GET Object

描述

此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, 它放在名字为 examplebucket 的 bucket 中，那么你可以认为资源逻辑名称为 /examplebucket/photos/2006/February/sample.jpg。

权限

该接口操作需要用户对Object拥有READ权限。如果请求的 object 不存在，KS3将根据你是否拥有读权限返回相应信息。

• 如果你拥有该Bucket的READ权限，KS3将会返回的 HTTP 状态码为404(no such key)错误。
• 如果你并不拥有该Bucket的READ权限，KS3将会返回的 HTTP 状态码为403(access denied)错误。
• 响应头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

注意：

• endpoint与Region对应关系
• SignatureValue签名算法

请求参数

有时也许你需要在 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。否则，返回304状态码 类型：String 默认值：None 约束条件：无	否
If-Unmodified-Since	如果 object 在指定时间后没有被改变，则返回 object。否则，返回412状态码 类型：String 默认值：None 约束条件：无	否
If-Match	如果 object 的 ETag(entity tag)与指定值一致，则返回 object。否则，返回412状态码 类型：String 默认值：None 约束条件：无	否
If-None-Match	如果 object 的 ETag(entity tag)与指定值不一致，则返回 object。否则，返回304状态码 类型：String 默认值：None 约束条件：无	否

请求内容

该接口不使用请求内容。

响应

响应头部

名称	描述
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 Object或Post Object请求创建的Object，ETag值是其内容的MD5值；对于分块上传方式创建的Object，ETag值是每个分块的MD5值进行字符串拼接后再次计算所得到的MD5值。ETag值可以用于检查Object内容是否发生变化。 类型: String
x‑kss‑tagging‑count	对象关联的标签的个数。仅当用户有读取标签权限时返回。 类型：String

响应内容

该接口不返回响应内容。

特殊错误

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

示例

请求示例

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: close
Server: Tengine
Content-MD5:eYMI+WOOpbKNXyXk1nf/rA==
[434234 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 发送签名。