对象 API

本章介绍对象相关的接口

PUT Object

上传一个对象到桶中，如果已有则覆盖。当开启了版本控制，同一个名称的对象可以在系统中保留多个版本，系统会为每次上传的对象生成一个version ID并保留每个版本。

请求语法

  1. PUT /bucketname/ObjectName HTTP/1.1
  2. Host: ip:port
  3. Date: date
  4. Authorization: authorization string

请求头部

--Cache-Control

指定请求/响应链中的缓存属性。

--Content-Disposition

当获取对象时，该属性提示将对象保存为的文件名。

--Content-Encoding

对象的附加编码类型，例如压缩文档使用的gzip类型。

--Content-MD5

对象内容（不包含头部）的MD5值经过BASE64编码后的字符串，服务端收到对象后也会做同样的计算，比较Content-MD5和服务端计算得出的结果，可以防止上传的对象内容被篡改或不完整。

--Content-Type

请求内容的MIME类型。

--Expect

当expect设置为100-continue，发送put object的请求时并不立刻发送对象内容，而是等收到100临时响应或等待超时再发送。

--Expires

缓存的超时时间。

--x-amz-meta-*

自定义元数据

结果解析

响应信息通过header返回。

--ETag

对象内容的MD5值转换为16进制之后生成的字符串。

--x-amz-version-id

版本号，当版本控制状态为Enabled，该字段返回此次上传对象的版本号，当版本控制状态为Suspended，该字段返回“null”，当未开启或禁用版本控制，该字段不返回。

样例

上传一个对象。

  1. PUT /bucketname/my-image.jpg HTTP/1.1
  2. Host: ip:port
  3. Date: Sat, 17 Aug 2019 17:50:00 GMT
  4. Authorization: authorization string
  5. Content-Type: text/plain
  6. Content-Length: 11434
  7. Expect: 100-continue
  8. [11434 bytes of object data]

响应结果

  1. HTTP/1.1 100 Continue
  3. HTTP/1.1 200 OK
  4. Date: Sat, 17 Aug 2019 17:50:00 GMT
  5. ETag: "1b2cf535f27731c974343645a3985328"
  6. Content-Length: 0

PUT Object - Copy

从系统中已有的对象拷贝到目标对象，不需要从本地上传对象内容。

请求语法

  1. PUT /destinationbucket/destinationObject HTTP/1.1
  2. Host: ip:port
  3. x-amz-copy-source: /source_bucket/sourceObject
  4. x-amz-metadata-directive: metadata_directive
  5. x-amz-copy-source-if-match: etag
  6. x-amz-copy-source-if-none-match: etag
  7. x-amz-copy-source-if-unmodified-since: time_stamp
  8. x-amz-copy-source-if-modified-since: time_stamp
  9. <request metadata>
  10. Authorization: authorization string

请求头部

--x-amz-copy-source

必须携带的头部。

复制对象的源对象地址，包含源存储桶和源对象，例如：/source_bucket/sourceObject ，默认复制源对象的最新版本，如果要指定版本复制，则需要增加版本号，例如：/source_bucket/sourceObject?versionId=3344 。

--x-amz-metadata-directive

指定是否从源对象复制元数据到目标对象。当指定为COPY时，从源对象复制元数据到目标对象，当指定为REPLACE时，源对象的元数据都不会复制到目标对象，目标对象使用复制对象请求中携带的元数据。

取值：COPY|REPLACE

默认值：COPY

--x-amz-copy-if-modified-since

时间，只有当源对象的创建时间在此时间后才进行复制。

--x-amz-copy-if-unmodified-since

时间，只有当源对象的创建时间在此之前才进行复制。

--x-amz-copy-if-match

ETag，只有当源对象的ETag与此ETag匹配才进行复制。

--x-amz-copy-if-none-match

ETag，只有当源对象的ETag与此ETag不匹配才进行复制。

--Cache-Control

指定请求/响应链中的缓存属性。

--Content-Disposition

当获取对象时，该属性提示将对象保存为的文件名。

--Content-Encoding

对象的附加编码类型，例如压缩文档使用的gzip类型。

--Content-MD5

对象内容（不包含头部）计算MD5值后经过BASE64编码后的字符串，服务端收到对象后也会做同样的计算，比较Content-MD5和服务端计算得出的结果是否一致，可以防止上传的对象内容被篡改或不完整。

--Expires

缓存的超时时间。

--x-amz-meta-*

自定义元数据

结果解析

版本号在响应header中体现。

--x-amz-version-id

复制后生成对象的版本号。

--x-amz-copy-source-version-id

源对象的版本号。

复制后对象的ETag和创建时间在消息体中以XML形式体现。

--CopyObjectResult

容器，包含ETag和LastModified。

--ETag

新对象内容计算MD5值后转换为16进制得到的字符串，与源对象一致。

--LastModified

新对象的创建时间。

样例

复制指定的版本。

  1. PUT /bucketname/my-second-image.jpg HTTP/1.1
  2. Host: ip:port
  3. Date: Sat, 17 Aug 2019 17:50:00 GMT
  4. x-amz-copy-source: /bucketname/my-image.jpg?versionId=3344
  5. Authorization: authorization string

响应结果

  1. HTTP/1.1 200 OK
  2. x-amz-version-id:5656
  3. x-amz-copy-source-version-id:3344
  4. Date: Sat, 17 Aug 2019 17:50:00 GMT
  6. <CopyObjectResult>
  7.    <LastModified>2019-08-17T17:50:00</LastModified>
  8.    <ETag>"9b2cf535f27731c974343645a3985328"</ETag>
  9. </CopyObjectResult>

GET Object

获取对象内容。

请求语法

  1. GET /bucketname/ObjectName HTTP/1.1
  2. Host: ip:port
  3. Date: date
  4. Authorization: authorization string

请求参数

通过URL参数指定请求参数。

--versionId

获取指定版本的对象时通过此参数指定版本号。

--response-content-type

指定响应消息中的Content-Type头部值。

--response-content-language

指定响应消息中的Content-Language头部值。

--response-expires

指定响应消息中的Expires头部值。

--response-cache-control

指定响应消息中的Cache-Control头部值。

--response-content-disposition

指定响应消息中的Content-Disposition头部值。

--response-content-encoding

指定响应消息中的Content-Encoding头部值。

请求头部

--Range

下载指定位置的字节数。

--If-Modified-Since

指定时间，只有在指定时间之后更新过，才返回对象，否则返回304.

--If-Unmodified-Since

指定时间，只有在指定时间之前未更新，才返回对象，否则返回412.

--If-Match

指定ETag，只有对象的ETag和ETag匹配，才返回对象，否则返回412.

--If-None-Match

指定ETag，只有对象的ETag和ETag不匹配，才返回对象，否则返回304.

结果解析

响应信息通过header返回。

--x-amz-version-id

获取的对象的版本号。

--x-amz-meta-*

对象的自定义元数据，与上传对象时的设置一致。

--x-amz-delete-marker

当获取的对象是一个删除标记，响应中会携带该头部且值为true，当获取的对象不是删除标记，该头部不会携带。

样例

样例1：获取一个对象

  1. GET /bucketname/ObjectName HTTP/1.1
  2. Host: ip:port
  3. Date: Sat, 17 Aug 2019 17:50:00 GMT
  4. Authorization: authorization string

响应结果

  1. HTTP/1.1 200 OK
  2. Date: Sat, 17 Aug 2019 17:50:00 GMT
  3. Last-Modified: Sat, 17 Aug 2019 17:40:00 GMT
  4. ETag: "fba9dede5f27731c9771645a39863328"
  5. Content-Length: 434234
  7. [434234 bytes of object data]

样例2：指定版本号获取一个对象

  1. GET /bucketname/myObject?versionId=4433 HTTP/1.1
  2. Host: ip:port
  3. Date: Sat, 17 Aug 2019 17:50:00 GMT
  4. Authorization: authorization string

响应结果

  1. HTTP/1.1 200 OK
  2. Date: Sat, 17 Aug 2019 17:50:00 GMT
  3. Last-Modified: Sat, 17 Aug 2019 17:40:00 GMT
  4. x-amz-version-id: 4433
  5. ETag: "fba9dede5f27731c9771645a39863328"
  6. Content-Length: 434234
  7. Content-Type: text/plain
  9. [434234 bytes of object data]

HEAD Object

获取对象的元数据信息，不获取对象内容。

请求语法

  1. HEAD /bucketname/ObjectName HTTP/1.1
  2. Host: ip:port
  3. Authorization: authorization string

请求参数

通过URL参数指定请求参数。

--versionId

获取指定版本的对象时通过此参数指定版本号。

请求头部

--Range

下载指定位置的字节数。

--If-Modified-Since

指定时间，只有在指定时间之后更新过，才返回对象，否则返回304.

--If-Unmodified-Since

指定时间，只有在指定时间之前未更新，才返回对象，否则返回412.

--If-Match

指定ETag，只有对象的ETag和ETag匹配，才返回对象，否则返回412.

--If-None-Match

指定ETag，只有对象的ETag和ETag不匹配，才返回对象，否则返回304.

结果解析

响应信息通过header返回。

--x-amz-version-id

获取的对象的版本号。

--x-amz-meta-*

对象的自定义元数据，与上传对象时的设置一致。

样例

样例1：获取对象的元数据

  1. HEAD /bucketname/my-image.jpg HTTP/1.1
  2. Host: ip:port
  3. Date: Sat, 17 Aug 2019 17:50:00 GMT
  4. Authorization: authorization string

响应结果

  1. HTTP/1.1 200 OK
  2. x-amz-version-id: 3344
  3. Date: Sat, 17 Aug 2019 17:50:00 GMT
  4. Last-Modified: Sat, 17 Aug 2019 17:40:00 GMT
  5. ETag: "fba9dede5f27731c9771645a39863328"
  6. Content-Length: 434234
  7. Content-Type: text/plain

样例2：获取指定版本对象的元数据

  1. HEAD /bucketname/my-image.jpg?versionId=3344 HTTP/1.1
  2. Host: ip:port
  3. Date: Sat, 17 Aug 2019 17:55:00 GMT
  4. Authorization: authorization string

响应结果

  1. HTTP/1.1 200 OK
  2. x-amz-version-id: 3344
  3. Date: Sat, 17 Aug 2019 17:55:00 GMT
  4. Last-Modified: Sat, 17 Aug 2019 17:40:00 GMT
  5. ETag: "fba9dede5f27731c9771645a39863328"
  6. Content-Length: 434234
  7. Content-Type: text/plain

DELETE Object

删除对象。

当打开了版本控制，删除对象实际会生成一个删除标记，原来的对象还保存在系统中。

当指定版本号删除时，找到对应的版本后会永久删除该版本。

请求语法

  1. DELETE /bucketname/ObjectName HTTP/1.1
  2. Host: ip:port
  3. Date: date
  4. Authorization: authorization string

请求参数

通过URL参数指定请求参数。

--versionId

删除指定版本的对象时通过此参数指定版本号。

结果解析

响应信息通过header返回。

--x-amz-delete-marker

当删除操作生成了一个删除标记，会返回该头部且值为true。

当指定版本号删除时，如果删除的是一个删除标记，会返回该头部且值为true。

--x-amz-version-id

当删除操作生成了一个删除标记，该头部记录删除标记的版本号。当指定版本删除对象时，该头部记录被删除的版本号。

样例

样例1：删除一个未开启版本控制的桶内的对象

  1. DELETE /bucketname/my-second-image.jpg HTTP/1.1
  2. Host: ip:port
  3. Date: Sat, 17 Aug 2019 17:55:00 GMT
  4. Authorization: authorization string
  5. Content-Type: text/plain

响应结果

  1. HTTP/1.1 204 NoContent
  2. Date: Sat, 17 Aug 2019 17:55:00 GMT
  3. Content-Length: 0

样例2：删除指定版本对象

  1. DELETE /bucketname/my-third-image.jpg?versionId=4455 HTTP/1.1
  2. Host: ip:port
  3. Date: Sat, 17 Aug 2019 17:58:00 GMT
  4. Authorization: authorization string

响应结果

  1. HTTP/1.1 204 NoContent
  2. x-amz-version-id: 4455
  3. Date: Sat, 17 Aug 2019 17:58:00 GMT
  4. Content-Length: 0

Initiate Multipart Upload

初始化分段上传，获得upload ID。

请求语法

  1. POST /bucketname/ObjectName?uploads HTTP/1.1
  2. Host: ip:port
  3. Date: date
  4. Authorization: authorization string

请求头部

初始化时携带的元数据，在合并分段上传生成一个完整对象时作为对象的元数据。

--Cache-Control

指定请求/响应链中的缓存属性。

--Content-Disposition

当获取对象时，该属性提示将对象保存为的文件名。

--Content-Encoding

对象的附加编码类型，例如压缩文档使用的gzip类型。

--Content-Type

请求内容的MIME类型。

--Expires

缓存的超时时间。

--x-amz-meta-*

自定义元数据

结果解析

响应消息体中返回XML形式的结果，包含upload ID。

--InitiateMultipartUploadResult

容器，包含初始化分段的结果。

--Bucket

初始化分段上传对象所在存储桶。

--Key

初始化分段上传的对象名称。

--UploadId

初始化分段上传的ID，用来唯一标识一个分段上传请求。

样例

响应结果

  1. HTTP/1.1 200 OK
  2. Date: Sat, 17 Aug 2019 17:59:00 GMT
  3. Content-Length: 151
  5. <InitiateMultipartUploadResult>
  6.   <Bucket>bucketname</Bucket>
  7.   <Key>ObjectName</Key>
  8.   <UploadId>56778</UploadId>
  9. </InitiateMultipartUploadResult>

Upload Part

上传分段。

请求语法

  1. PUT /bucketname/ObjectName?partNumber=PartNumber&uploadId=UploadId HTTP/1.1
  2. Host: ip:port
  3. Date: date
  4. Content-Length: Size
  5. Authorization: authorization string

请求参数

--partNumber

分段编号，有效范围：1-10000

--uploadId

upload ID，在Initiate Multipart Upload获得。

样例

上传一个分段

  1. PUT /bucketname/ObjectName?partNumber=1&uploadId=56778 HTTP/1.1
  2. Host: ip:port
  3. Date: Sat, 17 Aug 2019 18:05:00 GMT
  4. Content-Length: 10485760
  5. Content-MD5: pUNXr/BjKK5G2UKvaRRrOA==
  6. Authorization: authorization string
  8. ***part data omitted***

响应结果

  1. HTTP/1.1 200 OK
  2. Date: Sat, 17 Aug 2019 18:05:00 GMT
  3. ETag: "b54357faf0632cce46e942fa68356b38"
  4. Content-Length: 0

List Parts

查询分段列表。

请求语法

  1. GET /bucketname/ObjectName?uploadId=UploadId HTTP/1.1
  2. Host: ip:port
  3. Date: Date
  4. Authorization: authorization string

请求参数

--uploadId

upload ID，在Initiate Multipart Upload获得。

--max-parts

一次返回的最大分段数。

--part-number​-marker

查询的起始位置。

--encoding-type

响应结果编码类型，只支持url。由于对象名称可以包含任意字符，但是XML对某些特别的字符无法解析，所以需要对响应中的对象名称进行编码。

结果解析

在消息体中以XML形式返回查询结果。

--ListPartsResult

--Bucket

分段上传的存储桶名称。

--Key

分段上传的对象名称。

--UploadId

分段上传请求的upload ID。

--Initiator

分段上传的发起者。

--Owner

存储桶的拥有者。

--DisplayName

用户的名称。

--ID

用户的ID。

--PartNumberMarker

查询的part-number​-marker条件。

--MaxParts

查询的max-parts条件。

--IsTruncated

是否被截断。

--NextPartNumberMarker

当IsTruncated为true时，该字段记录下一次查询的起始位置。

--Encoding-Type

查询的encoding-type条件。

--Part

容器，包含分段内容。

--PartNumber

分段编号。

--LastModified

分段的最新修改时间。

--ETag

分段的ETag。

--Size

分段的大小。

样例

查询upload ID为56778的分段列表，指定max-parts为2，part-number-marker为1。

  1. GET /bucketname/ObjectName?uploadId=56778&max-parts=2&part-number-marker=1 HTTP/1.1
  2. Host: ip:port
  3. Date: Sat, 17 Aug 2019 18:10:00 GMT
  4. Authorization: authorization string

响应结果

  1. HTTP/1.1 200 OK
  2. Date: Sat, 17 Aug 2019 18:10:00 GMT
  3. Content-Length: 838
  5. <ListPartsResult>
  6.   <Bucket>bucketname</Bucket>
  7.   <Key>ObjectName</Key>
  8.   <UploadId>56778</UploadId>
  9.   <Initiator>
  10.     <DisplayName>username</DisplayName>
  11.     <ID>34455</ID>
  12.   </Initiator>
  13.   <Owner>
  14.     <DisplayName>username</DisplayName>
  15.     <ID>34455</ID>
  16.   </Owner>
  17.   <PartNumberMarker>1</PartNumberMarker>
  18.   <NextPartNumberMarker>3</NextPartNumberMarker>
  19.   <MaxParts>2</MaxParts>
  20.   <IsTruncated>true</IsTruncated>
  21.   <Part>
  22.     <PartNumber>2</PartNumber>
  23.     <LastModified>2019-08-1T17:06:06.000Z</LastModified>
  24.     <ETag>"7778aef83f66abc1fa1e8477f296d394"</ETag>
  25.     <Size>10485760</Size>
  26.   </Part>
  27.   <Part>
  28.     <PartNumber>3</PartNumber>
  29.     <LastModified>2019-08-1T17:06:23.000Z</LastModified>
  30.     <ETag>"aaaa18db4cc2f85cedef654fccc4a4x8"</ETag>
  31.     <Size>10485760</Size>
  32.   </Part>
  33. </ListPartsResult>

Complete Multipart Upload

完成分段上传，合并分段。

请求语法

  1. POST /bucketname/ObjectName?uploadId=UploadId HTTP/1.1
  2. Host: ip:port
  3. Date: Date
  4. Content-Length: Size
  5. Authorization: authorization string
  7. <CompleteMultipartUpload>
  8.   <Part>
  9.     <PartNumber>PartNumber</PartNumber>
  10.     <ETag>ETag</ETag>
  11.   </Part>
  12.   ...
  13. </CompleteMultipartUpload>

请求元素

--CompleteMultipartUpload

包含所有要合并的的分段信息

--Part

一个分段

--PartNumber

分段编码

--ETag

分段的ETag

结果解析

响应消息体中包含XML形式的合并结果，包含合并后对象的ETag。

--CompleteMultipartUploadResult

合并分段结果。

--Location

合并后对象的地址

--Bucket

存储桶名称

--Key

对象名称

--ETag

合并后对象的ETag，不一定是合并后完整对象的MD5值。

样例

  1. POST /bucketname/ObjectName?uploadId=56778 HTTP/1.1
  2. Host: ip:port
  3. Date: Sat, 17 Aug 2019 18:10:30 GMT
  4. Content-Length: 391
  5. Authorization: authorization string
  7. <CompleteMultipartUpload>
  8.   <Part>
  9.     <PartNumber>1</PartNumber>
  10.     <ETag>"a54357aff0632cce46d942af68356b38"</ETag>
  11.   </Part>
  12.   <Part>
  13.     <PartNumber>2</PartNumber>
  14.     <ETag>"0c78aef83f66abc1fa1e8477f296d394"</ETag>
  15.   </Part>
  16.   <Part>
  17.     <PartNumber>3</PartNumber>
  18.     <ETag>"acbd18db4cc2f85cedef654fccc4a4d8"</ETag>
  19.   </Part>
  20. </CompleteMultipartUpload>

响应结果

  1. HTTP/1.1 200 OK
  2. Date: Sat, 17 Aug 2019 18:10:30 GMT
  4. <CompleteMultipartUploadResult>
  5.   <Location>http://ip:port/bucketname/ObjectName</Location>
  6.   <Bucket>bucketname</Bucket>
  7.   <Key>ObjectName</Key>
  8.   <ETag>"3858f62230ac3c915f300c664312c11f-9"</ETag>
  9. </CompleteMultipartUploadResult>

Abort Multipart Upload

取消分段上传。

请求语法

  1. DELETE /bucketname/ObjectName?uploadId=UploadId HTTP/1.1
  2. Host: ip:port
  3. Date: Date
  4. Authorization: authorization string

请求参数

--uploadId

待取消的upload ID。

样例

响应结果

  1. HTTP/1.1 204 OK
  2. Date: Sat, 17 Aug 2019 18:15:30 GMT
  3. Content-Length: 0