更新时间:2024-03-05 GMT+08:00

下载对象

功能介绍

GET操作从对象存储下载对象。使用GET接口前,请确认必须拥有对象的READ权限。如果对象Owner向匿名用户授予READ访问权限,则可以在不使用鉴权头域的情况下访问该对象。

服务端加密

如果客户端的对象上传时,使用了客户提供的加密密钥进行服务端加密,当下载对象时,同样也必须在消息中提供密钥。

多版本

默认情况下,获取的是最新版本的对象。如果最新版本的对象是删除标记,则返回对象不存在。如果要获取指定版本的对象,请求可携带versionId消息参数。

冷存储对象

如果要下载的对象是冷存储类对象,由于对象存储在存档设备中,您必须先使用对象恢复,然后才能下载该冷存储对象。对象处于不同的恢复状态时,给出不同响应:如果对象已恢复,下载对象成功时需要返回x-obs-restore头域指示恢复失效时间。对未恢复或正在恢复的冷存储对象发送下载请求时,会返回错误403 Forbidden。

请求消息样式

1
2
3
4
5
6
GET /ObjectName HTTP/1.1 
Host: bucketname.obs.region.example.com
Date: date
Authorization: authorization
Range:bytes=byte_range 
<Optional Additional Header>

其中Range字段可选,如果没有的话得到全部内容。

请求消息参数

GET操作获取对象内容时,允许用户通过请求参数的方式对一些消息头值进行重写,可以重写的消息头有:Content-Type、Content-Language、Expires、Cache-Control、Content-Disposition以及Content-Encoding共6个。另外所需恢复的对象拥有多个版本时,可以通过versionId参数,指定需要下载的版本。具体的说明如表1所示。

OBS不会处理请求中携带的Accept-Encoding,也不会对上传的数据做任何压缩、解压的操作,压缩解压的操作由客户端决定。某些HTTPClient在默认情况下可能会根据服务端返回的Content-Encoding对数据做相应的解压处理,客户端程序需要根据自己的需求决定是否做解压处理以及如何解压(修改OBS端保存的对象元数据Content-Encoding或者在下载对象时对Content-Encoding进行重写)。如果在下载对象的请求中指明了重写消息头,OBS返回的HTTP标准消息头中将以请求中指定的重写内容为准。

表1 请求消息参数

参数名称

描述

是否必选

response-content-type

重写响应中的Content-Type头。

类型:String

response-content-language

重写响应中的Content-Language头。

类型:String

response-expires

重写响应中的Expires头。

类型:String

response-cache-control

重写响应中的Cache-Control头。

类型:String

response-content-disposition

重写响应中的Content-Disposition头。

类型:String

示例:

response-content-disposition=attachment; filename*=utf-8''name1

下载对象重命名为“name1”,如果name1中存在中文,需要将中文进行URL编码。

response-content-encoding

重写响应中的Content-Encoding头。

类型:String

versionId

指定获取对象的版本号。

类型:String

attname

重写响应中的Content-Disposition头。

类型:String

示例:

attname=name1

下载对象重命名为“name1”。

请求消息头

该请求除使用公共消息头外,还可以使用附加的消息头来完成获取对象的功能,消息头的意义如表2所示。

表2 请求消息头

消息头名称

描述

是否必选

Range

获取对象时,获取在Range范围内的对象内容。如果Range不合法则忽略此字段获取整个对象。

Range是一个范围,它的起始值最小为0,最大为对象长度减1。Range范围的起始值为必填项,如果Range只包含起始值,表示获取起始值到对象长度减1这个区间的对象内容。

携带Range头域后,响应消息的ETag仍是对象的ETag,而不是Range范围内对象的ETag。

类型:String

bytes=byte_range

示例1:bytes=0-4

示例2:bytes=1024

示例3:bytes=10-20,30-40(表示多个区间)

If-Modified-Since

如果对象在请求中指定的时间之后有修改,则返回对象内容;否则的话返回304(not modified)。

类型:符合http://www.ietf.org/rfc/rfc2616.txt规定格式的HTTP时间字符串。

If-Unmodified-Since

如果对象在请求中指定的时间之后没有修改,则返回对象内容;否则的话返回412(precondition failed)。

类型:符合http://www.ietf.org/rfc/rfc2616.txt规定格式的HTTP时间字符串。

If-Match

如果对象的ETag和请求中指定的ETag相同,则返回对象内容,否则的话返回412(precondition failed)。

类型:String

(ETag值,例:0f64741bf7cb1089e988e4585d0d3434。)

If-None-Match

如果对象的ETag和请求中指定的ETag不相同,则返回对象内容,否则的话返回304(not modified)。

类型:String

(ETag值,例:0f64741bf7cb1089e988e4585d0d3434。)

x-obs-server-side-encryption-customer-algorithm

SSE-C方式下使用该头域,该头域表示加密使用的算法。

类型:String

示例:x-obs-server-side-encryption-customer-algorithm:AES256

约束:需要和x-obs-server-side-encryption-customer-key, x-obs-server-side-encryption-customer-key-MD5一起使用。

否。当使用SSE-C方式时,必选。

x-obs-server-side-encryption-customer-key

SSE-C方式下使用该头域,该头域表示加密使用的密钥。该密钥用于解密对象。

类型:String

示例:x-obs-server-side-encryption-customer-key:K7QkYpBkM5+hca27fsNkUnNVaobncnLht/rCB2o/9Cw=

约束:该头域由256-bit的密钥经过base64-encoded得到,需要和x-obs-server-side-encryption-customer-algorithm,x-obs-server-side-encryption-customer-key-MD5一起使用。

否。当使用SSE-C方式时,必选。

x-obs-server-side-encryption-customer-key-MD5

SSE-C方式下使用该头域,该头域表示加密使用的密钥的MD5值。MD5值用于验证密钥传输过程中没有出错。

类型:String

示例:x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ==

约束:该头域由密钥的128-bit MD5值经过base64-encoded得到,需要和x-obs-server-side-encryption-customer-algorithm,x-obs-server-side-encryption-customer-key一起使用。

否。当使用SSE-C方式时,必选。

请求消息元素

该请求消息中不使用消息元素。

响应消息样式

1
2
3
4
5
6
7
8
HTTP/1.1 status_code 
Content-Type: type 
Date: date 
Content-Length: length 
Etag: etag 
Last-Modified: time 

<Object Content>

响应消息头

该请求的响应消息使用公共消息头,具体请参考表1

除公共响应消息头之外,还可能使用如下表3中的消息头。

表3 附加响应消息头

消息头名称

描述

x-obs-expiration

当对象单独设置了对象lifecycle,过期时间以对象lifecycle为准,该消息头用expiry-date描述对象的详细过期信息;如果对象没有设置对象lifecycle,设置了桶级别lifecycle,过期时间以桶级别lifecycle为准,该消息头用expiry-date和rule-id两个键值对描述对象的详细过期信息;否则不显示该头域。

类型:String

x-obs-website-redirect-location

当桶设置了Website配置,就可以设置对象元数据的这个属性,Website接入点返回301重定向响应,将请求重定向到该属性指定的桶内的另一个对象或外部的URL。

类型:String

x-obs-delete-marker

标识对象是否是删除标记。如果不是,则响应中不会出现该消息头。

类型:Boolean

有效值:true|false

默认值:false

x-obs-version-id

对象的版本号。如果该对象无版本号,则响应中不会出现该消息头。

有效值:字符串

默认值:无

x-obs-server-side-encryption

如果服务端加密是SSE-KMS方式,响应包含该头域。

类型:String

示例:x-obs-server-side-encryption:kms

x-obs-server-side-encryption-kms-key-id

如果服务端加密是SSE-KMS方式,响应包含该头域,该头域表示主密钥。

类型:String

格式为: regionID:domainID(租户ID):key/key_id

其中regionID是使用密钥所属region的ID;domainID是使用密钥所属租户的租户ID;key_id是本次加密使用的密钥ID。

示例: x-obs-server-side-encryption-kms-key-id:region:domainiddomainiddomainiddoma0001:key/4f1cd4de-ab64-4807-920a-47fc42e7f0d0

x-obs-server-side-encryption-customer-algorithm

如果服务端加密是SSE-C方式,响应包含该头域,该头域表示解密使用的算法。

类型:String

示例:x-obs-server-side-encryption-customer-algorithm:AES256

x-obs-server-side-encryption-customer-key-MD5

如果服务端加密是SSE-C方式,响应包含该头域,该头域表示解密使用的密钥的MD5值。

类型:String

示例:x-obs-server-side-encryption-customer-key-MD5:4XvB3tbNTN+tIEVa0/fGaQ==

x-obs-object-type

对象为非Normal对象时,会返回此头域,可取值为:Appendable。

类型:String

x-obs-next-append-position

对象为Appendable对象时,会返回此头域。

类型:Integer

响应消息元素

该请求的响应消息中不带消息元素。

错误响应消息

无特殊错误,所有错误已经包含在表2中。

请求示例:下载整个对象

1
2
3
4
5
6
GET /object01 HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: WED, 01 Jul 2015 04:24:33 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:NxtSMS0jaVxlLnxlO9awaMTn47s=

响应示例:下载整个对象

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 8DF400000163D3F2A89604C49ABEE55E
Accept-Ranges: bytes
ETag: "3b46eaf02d3b6b1206078bb86a7b7013"
Last-Modified: WED, 01 Jul 2015 01:20:29 GMT
Content-Type: binary/octet-stream
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSQwxJ2I1VvxD/Xgwuw2G2RQax30gdXU
Date: WED, 01 Jul 2015 04:24:33 GMT
Content-Length: 4572

[4572 Bytes object content]

请求示例:指定Range下载对象

指定Range下载对象(下载对象单个区间内容

1
2
3
4
5
6
7
GET /object01 HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: Mon, 14 Sep 2020 09:59:04 GMT
Range:bytes=20-30
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:mNPLWQMDWg30PTkAWiqJaLl3ALg=

指定Range下载对象(下载对象多个区间内容

1
2
3
4
5
6
7
GET /object01 HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: Mon, 14 Sep 2020 10:02:43 GMT
Range:bytes=20-30,40-50
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:ZwM7Vk2d7sD9o8zRsRKehgKQDkk=

响应示例:指定Range下载对象

指定Range下载对象(下载对象单个区间内容

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
HTTP/1.1 206 Partial Content
Server: OBS
x-obs-request-id: 000001748C0DBC35802E360C9E869F31
Accept-Ranges: bytes
ETag: "2200446c2082f27ed2a569601ca4e360"
Last-Modified: Mon, 14 Sep 2020 01:16:20 GMT
Content-Range: bytes 20-30/4583
Content-Type: binary/octet-stream
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSn2JHu4okx9NBRNZAvBGawa3lt3g31g
Date: Mon, 14 Sep 2020 09:59:04 GMT
Content-Length: 11

[ 11 Bytes object content]

指定Range下载对象(下载对象多个区间内容

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
HTTP/1.1 206 Partial Content
Server: OBS
x-obs-request-id: 8DF400000163D3F2A89604C49ABEE55E
Accept-Ranges: bytes
ETag: "2200446c2082f27ed2a569601ca4e360"
Last-Modified: Mon, 14 Sep 2020 01:16:20 GMT
Content-Type: multipart/byteranges;boundary=35bcf444-e65f-4c76-9430-7e4a68dd3d26
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSIBWFOVW8eeWujkqSnoIANC2mNR1cdF
Date: Mon, 14 Sep 2020 10:02:43 GMT
Content-Length: 288

--35bcf444-e65f-4c76-9430-7e4a68dd3d26
Content-type: binary/octet-stream
Content-range: bytes 20-30/4583
[ 11 Bytes object content]
--35bcf444-e65f-4c76-9430-7e4a68dd3d26
Content-type: binary/octet-stream
Content-range: bytes 40-50/4583
[ 11 Bytes object content]
--35bcf444-e65f-4c76-9430-7e4a68dd3d26

请求示例:判断对象Etag值

如果对象Etag值匹配则下载该对象

1
2
3
4
5
6
7
GET /object01 HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: WED, 01 Jul 2015 04:24:33 GMT
If-Match: 682e760adb130c60c120da3e333a8b09
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:NxtSMS0jaVxlLnxlO9awaMTn47s=

响应示例:判断对象Etag值,Etag不匹配

如果存储的对象的Etag值不是682e760adb130c60c120da3e333a8b09,则提示下载失败

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
HTTP/1.1 412 Precondition Failed
Server: OBS
x-obs-request-id: 8DF400000163D3F2A89604C49ABEE55E
Content-Type: application/xml
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSQwxJ2I1VvxD/Xgwuw2G2RQax30gdXU
Date: WED, 01 Jul 2015 04:20:51 GMT

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Error>
  <Code>PreconditionFailed</Code>
  <Message>At least one of the pre-conditions you specified did not hold</Message> 
  <RequestId>8DF400000163D3F2A89604C49ABEE55E</RequestId>      
  <HostId>ha0ZGaSKVm+uLOrCXXtx4Qn1aLzvoeblctVXRAqA7pty10mzUUW/yOzFue04lBqu</HostId>
  <Condition>If-Match</Condition>
</Error>

响应示例:判断对象Etag值匹配,下载成功

如果存储的对象的Etag值是682e760adb130c60c120da3e333a8b09,则下载成功

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 5DEB00000164A21E1FC826C58F6BA001
Accept-Ranges: bytes
ETag: "682e760adb130c60c120da3e333a8b09"
Last-Modified: Mon, 16 Jul 2015 08:03:34 GMT
Content-Type: application/octet-stream
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSbkdml1sLSvKnoHaRcOwRI+6+ustDwk
Date: Mon, 16 Jul 2015 08:04:00 GMT
Content-Length: 8

[ 8 Bytes object content]

请求示例:在URL中携带签名下载对象

GET /object02?AccessKeyId=H4IPJX0TQTHTHEBQQCEC&Expires=1532688887&Signature=EQmDuOhaLUrzrzRNZxwS72CXeXM%3D HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: Fri, 27 Jul 2018 10:52:31 GMT

响应示例:在URL中携带签名下载对象

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 804F00000164DB5E5B7FB908D3BA8E00
ETag: "682e760adb130c60c120da3e333a8b09"
Last-Modified: Mon, 16 Jul 2015 08:03:34 GMT
Content-Type: application/octet-stream
x-obs-id-2: 32AAAUJAIAABAAAQAAEAABAAAQAAEAABCTlpxILjhVK/heKOWIP8Wn2IWmQoerfw
Date: Fri, 27 Jul 2018 10:52:31 GMT
Content-Length: 8

[ 8 Bytes object content]

请求示例:下载对象并重命名,使用response-content-disposition参数

下载对象并重命名,使用response-content-disposition参数实现

1
2
3
4
5
6
GET /object01?response-content-disposition=attachment; filename*=utf-8''name1 HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: WED, 01 Jul 2015 04:24:33 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:NxtSMS0jaVxlLnxlO9awaMTn47s=

响应示例:下载对象并重命名,使用response-content-disposition参数

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 804F00000164DB5E5B7FB908D3BA8E00
ETag: "682e760adb130c60c120da3e333a8b09"
Last-Modified: Mon, 16 Jul 2015 08:03:34 GMT
Content-Type: application/octet-stream
x-obs-id-2: 32AAAUJAIAABAAAQAAEAABAAAQAAEAABCTlpxILjhVK/heKOWIP8Wn2IWmQoerfw
Date: Fri, 27 Jul 2018 10:52:31 GMT
Content-Length: 8
Content-Disposition: attachment; filename*=utf-8''name1

[ 8 Bytes object content]

请求示例:下载对象并重命名,使用attname参数

下载对象并重命名,使用attname参数实现

1
2
3
4
5
6
GET /object01?attname=name1 HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.example.com
Accept: */*
Date: WED, 01 Jul 2015 04:24:33 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:NxtSMS0jaVxlLnxlO9awaMTn47s=

响应示例:下载对象并重命名,使用attname参数

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 804F00000164DB5E5B7FB908D3BA8E00
ETag: "682e760adb130c60c120da3e333a8b09"
Last-Modified: Mon, 16 Jul 2015 08:03:34 GMT
Content-Type: application/octet-stream
x-obs-id-2: 32AAAUJAIAABAAAQAAEAABAAAQAAEAABCTlpxILjhVK/heKOWIP8Wn2IWmQoerfw
Date: Fri, 27 Jul 2018 10:52:31 GMT
Content-Length: 8
Content-Disposition: attachment; filename*=utf-8''name1

[ 8 Bytes object content]