对象 API

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

    请求头部

    —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
    2.  
    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
    5.  
    6. <CopyObjectResult>
    7.    <LastModified>2019-08-17T17:50:00</LastModified>
    8.    <ETag>"9b2cf535f27731c974343645a3985328"</ETag>
    9. </CopyObjectResult>

    GET Object

    获取对象内容。

    请求语法

    1. Host: ip:port
    2. Date: date
    3. 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

    请求头部

    —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
    6.  
    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
    8.  
    9. [434234 bytes of object data]

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

    请求参数

    通过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

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

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

    样例

    响应结果

    上传分段。

    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
    7.  
    8. ***part data omitted***

    响应结果

    1. HTTP/1.1 200 OK
    2. Date: Sat, 17 Aug 2019 18:05:00 GMT
    3. 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
    4.  
    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
    6.  
    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
    6.  
    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
    3.  
    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>

    取消分段上传。

    请求语法

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

    请求参数

    —uploadId

    待取消的upload ID。

    响应结果