大对象分块接口

初始化上传段任务

功能介绍

使用多段上传特性时，用户必须首先调用创建多段上传任务接口创建任务，系统会给用户返回一个全局唯一的多段上传任务号，作为任务标识。后续用户可以根据这个标识发起相关的请求，如：上传段、合并段、列举段等。创建多段上传任务不影响已有的同名对象；同一个对象可以同时存在多个多段上传任务。

请求语法

http

POST /<bucket-name>/<object-key>?uploads HTTP/1.1
Host: fgws3-ocloud.ihep.ac.cn
Date: <date>
Content-Length: 0
Content-Type: <content-type>
X-Amz-Content-Sha256: <content-sha256>
Authorization: <authorization-header>

请求头定义

参数	描述
x-amz-meta-	以该前缀开头的header都将被认为是用户自定义的元数据，比如：x-amz-meta-title: TITLE 这个header会把title:TITLE作为用户自定义元数据key-value对。类型：字符串默认：无

响应元素

参数	描述
InitiateMultipartUploadResult	响应容器参数类型：容器子节点：Key，Bucket
Key	对象的Key 类型：字符串父节点：InitiateMultipartUploadResult
Bucket	对象的桶类型：字符串父节点：InitiateMultipartUploadResult
UploadId	分块上传的ID，用这个ID来作为各块属于这个文件的标识类型：字符串父节点：InitiateMultipartUploadResult

请求消息示例

http

POST https://fgws3-ocloud.ihep.ac.cn/20001-cbq/S3test3.txt?uploads= HTTP/1.1
Host: fgws3-ocloud.ihep.ac.cn
Authorization: AWS4-HMAC-SHA256 Credential=PIM9Z4LAahZtba1BeLW2/20231128/us-east-1/s3/aws4_request, SignedHeaders=content-type;host;x-amz-content-sha256;x-amz-date, Signature=99d76bb2424b27b400ce90adaa58fc6ce8fd2fdf317e1c9c4c444db75baaa508
Content-Type: application/ocet-stream
X-Amz-Date: 20231128T083718Z
X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

响应消息示例

http

HTTP/1.1 200 OK
Server: JWanFS FGW Server
X-Amz-Request-Id: 1701160639352568301
Date: Tue, 28 Nov 2023 08:37:19 GMT
Accept-Ranges: bytes
Content-Length: 259
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<InitiateMultipartUploadResult
    xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Bucket>20001-cbq</Bucket>
    <Key>S3test3.txt</Key>
    <UploadId>e1a680618264019c2e98fb37f02e42bdafc892a7</UploadId>
</InitiateMultipartUploadResult>

上传段

多段上传任务创建后，用户可以通过指定多段上传任务号，通过上传段接口为特定的任务上传段，从客户端上传新数据。同一个对象的同一个多段上传任务在上传段时，上传的顺序对后续的合并操作没有影响，也即支持多个段并发上传。

段大小范围是[100KB，5GB]，但在进行合并段操作时，最后一个段的大小范围为[0,5GB]。上传的段的编号也有范围限制，其范围是[1,10000]。

请求语法

http

PUT /<bucket-name>/<object-key>?partNumber=<part-number>&uploadId=<upload-id> HTTP/1.1
Host: fgws3-ocloud.ihep.ac.cn
Date: <date>
Content-Length: <part-size>
Content-Type: <content-type>
X-Amz-Content-Sha256: <content-sha256>
Authorization: <authorization-header>

<part-data>

请求头定义

参数	描述	是否必须
Content-Length	Entity Body的长度类型：整型默认：无	是
Content-MD5	Entity Body的MD5摘要类型：字符串默认：无	否

特殊错误码

错误码	Http状态码	描述
NoSuchUpload	404 Not Found	对应的分块上传不存在，可能原因：uploadId非法、已经执行了abort、已经执行了complete等

请求消息示例

http

PUT https://fgws3-ocloud.ihep.ac.cn/20001-cbq/S3test1.txt?partNumber=1&uploadId=1d1375c6431e0f9ac30a1d37003a8eb8564c6d88 HTTP/1.1
Host: fgws3-ocloud.ihep.ac.cn
Content-Length: 12
Content-Md5: Zl8nvtblllvc/0VEbXhRXA==
X-Amz-Content-Sha256: a8647ad4015e68ea743af1cd830305d6455d09fa3a27b546f3e215671298ab1c
X-Amz-Date: 20231128T083840Z
Authorization: AWS4-HMAC-SHA256 Credential=PIM9Z4LAahZtba1BeLW2/20231128/us-east-1/s3/aws4_request, SignedHeaders=content-length;content-md5;host;x-amz-content-sha256;x-amz-date, Signature=57d4eaa98b10bf21513df2cfa08cfa71f00664c5938f54cff1a4fbb0ae3fb9d1

响应消息示例

http

HTTP/1.1 200 OK
Date: Tue, 28 Nov 2023 08:38:41 GMT
Accept-Ranges: bytes
Content-Length: 0
Etag: "665f27bed6e5965bdcff45446d78515c"
Server: JWanFS FGW Server
X-Amz-Request-Id: 1701160721749557386

合并段

功能介绍

如果用户上传完所有的段，就可以调用合并段接口，系统将在服务端将用户指定的段合并成一个完整的对象。在执行“合并段”操作以前，用户不能下载已经上传的数据。在合并段时需要将多段上传任务初始化时记录的附加消息头信息拷贝到对象元数据中，其处理过程和普通上传对象带这些消息头的处理过程相同。在并发合并段的情况下，仍然遵循Last Write Win策略，但“Last Write”的时间定义为段任务的初始化时间。

已经上传的段，只要没有取消对应的多段上传任务，都要占用用户的容量配额；对应的多段上传任务“合并段”操作完成后，只有指定的多段数据占用容量配额，用户上传的其他此多段任务对应的段数据如果没有包含在“合并段”操作制定的段列表中，“合并段”完成后删除多余的段数据，且同时释放容量配额。

合并完成的多段上传数据可以通过已有的下载对象接口，下载整个多段上传对象或者指定Range下载整个多段上传对象的某部分数据。

合并完成的多段上传数据可以通过已有的删除对象接口，删除整个多段上传对象的所有分段数据，删除后不可恢复。

请求语法

http

POST /<bucket-name>/<object-key>?uploadId=<upload-id> HTTP/1.1
Host: fgws3-ocloud.ihep.ac.cn
Date: <date>
Content-Type: application/xml
Content-Length: <request-body-size>
X-Amz-Content-Sha256: <content-sha256>
Authorization: <authorization-header>

<CompleteMultipartUpload>
  <Part>
    <PartNumber>1</PartNumber>
    <ETag>"<part1-etag>"</ETag>
  </Part>
  <Part>
    <PartNumber>2</PartNumber>
    <ETag>"<part2-etag>"</ETag>
  </Part>
</CompleteMultipartUpload>

请求头定义

参数	描述
x-amz-meta-	以该前缀开头的header都将被认为是用户自定义的元数据，比如：x-amz-meta-title: TITLE 这个header会把title:TITLE作为用户自定义元数据key-value对。类型：字符串默认：无

请求元素

参数	描述	是否必须
CompleteMultipartUpload	Entity Body的长度类型：整型默认：无	是
ETag	一块数据上传完毕后，服务器端返回的Entity tag类型：字符串父节点：Part	是
Part	每一块的描述信息的容器类型：容器子节点：PartNumber，ETag	是
PartNumber	分块序号。类型：整型父节点：Part	是

响应元素

参数	描述
CompleteMultipartUploadResult	响应容器参数类型：容器子节点：Location，Bucket，Key，ETag
Key	对象的Key 类型：字符串父节点：CompleteMultipartUploadResult
Bucket	对象的桶类型：字符串父节点：CompleteMultipartUploadResult
ETag	新创建的对象的Entity Tag 类型：字符串父节点：CompleteMultipartUploadResult
Location	新创建的这个对象的资源定位URL 类型：字符串父节点：CompleteMultipartUploadResult

特殊错误码

错误码	Http状态码	描述
InvalidPart	400 Bad Request	请求所指定的上传块中，有一个或多个块不存在，可能的原因：该块缺失未上传，该块的EntityTag不匹配等
InvalidPartOrder	400 Bad Request	上传块列表，不是按照块序号升序排列
NoSuchUpload	404 Not Found	对应的分块上传不存在，可能原因：uploadId非法、已经执行了abort、已经执行了complete等

请求消息示例

http

POST https://fgws3-ocloud.ihep.ac.cn/20012-test-RAMmI-499/S3test.txt%20?uploadId=5d490580065444e3cacfed03998f09746a3ffdc1 HTTP/1.1
Host: fgws3-ocloud.ihep.ac.cn
Content-Length: 475
X-Amz-Date: 20231128T084524Z
X-Amz-Content-Sha256: d4197617366ccb6681566c32549a2947d69315c3c5c377748892e25a3e7fcc4b
Authorization: AWS4-HMAC-SHA256 Credential=LIAubFpMwwb34FXfvvvw/20231128/us-east-1/s3/aws4_request, SignedHeaders=content-length;host;x-amz-content-sha256;x-amz-date, Signature=d2219289e5ea87eafc3b1a2d7afeeef4d1cb3c20011a82aca849982e0e4b1db6

响应消息示例

http

HTTP/1.1 200 OK 
Date: Tue, 28 Nov 2023 08:45:24 GMT
Accept-Ranges: bytes
Content-Length: 351
Content-Type: application/xml
Server: JWanFS FGW Server
X-Amz-Request-Id: 1701161124981482313

<?xml version="1.0" encoding="UTF-8"?>
<CompleteMultipartUploadResult
    xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Bucket>20012-test-RAMmI-499</Bucket>
    <ETag>&#34;f45dfee146f3414491423aad4d6c7cfd-8&#34;</ETag>
    <Key>S3test.txt </Key>
    <Location>http://127.0.0.1:8899/buckets/20012-test-RAMmI-499/S3test.txt%20</Location>
</CompleteMultipartUploadResult>

取消多段上传任务

功能介绍

如果用户希望取消一个任务，可以调用取消多段上传任务接口取消任务。合并段或取消任务接口被调用后，用户不能再对任务进行上传段和列举段的操作。

特殊错误码

错误码	Http状态码	描述
NoSuchUpload	404 Not Found	对应的分块上传不存在，可能原因：uploadId非法、已经执行了abort、已经执行了complete等

请求语法

http

DELETE /<bucket-name>/<object-key>?uploadId=<upload-id> HTTP/1.1
Host: fgws3-ocloud.ihep.ac.cn
Date: <date>
Authorization: <authorization-header>
X-Amz-Content-Sha256: <content-sha256>

请求消息示例

http

DELETE https://fgws3-ocloud.ihep.ac.cn/20011-test-ENxdR-052 HTTP/1.1
Host: fgws3-ocloud.ihep.ac.cn
X-Amz-Date: 20231128T084155Z
X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Authorization: AWS4-HMAC-SHA256 Credential=6H710y1DFuIFzMIvUp8O/20231128/us-east-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=48410d7af44e34875874fef8739ff984c0b4a5e08135eabdf980e1b73f72c72a

响应消息示例

http

HTTP/1.1 204 No Content 
Server: JWanFS FGW Server
X-Amz-Request-Id: 1701160915501770044
Date: Tue, 28 Nov 2023 08:41:55 GMT
Accept-Ranges: bytes

列举已上传的段

功能介绍

段大小范围是[100KB，5GB]，但在进行合并段操作时，最后一个段的大小范围为[0,5GB]。上传的段的编号也有范围限制，其范围是[1,10000]。

请求语法

http

GET /<bucket-name>/<object-key>?uploadId=<upload-id> HTTP/1.1
Host: fgws3-ocloud.ihep.ac.cn
X-Amz-Content-Sha256: <content-sha256>
Date: <date>
Authorization: <authorization-header>

请求参数

参数	描述	是否必须
max-parts	响应中的limit个数类型：整型默认值：1000 取值：[0-1000]	否
part-number-marker	分块号的界限，只有更大的分块号会被列出来。类型：字符串默认：无	否
UploadId	分块上传操作的ID 类型：字符串默认：无	是

响应元素

参数	描述
ListPartsResult	响应容器参数类型：容器子节点：Bucket，IsTruncated，Key，MaxParts、PartNumberMarker、Part、ETag、LastModified、PartNumber、Size、StorageClass、UploadId
Key	对象的 Key 类型：字符串父节点：ListPartsResult
Bucket	对象的桶类型：字符串父节点：ListPartsResult
ETag	新创建的对象的 Entity Tag 类型：字符串父节点：ListPartsResult
UploadId	分块上传操作的 ID 类型：字符串父节点：ListPartsResult
StorageClass	存储级别类型：字符串父节点：ListPartsResult
PartNumberMarker	上次列举操作后的 Part number 类型：整数父节点：ListPartsResult
MaxParts	响应允许返回的最大 part 数目类型：整数父节点：ListPartsResult
IsTruncated	是否截断，如果因为设置了 limit 导致未返回所有数据集，则该值设置为 true 类型：整数父节点：ListPartsResult
Part	识别特定 part 的一串数字类型：整数父节点：Part
LastModified	该 part 上传的时间类型：日期父节点：Part
ETag	当该 part 被上传时返回类型：字符串父节点：Part
Size	已上传的 part 数据的大小类型：整数父节点：Part

特殊错误码

错误码	Http状态码	描述
NoSuchUpload	404 Not Found	对应的分块上传不存在，可能原因：uploadId非法、已经执行了abort、已经执行了complete等

请求消息示例

http

GET https://fgws3-ocloud.ihep.ac.cn/20011-test-ENxdR-052/S3test.txt%20?uploadId=5d490580065444e3cacfed03998f09746a3ffdc1 HTTP/1.1
Host: fgws3-ocloud.ihep.ac.cn
X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Authorization: AWS4-HMAC-SHA256 Credential=6H710y1DFuIFzMIvUp8O/20231128/us-east-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=b26e139269bce59209958251adad86b1ec6ab5377af9ae8d774c0ded93138131
X-Amz-Date: 20231128T084155Z

响应消息示例

http

HTTP/1.1 200 OK 
Content-Type: application/xml
Server: JWanFS FGW Server
X-Amz-Request-Id: 1701160915449026242
Date: Tue, 28 Nov 2023 08:41:55 GMT
Accept-Ranges: bytes
Content-Length: 1027

<ListPartsResult
    xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Bucket>20011-test-ENxdR-052</Bucket>
    <IsTruncated>false</IsTruncated>
    <Key>S3test.txt </Key>
    <MaxParts>10000</MaxParts>
    <PartNumberMarker>0</PartNumberMarker>
    <Part>
        <ETag>&#34;984ca73195a93da18f0f74a3880ef01f&#34;</ETag>
        <LastModified>2023-11-28T08:41:54Z</LastModified>
        <PartNumber>1</PartNumber>
        <Size>5242880</Size>
    </Part>
    <Part>
        <ETag>&#34;fa08c07429b04078294cbd56c1eb8e6f&#34;</ETag>
        <LastModified>2023-11-28T08:41:55Z</LastModified>
        <PartNumber>2</PartNumber>
        <Size>5242880</Size>
    </Part>
    <Part>
        <ETag>&#34;ce690c786278b2a84484453995411b44&#34;</ETag>
        <LastModified>2023-11-28T08:41:55Z</LastModified>
        <PartNumber>3</PartNumber>
        <Size>5242880</Size>
    </Part>
    <Part>
        <ETag>&#34;7d6b4bb9d65d9cd72eb1d164f07fe034&#34;</ETag>
        <LastModified>2023-11-28T08:41:55Z</LastModified>
        <PartNumber>4</PartNumber>
        <Size>5242880</Size>
    </Part>
    <StorageClass>STANDARD</StorageClass>
    <UploadId>5d490580065444e3cacfed03998f09746a3ffdc1</UploadId>
</ListPartsResult>

列举桶中已初始化多段任务

功能介绍

用户可以通过本接口查询一个桶中所有的初始化后还未合并以及未取消的多段上传任务。

请求语法

http

GET /<bucket-name>?uploads HTTP/1.1
Host: fgws3-ocloud.ihep.ac.cn
X-Amz-Content-Sha256: <content-sha256>
Date: <date>
Authorization: <authorization-header>

请求参数

参数	描述	是否必须
key-marker	指定某一uploads key，只有大于该key-marker的才会被列出类型: String	否
max-uploads	最多返回max-uploads条记录类型: 数字默认：1000 取值：[0-1000]	否

响应元素

参数	描述
ListMultipartUploadsResult	响应容器参数类型：容器子节点：Bucket，IsTruncated，Delimiter，EncodingType、KeyMarker、Prefix、Upload、Key、UploadId
Bucket	对象的桶类型：字符串父节点：ListMultipartUploadsResult
Delimiter	分隔符类型：字符串父节点：ListMultipartUploadsResult
EncodingType	编码类型类型：字符串父节点：ListMultipartUploadsResult
KeyMarker	上次列举操作后的 Part number 类型：整数父节点：ListMultipartUploadsResult
Prefix	响应允许返回的最大 part 数目类型：整数父节点：ListMultipartUploadsResult
IsTruncated	是否截断，如果因为设置了 limit 导致未返回所有数据集，则该值设置为 true 类型：整数父节点：ListMultipartUploadsResult
Upload	类型：容器子节点：Key，UploadId 父节点：ListMultipartUploadsResult
Key	对象的 Key 类型：字符串父节点：Upload
UploadId	分块上传操作的 ID 类型：字符串父节点：Upload

请求消息示例

http

GET https://fgws3-ocloud.ihep.ac.cn/20001-cbq?uploads= HTTP/1.1
Host: fgws3-ocloud.ihep.ac.cn
X-Amz-Date: 20231128T083911Z
X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Authorization: AWS4-HMAC-SHA256 Credential=PIM9Z4LAahZtba1BeLW2/20231128/us-east-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=a58ecc07fa5c35f06f8065cd322db8d80c4a21bd546191c1ea0de5d8490fd965

响应消息示例

http

HTTP/1.1 200 OK
Server: JWanFS FGW Server
X-Amz-Request-Id: 1701160752470847804
Date: Tue, 28 Nov 2023 08:39:12 GMT
Accept-Ranges: bytes
Content-Length: 624
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<ListMultipartUploadsResult
    xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Bucket>20001-cbq</Bucket>
    <Delimiter></Delimiter>
    <EncodingType></EncodingType>
    <IsTruncated>false</IsTruncated>
    <KeyMarker></KeyMarker>
    <MaxUploads>10000</MaxUploads>
    <Prefix></Prefix>
    <Upload>
        <Key>S3test1.txt</Key>
        <UploadId>1d1375c6431e0f9ac30a1d37003a8eb8564c6d88</UploadId>
    </Upload>
    <Upload>
        <Key>S3test2.txt</Key>
        <UploadId>25ddfdf5db9604eb2cddb0c99d1fcaea6cafa8f4</UploadId>
    </Upload>
    <Upload>
        <Key>S3test3.txt</Key>
        <UploadId>e1a680618264019c2e98fb37f02e42bdafc892a7</UploadId>
    </Upload>
</ListMultipartUploadsResult>

大对象分块接口 ​

初始化上传段任务 ​

功能介绍 ​

请求语法 ​

请求头定义 ​

响应元素 ​

请求消息示例 ​

响应消息示例 ​

上传段 ​

请求语法 ​

请求头定义 ​

特殊错误码 ​

请求消息示例 ​

响应消息示例 ​

合并段 ​

功能介绍 ​

请求语法 ​

请求头定义 ​

请求元素 ​

响应元素 ​

特殊错误码 ​

请求消息示例 ​

响应消息示例 ​

取消多段上传任务 ​

功能介绍 ​

特殊错误码 ​

请求语法 ​

请求消息示例 ​

响应消息示例 ​

列举已上传的段 ​

功能介绍 ​

请求语法 ​

请求参数 ​

响应元素 ​

特殊错误码 ​

请求消息示例 ​

响应消息示例 ​

列举桶中已初始化多段任务 ​

功能介绍 ​

请求语法 ​

请求参数 ​

响应元素 ​

请求消息示例 ​

响应消息示例 ​

大对象分块接口

初始化上传段任务

功能介绍

请求语法

请求头定义

响应元素

请求消息示例

响应消息示例

上传段

请求语法

请求头定义

特殊错误码

请求消息示例

响应消息示例

合并段

功能介绍

请求语法

请求头定义

请求元素

响应元素

特殊错误码

请求消息示例

响应消息示例

取消多段上传任务

功能介绍

特殊错误码

请求语法

请求消息示例

响应消息示例

列举已上传的段

功能介绍

请求语法

请求参数

响应元素

特殊错误码

请求消息示例

响应消息示例

列举桶中已初始化多段任务

功能介绍

请求语法

请求参数

响应元素

请求消息示例

响应消息示例