最近更新时间:2024-01-25 19:45:11
该接口表示从KS3获取某个文件(Object)。
如果授予匿名用户ks3:GetObject
权限,该操作可以不做签名。如果期望生成一个下载链接,可参考文档: 通过 URL QueryString 发送签名。
KS3的Bucket并不具有目录层次, 但是用户可以通过为Object Key赋予一个具有文件结构的值来实现逻辑分层。例如,对于sample.jpg,可以将它命名为 :photos/2006/February/sample.jpg。
使用此接口的用户,必须是Bucket拥有者或具有ks3:GetObject
权限。
响应头x‑kss‑tagging‑count
的返回需要用户具有读该对象标签的权限(ks3:GetObjectTagging
)。若用户仅有ks3:GetObject
权限,没有ks3:GetObjectTagging
权限,Get Object
请求的响应头将不会返回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 | 设置响应头部 | 否 |
response-content-language | 设置响应头部 | 否 |
response-expires | 设置响应头部 | 否 |
response-cache-control | 设置响应头部 | 否 |
response-content-disposition | 设置响应头部 | 否 |
response-content-encoding | 设置响应头部 | 否 |
该接口可以使用所有常用请求头部,此外,也可以使用下表所列请求头部。获取更多信息,请点击常用请求头部。
名称 | 描述 | 是否必选 |
---|---|---|
Range | 下载指定 | 否 |
If-Modified-Since | 如果 | 否 |
If-Unmodified-Since | 如果 | 否 |
If-Match | 如果 | 否 |
If-None-Match | 如果 | 否 |
若使用客户提供的加密密钥的服务器端加密,则需要使用以下请求头 。
名称 | 描述 |
---|---|
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-* | 如果你在
|
x-kss-storage-class | 如果文件存储类型为低频存储,值为
|
ETag | 用于标识
|
x‑kss‑tagging‑count | 对象关联的标签的个数。仅当用户有读取标签权限且Object有标签时返回。
|
x-kss-crr | 如果Object是从其他桶复制的文件,则会返回该响应头,对应的值为true。否则不返回该响应头。 |
x-kss-checksum-crc64ecma | 对象的CRC64值,用来做数据完整性校验。关于CRC64的计算标准,请参见文档:ECMA-182标准。
|
若使用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: "798308f9638ea5b28d5f25e4d677****"
x-kss-checksum-crc64ecma: 503054087537662****
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: "c2b04aae00a6f6b937511fa7382f****"
x-kss-checksum-crc64ecma: 503054087537662****
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加密时,请求中未提供客户密钥。 |
纯净模式