全部文档
当前文档

暂无内容

如果没有找到您期望的内容,请尝试其他搜索词

文档中心

GET Object

最近更新时间:2022-12-30 15:48:03

描述

此GET操作将从KS3获取object。你需要具有对文件的读权限。如果你授予匿名用户读权限,那么该操作可以不做签名。如果期望生成一个下载链接,可以参考 通过 URL QueryString 发送签名

KS3的bucket并不具有目录层次,类似于桌面电脑的文件目录。 但是,你可以通过为object key赋予一个具有文件结构的值来实现逻辑分层。例如,对于sample.jpg,你可以命名它为 photos/2006/February/sample.jpg

此GET操作,你可以通过指定object的全称来获取一个逻辑分层的object。例如,如果你拥有一个名称为 photos/2006/February/sample.jpg 的object, 它放在名字为 examplebucketbucket 中,那么你可以认为资源逻辑名称为 /examplebucket/photos/2006/February/sample.jpg

权限

  • 该接口操作需要用户对Object拥有READ权限。

  • 响应头x‑kss‑tagging‑count的返回需要访问者具有读该对象标签的权限(ks3:GetObjectTagging)。若当用户仅有ks3:GetObject权限,但没有ks3:GetObjectTagging权限时,GetObject请求的响应头不返回x-kss-tagging-count

    请求

    请求语法

    GET /{ObjectKey} HTTP/1.1
    Host: {BucketName}.{endpoint}
    Date: {date}
    Authorization: {SignatureValue}
    Range:bytes=byte_range

    注意:

    请求参数

    有时也许你需要在 GET 响应中返回某一个确定的响应头部值,比如,你可能需要在你的 GET 请求中设置响应头部 Content-Disposition 的值。

    你可以使用下表中所列出的查询参数来设置响应头部的值。只有当KS3返回200状态码时,设置的header才会生效。可以通过以下参数设置返回的Content-Type, Content-Language, Expires, Cache-Control, Content-Disposition, 和 Content-Encoding

参数 描述 是否必选
response-content-type 设置响应头部 Content-Type
类型:String
默认值:None
response-content-language 设置响应头部 Content-Language
类型:String
默认值:None
response-expires 设置响应头部 Expires
类型:String
默认值:None
response-cache-control 设置响应头部 Cache-Control
类型:String
默认值:None
response-content-disposition 设置响应头部 Content-Disposition
类型:String
默认值:None
response-content-encoding 设置响应头部 Content-Encoding
类型:String
默认值:None

请求头部

该接口可以使用所有常用请求头部,此外,也可以使用下表所列请求头部。获取更多信息,请点击常用请求头部

名称 描述 是否必选
Range 下载指定 range 字节的 object。更多关于HTTP Range 头部信息,请访问http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html##sec14.35
类型:String
默认值:None
约束条件:无
If-Modified-Since 如果 object 在指定时间后被修改,则返回 object,并返回200 OK。否则,返回304 Not Modified
时间格式:GMT,例如Wed, 12 Oct 2009 17:50:00 GMT
类型:String
默认值:None
约束条件:无
If-Unmodified-Since 如果 object 在指定时间后没有被修改,则返回 object,并返回200 OK。否则,返回412 Precondition Failed
时间格式:GMT,例如Wed, 12 Oct 2009 17:50:00 GMT
类型:String
默认值:None
约束条件:无
If-Match 如果 objectETag(entity tag)与指定值一致,则返回 object。否则,返回412状态码
类型:String
默认值:None
约束条件:无
If-None-Match 如果 objectETag(entity tag)与指定值不一致,则返回 object。否则,返回304状态码
类型:String
默认值:None
约束条件:无
加密相关请求头部
若使用客户提供的加密密钥的服务器端加密,则需要使用以下请求头 。 名称 描述
x-kss-server-side-encryption-customer-algorithm 客户端提供的加密算法,合法值:AES256
x-kss-server-side-encryption-customer-key 客户端提供的加密密钥
x-kss-server-side-encryption-customer-key-MD5 客户端提供的通过BASE64编码的通过128位MD5加密的密钥的MD5值

请求内容

该接口不使用请求内容。

响应

响应头部

名称 描述
Content-MD5 返回文件md5值的base64编码,前提条件为文件是通过PUT或POST上传到KS3;如果是分块上传的文件,将不会返回此响应头。
x-kss-meta-* 如果你在PUT Object中使用了用户元数据,格式为前缀 x-kss-meta- 后缀为你自定的字段,那么响应头部会返回它,并不解析。
类型:String
x-kss-storage-class 如果文件存储类型为低频存储,值为STANDARD_IA;如果文件存储类型为归档存储,值为ARCHIVE;如果文件存储类型为标准存储,不返回此响应头。
类型:String
ETag 用于标识Object内容的32位十六进制字符串,不同内容的Object对应着不同的ETag。对于Put ObjectPost Object请求创建的ObjectETag值是其内容的MD5值;对于分块上传方式创建的ObjectETag值是每个分块的MD5值进行字符串拼接后再次计算所得到的MD5值。ETag值可以用于检查Object内容是否发生变化。
类型: String
x‑kss‑tagging‑count 对象关联的标签的个数。仅当用户有读取标签权限且Object有标签时返回。
类型:String
x-kss-crr 如果Object是从其他桶复制的文件,则会返回该响应头,对应的值为true。否则不返回该响应头。
加密相关响应头部
若使用KS3 托管密钥的服务器端加密,则会返回以下响应头。 名称 描述
x-kss-server-side-encryption 如果数据通过KS3 托管密钥的服务器端加密,则响应头将包含该值
若使用客户提供的加密密钥的服务器端加密,则会返回以下响应头。 名称 描述
x-kss-server-side-encryption-customer-algorithm 如果请求数据通过客户提供的加密密钥的服务器端加密,则响应头将包含该值
x-kss-server-side-encryption-customer-key-MD5 如果请求数据通过客户提供的加密密钥的服务器端加密,则响应头将包含该值

响应内容

该接口返回的响应内容为对象(文件)。

特殊错误

该接口不返回任何特殊错误。

示例

简单GET请求示例

  GET /my-image.jpg HTTP/1.1
  Host: ks3-example.ks3-cn-beijing.ksyuncs.com
  Date: Fri, 26 Dec 2014 06:48:45 GMT
  Authorization: authorization string

响应示例

  HTTP/1.1 200 OK
  x-kss-request-id: 5a868ca0ebd74bcc8eff1f1a7c9bcd6c
  Date: Fri, 26 Dec 2014 06:48:46 GMT
  Last-Modified: Wed, 12 Oct 2009 17:50:00 GMT
  ETag: "798308f9638ea5b28d5f25e4d677ffac"
  Content-Length: 434234
  Content-Type: text/plain
  Connection: keep-alive
  Server: KS3
  Content-MD5:eYMI+WOOpbKNXyXk1nf/rA==
  [434234 bytes of object data]

带Range参数请求示例

  GET /my-image.jpg HTTP/1.1
  Host: ks3-example.ks3-cn-beijing.ksyuncs.com
  Date: Fri, 28 Dec 2014 07:48:41 GMT
Range: bytes=1-100
  Authorization: authorization string

响应示例

  HTTP/1.1 206 Partial Content
  x-kss-request-id: f8qbqt80h9robs74ctib1norlmluqccb
  Date: Fri, 28 Dec 2014 07:48:41 GMT
  Last-Modified: Wed, 12 Oct 2009 17:50:00 GMT
  ETag: "c2b04aae00a6f6b937511fa7382f6f8f"
  Content-Length: 100
  Content-Type: application/pdf
  Connection: keep-alive
  Accept-Ranges: bytes
  Content-Range: bytes 1-100/493132
  Server: KS3
  Content-MD5:wrBKrgCm9rk3UR+nOC9vjw==
  [100 bytes of object data]

注意:

1、如果文件通过分块上传保存在KS3,对文件调用GET接口时将不会返回Content_MD5响应头;

2、如果文件通过PUT或POST接口上传到KS3,对文件调用GET接口将会返回Content_MD5响应头。

接口细节分析

  • 当使用参数设置返回的header时,只有KS3返回200时才会生效。
  • 当设置Range下载时,注意Range的格式不能错,否则KS3会返回416。
  • x‑kss‑tagging‑count请求头的返回需要访问者具有读取标签的权限(ks3:GetObjectTagging )。即当用户仅有ks3:GetObject权限,但没有ks3:GetObjectTagging权限时,GetObject请求的响应头不返回示x-kss-tagging-count。
  • 对于私有文件想通过浏览器下载的需求,可以参考通过 URL QueryString 发送签名

    错误码

错误码 HTTP状态码 描述
InvalidObjectState 403 Object为归档存储类型时,未解冻或解冻中调用该接口。
No Such Key 404 请求的 Object 不存在。
Access Denied 403 用户没有该Object的READ权限。
InvalidArgument 400 提供了x-kss-server-side-encryption请求头。
Md5NotMatchForOldMd5 400 x-kss-copy-source-server-side-encryption-customer-key-MD5 不是 x-kss-copy-source-server-side-encryption-customer-key 的MD5值。
AlgorithmInvalidForCustomerKey 400 x-kss-server-side-encryption-customer-algorithm不是合法的AES256。
MissingCustomerKey 400 文件为SSE-C加密时,请求中未提供客户密钥。
文档导读
纯净模式常规模式

纯净模式

点击可全屏预览文档内容
文档反馈