IBM Cloud Docs
对象操作

对象操作

IBM Cloud® Object Storage 的现代功能可通过 RESTful API 方便地提供。 此处记录了读取，写入和配置对象 (存储在存储区中) 的操作和方法。

有关端点的更多信息，请参阅端点和存储位置。

有关访问/密钥 (HMAC) 认证的注释

通过 使用 HMAC 凭证 向 IBM Cloud Object Storage 实例进行认证时，在 构造 HMAC 签名 时，需要表 1 中表示的信息。

HMAC 签名组件
键 值 示例
{access_key} 为您的服务证书分配的访问密钥 cf4965cebe074720a4929759f57e1214
{date} 请求的格式化日期 (yyyymmdd) 20180613
{region} 端点的位置码 标准
{signature} 使用密钥，位置和日期创建的散列 ffe2b6e18f9dcc41f593f4dbb39882a6bb4d26a73a04326e62a8d344e07c1a3e
{timestamp} 请求的格式化日期和时间 20180614T001804Z

上传对象

提供有对象路径的 PUT 请求可将请求主体作为对象上传。 在单个线程中上载的所有对象都应小于 500 MB，以最大程度地降低网络中断风险。( 在多个部分中上载 的对象可高达 10 TB)。

个人身份信息 (PII)：在_命名_数据桶或对象时，不要使用任何可通过姓名、位置或任何其他方式识别任何用户（自然人）的信息。

并非所有操作都在 Satellite 环境中受支持。 有关详细信息，请参阅 受支持的 Satellite API

可以使用单个 PUT 请求对大小为 5 GB 的对象进行流式传输。 通过使用多个线程并行上载部件，多部分上载更加可靠，并且可以更高效地上载。 在单个 PUT 请求中上载更大的对象会导致单个线程的性能限制，如果发生任何故障，那么将需要完整地重试单线程上载 (而对于 MPU，仅需要重试失败的特定部件)。 单个线程所能达到的精确吞吐量因以下因素而异：从客户端到 IBM Cloud 端点的网络带宽、连接上的数据包丢失率（如有）、HTTP 与 HTTPS 的使用、连接中使用的特定密码、特定 TCP 连接参数（如窗口大小）以及其他因素。 虽然可以针对单线程上载对这些因素进行优化，但优化也同样适用于任何多线程 (多部分) 上载。

个人身份信息 (PII)：在创建数据桶或添加对象时，请确保不使用任何可通过姓名、位置或任何其他方式识别任何用户（自然人）的信息。

并非所有操作都在 Satellite 环境中受支持。 有关详细信息，请参阅 受支持的 Satellite API

语法

PUT https://{endpoint}/{bucket-name}/{object-name} # path style
PUT https://{bucket-name}.{endpoint}/{object-name} # virtual host style

可选头

头 Type 描述
x-amz-tagging 字符串 要应用于对象的一组标记，格式为查询参数 ("SomeKey=SomeValue")。
x-amz-object-lock-mode 字符串 有效值为 COMPLIANCE-如果 x-amz-object-lock-retain-until-date 存在，那么该值是必需的。
x-amz-object-lock-retain-until-date ISO8601 日期和时间 如果存在 x-amz-object-lock-mode，那么是必需的。
x-amz-object-lock-legal-hold 字符串 有效值为 ON 或 OFF。

示例请求

PUT /apiary/queen-bee HTTP/1.1
Authorization: Bearer {token}
Content-Type: text/plain; charset=utf-8
Host: s3.us.cloud-object-storage.appdomain.cloud

Content-Length: 533

 The 'queen' bee is developed from larvae selected by worker bees and fed a
 substance referred to as 'royal jelly' to accelerate sexual maturity. After a
 short while the 'queen' is the mother of nearly every bee in the hive, and
 the colony will fight fiercely to protect her.

示例请求

PUT /apiary/queen-bee HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
x-amz-content-sha256: {payload_hash}
Content-Type: text/plain; charset=utf-8
Host: s3.us.cloud-object-storage.appdomain.cloud

Content-Length: 533

 The 'queen' bee is developed from larvae selected by worker bees and fed a
 substance referred to as 'royal jelly' to accelerate sexual maturity. After a
 short while the 'queen' is the mother of nearly every bee in the hive, and
 the colony will fight fiercely to protect her.

示例响应

HTTP/1.1 200 OK
Date: Thu, 25 Aug 2016 18:30:02 GMT
X-Clv-Request-Id: 9f0ca49a-ae13-4d2d-925b-117b157cf5c3
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.121
X-Clv-S3-Version: 2.5
x-amz-request-id: 9f0ca49a-ae13-4d2d-925b-117b157cf5c3
ETag: "3ca744fa96cb95e92081708887f63de5"
Content-Length: 0

获取对象的头

提供有对象路径的 HEAD 请求将检索对象的头。

使用 SSE-KP 加密的对象返回的 Etag 值是原始解密对象的 MD5 哈希值。

并非所有操作都在 Satellite 环境中受支持。 有关详细信息，请参阅 受支持的 Satellite API

语法

HEAD https://{endpoint}/{bucket-name}/{object-name} # path style
HEAD https://{bucket-name}.{endpoint}/{object-name} # virtual host style

示例请求

HEAD /apiary/soldier-bee HTTP/1.1
Authorization: Bearer {token}
Host: s3-api.sjc-us-geo.objectstorage.s3.us-south.cloud-object-storage.appdomain.cloud.net

示例请求

HEAD /apiary/soldier-bee HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Host: s3.us.cloud-object-storage.appdomain.cloud

示例响应

HTTP/1.1 200 OK
Date: Thu, 25 Aug 2016 18:32:44 GMT
X-Clv-Request-Id: da214d69-1999-4461-a130-81ba33c484a6
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.121
X-Clv-S3-Version: 2.5
x-amz-request-id: da214d69-1999-4461-a130-81ba33c484a6
ETag: "37d4c94839ee181a2224d6242176c4b5"
Content-Type: text/plain; charset=UTF-8
Last-Modified: Thu, 25 Aug 2016 17:49:06 GMT
Content-Length: 11

下载对象

提供有对象路径的 GET 请求将下载对象。

请注意，针对使用 SSE-C/SSE-KP 加密的对象返回的 Etag 值将不是原始已解密对象的 MD5 散列。

并非所有操作都在 Satellite 环境中受支持。 有关详细信息，请参阅 受支持的 Satellite API

语法

GET https://{endpoint}/{bucket-name}/{object-name} # path style
GET https://{bucket-name}.{endpoint}/{object-name} # virtual host style

可选头

头 Type 描述
range 字符串 返回指定范围内对象的字节。

示例请求

GET /apiary/worker-bee HTTP/1.1
Authorization: Bearer {token}
Host: s3.us.cloud-object-storage.appdomain.cloud

示例请求

GET /apiary/worker-bee HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Host: s3.us.cloud-object-storage.appdomain.cloud

示例响应

HTTP/1.1 200 OK
Date: Thu, 25 Aug 2016 18:34:25 GMT
X-Clv-Request-Id: 116dcd6b-215d-4a81-bd30-30291fa38f93
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.121
X-Clv-S3-Version: 2.5
x-amz-request-id: 116dcd6b-215d-4a81-bd30-30291fa38f93
ETag: "d34d8aada2996fc42e6948b926513907"
Content-Type: text/plain; charset=UTF-8
Last-Modified: Thu, 25 Aug 2016 17:46:53 GMT
Content-Length: 467

 Female bees that are not fortunate enough to be selected to be the 'queen'
 while they were still larvae become known as 'worker' bees. These bees lack
 the ability to reproduce and instead ensure that the hive functions smoothly,
 acting almost as a single organism in fulfilling their purpose.

删除一个对象

提供有对象路径的 DELETE 请求将删除该对象。

并非所有操作都在 Satellite 环境中受支持。 有关详细信息，请参阅 受支持的 Satellite API

语法

DELETE https://{endpoint}/{bucket-name}/{object-name} # path style
DELETE https://{bucket-name}.{endpoint}/{object-name} # virtual host style

示例请求

DELETE /apiary/soldier-bee HTTP/1.1
Authorization: Bearer {token}
Host: s3-api.sjc-us-geo.objectstorage.s3.us-south.cloud-object-storage.appdomain.cloud.net

示例请求

DELETE /apiary/soldier-bee HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Host: s3.us.cloud-object-storage.appdomain.cloud

示例响应

HTTP/1.1 204 No Content
Date: Thu, 25 Aug 2016 17:44:57 GMT
X-Clv-Request-Id: 8ff4dc32-a6f0-447f-86cf-427b564d5855
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.121
X-Clv-S3-Version: 2.5
x-amz-request-id: 8ff4dc32-a6f0-447f-86cf-427b564d5855

删除多个对象

提供有存储区路径和相应参数的 POST 请求将删除一组指定的对象。 需要 Content-MD5 头，用于指定请求主体的 Base64 编码的 MD5 散列。

必需的 Content-MD5 头需要是 Base64 编码的 MD5 散列的二进制表示。

如果未找到请求中指定的对象，则返回删除结果。

并非所有操作都在 Satellite 环境中受支持。 有关详细信息，请参阅 受支持的 Satellite API

多个对象删除涉及作为 A 类收费的 POST operation。针对多次删除的 POST 请求的成本因对象的存储类以及删除的数据量而异。 有关定价的详细信息，请参阅 IBM Cloud Object Storage定价页面。

可选元素

头
头 Type 描述
Quiet 布尔值 对请求启用静默方式。

请求最多可包含 1000 个要删除的密钥。 虽然这对于减少请求数非常有用，但在删除大量密钥时应谨慎。 此外，请考虑对象的大小，以确保性能合适。

以下代码显示了如何创建头内容的必要表示的一个示例:

echo -n (XML block) | openssl dgst -md5 -binary | openssl enc -base64

语法

POST https://{endpoint}/{bucket-name}?delete= # path style
POST https://{bucket-name}.{endpoint}?delete= # virtual host style

请求主体必须包含具有以下模式的 XML 块：

请求模式正文
元素 Type 子代 祖代 约束
删除(T) 容器 对象
对象 容器 键 删除(T)
键 字符串
对象 有效密钥字符串

示例请求

POST /apiary?delete= HTTP/1.1
Authorization: Bearer {token}
Host: s3.us.cloud-object-storage.appdomain.cloud
Content-Type: text/plain; charset=utf-8
Content-MD5: xj/vf7lD7vbIe/bqHTaLvg==

示例请求

POST /apiary?delete= HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain; charset=utf-8
Content-MD5: xj/vf7lD7vbIe/bqHTaLvg==
Host: s3.us.cloud-object-storage.appdomain.cloud

示例响应

HTTP/1.1 200 OK
Date: Wed, 30 Nov 2016 18:54:53 GMT
X-Clv-Request-Id: a6232735-c3b7-4c13-a7b2-cd40c4728d51
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.137
X-Clv-S3-Version: 2.5
x-amz-request-id: a6232735-c3b7-4c13-a7b2-cd40c4728d51
Content-Type: application/xml
Content-Length: 207

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<DeleteResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Deleted>
         <Key>surplus-bee</Key>
    </Deleted>
    <Deleted>
         <Key>unnecessary-bee</Key>
    </Deleted>
</DeleteResult>

在对象上添加或扩展保留时间

向具有正确参数的对象发出的 PUT 会添加或延长该对象的保留期。

并非所有操作都在 Satellite 环境中受支持。 有关详细信息，请参阅 受支持的 Satellite API

语法

PUT https://{endpoint}/{bucket-name}/{object-name}?retention # path style
PUT https://{bucket-name}.{endpoint}/{object-name}?retention # virtual host style

有效内容元素

请求主体必须包含具有以下模式的 XML 块：

请求模式正文
元素 Type 子代 祖代 注释
保留时间 容器 模式，RetainUntilDate
必需
方式 字符串
保留时间 必需-有效值为 COMPLIANCE
RetainUntilDate 时间戳记
保留时间 必需

以下代码显示了如何创建头内容的必要表示的一个示例:

echo -n (XML block) | openssl dgst -md5 -binary | openssl enc -base64

示例请求

这是在对象上添加或扩展保留时间的示例。

PUT /apiary/myObject?retention HTTP/1.1
Authorization: Bearer {token}
Content-Type: text/plain
Content-MD5: cDeRJIdLuEXWmLpA79K2kg==
Host: s3.us.cloud-object-storage.appdomain.cloud
Content-Length: 119

<Retention>
    <Mode>COMPLIANCE</Mode>
    <RetainUntilDate>2023-04-12T23:01:00.000Z</RetainUntilDate>
</Retention>

示例响应

HTTP/1.1 200 OK
Date: Wed, 5 Oct 2020 15:39:38 GMT
X-Clv-Request-Id: 7afca6d8-e209-4519-8f2c-1af3f1540b42
Accept-Ranges: bytes
Content-Length: 0

向对象添加标记

发出到具有正确参数的对象的 PUT 会创建或替换与该对象关联的一组键值标记。

并非所有操作都在 Satellite 环境中受支持。 有关详细信息，请参阅 受支持的 Satellite API

语法

PUT https://{endpoint}/{bucket-name}/{object-name}?tagging # path style
PUT https://{bucket-name}.{endpoint}/{object-name}?tagging # virtual host style

有效内容元素

请求主体必须包含具有以下模式的 XML 块：

请求模式正文
元素 Type 子代 祖代 注释
标记 容器 TagSet
必需
TagSet 容器 标记 标记 必需
标记 字符串 键，值 TagSet 必需
键 容器
标记 必需
值 字符串
标记 必需

标记必须符合以下限制:

  • 一个对象最多可以有 10 个标记
  • 对于每个对象，每个标记键都必须唯一，并且每个标记键只能有一个值。
  • 最小密钥长度-1 Unicode 字符 ( UTF-8 )
  • 最大密钥长度-128 个 Unicode 字符 (采用 UTF-8 )
  • 最大键字节大小-256 字节
  • 最小值长度-0 Unicode 字符 ( UTF-8 ) (标记值可以为空)
  • 最大值长度-以 UTF-8 表示的 256 个 Unicode 字符
  • 最大值字节大小-512 字节
  • 标签键和值可由美国字母数字字符 (a-z,A-Z,0-9) 和空格（用 UTF-8 表示）以及以下符号组成：+, -, =, ., _, :, /、@
  • 标记键和值区分大小写
  • ibm: 不能用作标记的键前缀

示例请求

这是向对象添加一组标记的示例。

PUT /apiary/myObject?tagging HTTP/1.1
Authorization: Bearer {token}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
Content-Length: 119

PUT /apiary/myObject?tagging HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
Content-Length: 128

<Tagging>
   <TagSet>
      <Tag>
         <Key>string</Key>
         <Value>string</Value>
      </Tag>
   </TagSet>
</Tagging>

示例响应

HTTP/1.1 200 OK
Date: Wed, 5 Oct 2020 15:39:38 GMT
X-Clv-Request-Id: 7afca6d8-e209-4519-8f2c-1af3f1540b42
Accept-Ranges: bytes
Content-Length: 0

读取对象的标记

发出到具有正确参数的对象的 GET 将返回与该对象相关联的键/值标记集。

并非所有操作都在 Satellite 环境中受支持。 有关详细信息，请参阅 受支持的 Satellite API

语法

GET https://{endpoint}/{bucket-name}/{object-name}?tagging # path style
GET https://{bucket-name}.{endpoint}/{object-name}?tagging # virtual host style

示例请求

这是读取一组对象标记的示例。

GET /apiary/myObject?tagging HTTP/1.1
Authorization: Bearer {token}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
Content-Length: 0

GET /apiarymyObject?tagging HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
Content-Length: 0

示例响应

HTTP/1.1 200 OK
Date: Wed, 5 Oct 2020 15:39:38 GMT
X-Clv-Request-Id: 7afca6d8-e209-4519-8f2c-1af3f1540b42
Accept-Ranges: bytes
Content-Length: 128

<Tagging>
   <TagSet>
      <Tag>
         <Key>string</Key>
         <Value>string</Value>
      </Tag>
   </TagSet>
</Tagging>

删除对象的标记

发出到具有正确参数的存储区的 DELETE 将除去对象的标记。

并非所有操作都在 Satellite 环境中受支持。 有关详细信息，请参阅 受支持的 Satellite API

语法

DELETE https://{endpoint}/{bucket-name}{object-name}?tagging # path style
DELETE https://{bucket-name}.{endpoint}{object-name}?tagging # virtual host style

示例请求

这是删除对象的标记的示例。

DELETE /apiary/myObject?tagging HTTP/1.1
Authorization: Bearer {token}
Host: s3.us.cloud-object-storage.appdomain.cloud

示例请求

DELETE /apiary/myObject?tagging HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud

服务器使用 204 No Content进行响应。

复制对象

提供有新对象路径的 PUT 请求将创建由 x-amz-copy-source 头指定的另一个对象的新副本。 除非另有变更，否则元数据保持不变。

个人身份信息 (PII)：在_命名_数据桶或对象时，不要使用任何可通过姓名、位置或任何其他方式识别任何用户（自然人）的信息。

复制对象 (甚至跨位置) 不会产生公共出站带宽费用。 所有数据都保留在 COS 内部网络中。

并非所有操作都在 Satellite 环境中受支持。 有关详细信息，请参阅 受支持的 Satellite API

语法

PUT https://{endpoint}/{bucket-name}/{object-name} # path style
PUT https://{bucket-name}.{endpoint}/{object-name} # virtual host style

可选头

头 Type 描述
x-amz-metadata-directive 字符串（COPY 或 REPLACE） REPLACE 将使用提供的新元数据覆盖原始元数据。
x-amz-tagging 字符串 要应用于对象的一组标记，格式为查询参数 ("SomeKey=SomeValue")。
x-amz-tagging-directive 字符串（COPY 或 REPLACE） REPLACE 用提供的新标签覆盖原始标签。
x-amz-copy-source-if-match 字符串 (ETag) 指定的 ETag 与源对象匹配时创建副本。
x-amz-copy-source-if-none-match 字符串 (ETag) 指定的 ETag 与源对象不同时创建副本。
x-amz-copy-source-if-unmodified-since 字符串（时间戳记） 自指定日期以来未修改过源对象时创建副本。 日期必须是有效的 HTTP 日期（例如，Wed, 30 Nov 2016 20:21:38 GMT）。
x-amz-copy-source-if-modified-since 字符串（时间戳记） 自指定日期以来修改过源对象时创建副本。 日期必须是有效的 HTTP 日期（例如，Wed, 30 Nov 2016 20:21:38 GMT）。

示例请求

此基本示例从 bee 存储区中获取 garden 对象，然后在 apiary 存储区中使用新键 wild-bee 来创建副本。

PUT /apiary/wild-bee HTTP/1.1
Authorization: Bearer {token}
x-amz-copy-source: /garden/bee
Host: s3.us.cloud-object-storage.appdomain.cloud

示例请求

PUT /apiary/wild-bee HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
x-amz-copy-source: /garden/bee
Host: s3.us.cloud-object-storage.appdomain.cloud

示例响应

HTTP/1.1 200 OK
Date: Wed, 30 Nov 2016 19:52:52 GMT
X-Clv-Request-Id: 72992a90-8f86-433f-b1a4-7b1b33714bed
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.137
X-Clv-S3-Version: 2.5
x-amz-request-id: 72992a90-8f86-433f-b1a4-7b1b33714bed
ETag: "853aab195ce770b0dfb294a4e9467e62"
Content-Type: application/xml
Content-Length: 240

<CopyObjectResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <LastModified>2016-11-30T19:52:53.125Z</LastModified>
  <ETag>"853aab195ce770b0dfb294a4e9467e62"</ETag>
</CopyObjectResult>

检查对象的 CORS 配置

提供有对象路径以及源和请求类型的 OPTIONS 请求将检查以确定该对象是否可使用该请求类型从该源进行访问。 与其他所有请求不同，OPTIONS 请求并不需要 authorization 或 x-amx-date 头。

并非所有操作都在 Satellite 环境中受支持。 有关详细信息，请参阅 受支持的 Satellite API

语法

OPTIONS https://{endpoint}/{bucket-name}/{object-name} # path style
OPTIONS https://{bucket-name}.{endpoint}/{object-name} # virtual host style

示例请求

OPTIONS /apiary/queen-bee HTTP/1.1
Access-Control-Request-Method: PUT
Origin: http://ibm.com
Host: s3.us.cloud-object-storage.appdomain.cloud

示例请求

OPTIONS /apiary/queen-bee HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Access-Control-Request-Method: PUT
Origin: http://ibm.com
Host: s3.us.cloud-object-storage.appdomain.cloud

示例响应

HTTP/1.1 200 OK
Date: Wed, 07 Dec 2016 16:23:14 GMT
X-Clv-Request-Id: 9a2ae3e1-76dd-4eec-a8f2-1a7f60f63483
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.137
X-Clv-S3-Version: 2.5
x-amz-request-id: 9a2ae3e1-76dd-4eec-a8f2-1a7f60f63483
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: PUT
Access-Control-Allow-Credentials: true
Vary: Origin, Access-Control-Request-Headers, Access-Control-Allow-Methods
Content-Length: 0

分块上传对象

使用较大的对象时，建议使用分块上传操作将对象写入 IBM Cloud® Object Storage。 可以将单个对象的上传作为一组分块来执行，这些分块可以按任意顺序单独上传，也可以并行上传。 上传完成后，Object Storage 会将所有分块显示为单个对象。 此方法有诸多优点：网络中断不会导致大型上传操作失败，在一段时间内上传可以暂停并重新启动，并且可以在对象创建期间上传对象。

分块上传仅可用于大于 5 MB 的对象。 对于小于 50 GB 的对象，建议的分块大小为 20 MB 到 100 MB，以实现最佳性能。 对于更大的对象，可以增大分块大小，而不会对性能产生重大影响。

由于涉及到额外的复杂性，因此建议开发者使用提供分块上传支持的库。

未完成的分块上传会一直持久存储，直到删除对象或使用 AbortIncompleteMultipartUpload 中止分块上传。 如果未中止未完成的分块上传，那么分块上传会继续使用资源。 设计界面时应该谨记这一点，应清除未完成的分块上传。

分块上传对象分为三个阶段：

  1. 启动上传并创建 UploadId。
  2. 上传各个分块，并指定对象的分块序号和 UploadId。
  3. 上传所有分块完成后，通过发送包含 UploadId 和 XML 块（列出每个分块编号及其各自的 Etag 值）的请求来完成上传。

启动分块上传

向对象发出使用查询参数 POST 的 upload 请求会创建新的 UploadId 值，然后要上传的对象的每个分块都会引用此值。

个人身份信息 (PII)：在_命名_数据桶或对象时，不要使用任何可通过姓名、位置或任何其他方式识别任何用户（自然人）的信息。

并非所有操作都在 Satellite 环境中受支持。 有关详细信息，请参阅 受支持的 Satellite API

语法

POST https://{endpoint}/{bucket-name}/{object-name}?uploads= # path style
POST https://{bucket-name}.{endpoint}/{object-name}?uploads= # virtual host style

示例请求

POST /some-bucket/multipart-object-123?uploads= HTTP/1.1
Authorization: Bearer {token}
Host: s3.us.cloud-object-storage.appdomain.cloud

示例请求

POST /some-bucket/multipart-object-123?uploads= HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Host: s3.us.cloud-object-storage.appdomain.cloud

示例响应

HTTP/1.1 200 OK
Date: Fri, 03 Mar 2017 20:34:12 GMT
X-Clv-Request-Id: 258fdd5a-f9be-40f0-990f-5f4225e0c8e5
Accept-Ranges: bytes
Server: Cleversafe/3.9.1.114
X-Clv-S3-Version: 2.5
Content-Type: application/xml
Content-Length: 276

<InitiateMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Bucket>some-bucket</Bucket>
  <Key>multipart-object-123</Key>
  <UploadId>0000015a-95e1-4326-654e-a1b57887784f</UploadId>
</InitiateMultipartUploadResult>

上传部件

向对象发出使用查询参数 PUT 和 partNumber 的 uploadId 请求将上传对象的一个分块。 这些分块可以按序列上传，也可以并行上传，但必须按顺序编号。

个人身份信息 (PII)：在_命名_数据桶或对象时，不要使用任何可通过姓名、位置或任何其他方式识别任何用户（自然人）的信息。

并非所有操作都在 Satellite 环境中受支持。 有关详细信息，请参阅 受支持的 Satellite API

语法

PUT https://{endpoint}/{bucket-name}/{object-name}?partNumber={sequential-integer}&uploadId={uploadId}= # path style
PUT https://{bucket-name}.{endpoint}/{object-name}?partNumber={sequential-integer}&uploadId={uploadId}= # virtual host style

示例请求

PUT /some-bucket/multipart-object-123?partNumber=1&uploadId=0000015a-df89-51d0-2790-dee1ac994053 HTTP/1.1
Authorization: Bearer {token}
Content-Type: application/pdf
Host: s3.us.cloud-object-storage.appdomain.cloud
Content-Length: 13374550

示例请求

PUT /some-bucket/multipart-object-123?partNumber=1&uploadId=0000015a-df89-51d0-2790-dee1ac994053 HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
x-amz-content-sha256: STREAMING-AWS4-HMAC-SHA256-PAYLOAD
Content-Encoding: aws-chunked
x-amz-decoded-content-length: 13374550
Content-Type: application/pdf
Host: s3.us.cloud-object-storage.appdomain.cloud
Content-Length: 13374550

示例响应

HTTP/1.1 200 OK
Date: Sat, 18 Mar 2017 03:56:41 GMT
X-Clv-Request-Id: 17ba921d-1c27-4f31-8396-2e6588be5c6d
Accept-Ranges: bytes
Server: Cleversafe/3.9.1.114
X-Clv-S3-Version: 2.5
ETag: "7417ca8d45a71b692168f0419c17fe2f"
Content-Length: 0

列出分块

提供有分块对象路径并且将活动 GET 指定为查询参数的 UploadID 请求将返回对象的所有分块的列表。

并非所有操作都在 Satellite 环境中受支持。 有关详细信息，请参阅 受支持的 Satellite API

语法

GET https://{endpoint}/{bucket-name}/{object-name}?uploadId={uploadId} # path style
GET https://{bucket-name}.{endpoint}/{object-name}?uploadId={uploadId} # virtual host style

查询参数

参数
参数 必需? 类型 描述
uploadId 必需 string 初始化多重部件上载时返回的上载标识。
max-parts 可选 string 缺省值为 1,000。
part-number​-marker 可选 string 定义部件列表的开始位置。

示例请求

GET /farm/spaceship?uploadId=01000162-3f46-6ab8-4b5f-f7060b310f37 HTTP/1.1
Authorization: bearer {token}
Host: s3.us.cloud-object-storage.appdomain.cloud

示例请求

GET /farm/spaceship?uploadId=01000162-3f46-6ab8-4b5f-f7060b310f37 HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Host: s3.us.cloud-object-storage.appdomain.cloud

示例响应

HTTP/1.1 200 OK
Date: Mon, 19 Mar 2018 17:21:08 GMT
X-Clv-Request-Id: 6544044d-4f88-4bb6-9ee5-bfadf5023249
Server: Cleversafe/3.12.4.20
X-Clv-S3-Version: 2.5
Accept-Ranges: bytes
Content-Type: application/xml
Content-Length: 743

<ListPartsResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Bucket>farm</Bucket>
  <Key>spaceship</Key>
  <UploadId>01000162-3f46-6ab8-4b5f-f7060b310f37</UploadId>
  <Initiator>
    <ID>d6f04d83-6c4f-4a62-a165-696756d63903</ID>
    <DisplayName>d6f04d83-6c4f-4a62-a165-696756d63903</DisplayName>
  </Initiator>
  <Owner>
    <ID>d6f04d83-6c4f-4a62-a165-696756d63903</ID>
    <DisplayName>d6f04d83-6c4f-4a62-a165-696756d63903</DisplayName>
  </Owner>
  <StorageClass>STANDARD</StorageClass>
  <MaxParts>1000</MaxParts>
  <IsTruncated>false</IsTruncated>
  <Part>
    <PartNumber>1</PartNumber>
    <LastModified>2018-03-19T17:20:35.482Z</LastModified>
    <ETag>"bb03cf4fa8603fe407a65ee1dba55265"</ETag>
    <Size>7128094</Size>
  </Part>
</ListPartsResult>

完成分块上传

向对象发出使用查询参数 POST 并且主体中包含相应 XML 块的 uploadId 请求将完成分块上传。

并非所有操作都在 Satellite 环境中受支持。 有关详细信息，请参阅 受支持的 Satellite API

语法

POST https://{endpoint}/{bucket-name}/{object-name}?uploadId={uploadId}= # path style
POST https://{bucket-name}.{endpoint}/{object-name}?uploadId={uploadId}= # virtual host style

请求主体必须包含具有以下模式的 XML 块：

请求模式正文
元素 Type 子代 祖代 约束
CompleteMultipartUpload 容器 部件
部件 容器 PartNumber, ETag 删除(T)
PartNumber 字符串
对象 有效部件号
ETag 字符串
对象 有效的 ETag 值字符串 
<CompleteMultipartUpload>
  <Part>
    <PartNumber>{sequential part number}</PartNumber>
    <ETag>{ETag value from part upload response header}</ETag>
  </Part>
</CompleteMultipartUpload>

示例请求

POST /some-bucket/multipart-object-123?uploadId=0000015a-df89-51d0-2790-dee1ac994053 HTTP/1.1
Authorization: Bearer {token}
Content-Type: text/plain; charset=utf-8
Host: s3.us.cloud-object-storage.appdomain.cloud
Content-Length: 257

示例请求

POST /some-bucket/multipart-object-123?uploadId=0000015a-df89-51d0-2790-dee1ac994053 HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain; charset=utf-8
Host: s3.us.cloud-object-storage.appdomain.cloud
Content-Length: 257

<CompleteMultipartUpload>
  <Part>
    <PartNumber>1</PartNumber>
    <ETag>"7417ca8d45a71b692168f0419c17fe2f"</ETag>
  </Part>
  <Part>
    <PartNumber>2</PartNumber>
    <ETag>"7417ca8d45a71b692168f0419c17fe2f"</ETag>
  </Part>
</CompleteMultipartUpload>

示例响应

HTTP/1.1 200 OK
Date: Fri, 03 Mar 2017 19:18:44 GMT
X-Clv-Request-Id: c8be10e7-94c4-4c03-9960-6f242b42424d
Accept-Ranges: bytes
Server: Cleversafe/3.9.1.114
X-Clv-S3-Version: 2.5
ETag: "765ba3df36cf24e49f67fc6f689dfc6e-2"
Content-Type: application/xml
Content-Length: 364

<CompleteMultipartUploadResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Location>http://s3.us.cloud-object-storage.appdomain.cloud/zopse/multipart-object-123</Location>
  <Bucket>some-bucket</Bucket>
  <Key>multipart-object-123</Key>
  <ETag>"765ba3df36cf24e49f67fc6f689dfc6e-2"</ETag>
</CompleteMultipartUploadResult>

中止未完成的分块上传

向对象发出使用查询参数 DELETE 的 uploadId 请求将删除分块上传中所有未完成的分块。

并非所有操作都在 Satellite 环境中受支持。 有关详细信息，请参阅 受支持的 Satellite API

语法

DELETE https://{endpoint}/{bucket-name}/{object-name}?uploadId={uploadId}= # path style
DELETE https://{bucket-name}.{endpoint}/{object-name}?uploadId={uploadId}= # virtual host style

示例请求

DELETE /some-bucket/multipart-object-123?uploadId=0000015a-df89-51d0-2790-dee1ac994053 HTTP/1.1
Authorization: Bearer {token}
Host: s3.us.cloud-object-storage.appdomain.cloud

示例请求

DELETE /some-bucket/multipart-object-123?uploadId=0000015a-df89-51d0-2790-dee1ac994053 HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Host: s3.us.cloud-object-storage.appdomain.cloud

示例响应

HTTP/1.1 204 No Content
Date: Thu, 16 Mar 2017 22:07:48 GMT
X-Clv-Request-Id: 06d67542-6a3f-4616-be25-fc4dbdf242ad
Accept-Ranges: bytes
Server: Cleversafe/3.9.1.114
X-Clv-S3-Version: 2.5

临时复原归档对象

向对象发出使用查询参数 POST 的 restore 请求将请求临时复原归档对象。 需要 Content-MD5 头作为有效内容的完整性检查。

归档对象必须在下载或修改该对象之前进行复原。 必须指定对象的生命周期，在此周期后将删除该对象的临时副本。

对于生命周期策略转换存储类为 GLACIER 的存储区，在复原的副本可供访问之前，可能会有最多 12 小时的延迟。 如果转换存储类设置为 ACCELERATED，那么在复原的对象可用之前可能有最多两个 (2) 小时的延迟。 HEAD 请求可以检查复原的副本是否可用。

要永久复原对象，必须将该对象复制到没有活动生命周期配置的存储区。

并非所有操作都在 Satellite 环境中受支持。 有关详细信息，请参阅 受支持的 Satellite API

语法

POST https://{endpoint}/{bucket-name}/{object-name}?restore # path style
POST https://{bucket-name}.{endpoint}/{object-name}?restore # virtual host style

有效内容元素

请求主体必须包含具有以下模式的 XML 块：

元素 Type 子代 祖代 约束
RestoreRequest 容器 Days、GlacierJobParameters 无 无
天 整数 无 RestoreRequest 指定临时复原对象的生命周期。 对象的已复原副本可以存在的最小天数为 1。 在经过复原周期之后，将除去对象的临时副本。
GlacierJobParameters 字符串 层 RestoreRequest 无
层 字符串 无 GlacierJobParameters 可选，如果留空，那么将缺省为与写入对象时的策略存储层相关联的值。 如果此值不留空，那么 必须 将其设置为 Bulk (如果存储区生命周期策略的转换存储类设置为 GLACIER)，必须 将其设置为 Accelerated (如果转换存储类设置为 ACCELERATED)。 
<RestoreRequest>
    <Days>{integer}</Days>
    <GlacierJobParameters>
        <Tier>Bulk</Tier>
    </GlacierJobParameters>
</RestoreRequest>

示例请求

POST /apiary/queenbee?restore HTTP/1.1
Authorization: {authorization-string}
Content-Type: text/plain
Content-MD5: rgRRGfd/OytcM7O5gIaQ==
Content-Length: 305
Host: s3.us.cloud-object-storage.appdomain.cloud

示例请求

POST /apiary/queenbee?restore HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-MD5: rgRRGfd/OytcM7O5gIaQ==
Content-Length: 305
Host: s3.us.cloud-object-storage.appdomain.cloud

<RestoreRequest>
    <Days>3</Days>
    <GlacierJobParameters>
        <Tier>Bulk</Tier>
    </GlacierJobParameters>
</RestoreRequest>

示例响应

HTTP/1.1 202 Accepted
Date: Thu, 16 Mar 2017 22:07:48 GMT
X-Clv-Request-Id: 06d67542-6a3f-4616-be25-fc4dbdf242ad
Accept-Ranges: bytes
Server: Cleversafe/3.9.1.114
X-Clv-S3-Version: 2.5

更新元数据

有两种方法可更新现有对象上的元数据：

  • 对新的元数据和原始对象内容执行 PUT 请求
  • 使用将原始对象指定为复制源的新元数据来运行 COPY 请求

所有元数据键的前缀必须为 x-amz-meta-

并非所有操作都在 Satellite 环境中受支持。 有关详细信息，请参阅 受支持的 Satellite API

使用 PUT 更新元数据

PUT 请求需要现有对象的副本，因为这将覆盖内容。

语法

PUT https://{endpoint}/{bucket-name}/{object-name} # path style
PUT https://{bucket-name}.{endpoint}/{object-name} # virtual host style

示例请求

PUT /apiary/queen-bee HTTP/1.1
Authorization: Bearer {token}
Content-Type: text/plain; charset=utf-8
Host: s3.us.cloud-object-storage.appdomain.cloud
x-amz-meta-key1: value1
x-amz-meta-key2: value2

Content-Length: 533

 The 'queen' bee is developed from larvae selected by worker bees and fed a
 substance referred to as 'royal jelly' to accelerate sexual maturity. After a
 short while the 'queen' is the mother of nearly every bee in the hive, and
 the colony will fight fiercely to protect her.

示例请求

PUT /apiary/queen-bee HTTP/1.1
Authorization: Bearer {token}
Content-Type: text/plain; charset=utf-8
Content-MD5: M625BaNwd/OytcM7O5gIaQ==
Host: s3.us.cloud-object-storage.appdomain.cloud
x-amz-meta-key1: value1
x-amz-meta-key2: value2

Content-Length: 533

 The 'queen' bee is developed from larvae selected by worker bees and fed a
 substance referred to as 'royal jelly' to accelerate sexual maturity. After a
 short while the 'queen' is the mother of nearly every bee in the hive, and
 the colony will fight fiercely to protect her.

示例响应

HTTP/1.1 200 OK
Date: Thu, 25 Aug 2016 18:30:02 GMT
X-Clv-Request-Id: 9f0ca49a-ae13-4d2d-925b-117b157cf5c3
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.121
X-Clv-S3-Version: 2.5
x-amz-request-id: 9f0ca49a-ae13-4d2d-925b-117b157cf5c3
ETag: "3ca744fa96cb95e92081708887f63de5"
Content-Length: 0

使用 COPY 更新元数据

此处 提供了有关 COPY 请求的完整详细信息。

语法

PUT https://{endpoint}/{bucket-name}/{object-name} # path style
PUT https://{bucket-name}.{endpoint}/{object-name} # virtual host style

示例请求

PUT /apiary/queen-bee HTTP/1.1
Authorization: Bearer {token}
Content-Type: text/plain; charset=utf-8
Host: s3.us.cloud-object-storage.appdomain.cloud
x-amz-copy-source: /apiary/queen-bee
x-amz-metadata-directive: REPLACE
x-amz-meta-key1: value1
x-amz-meta-key2: value2

示例请求

PUT /apiary/queen-bee HTTP/1.1
Authorization: 'AWS4-HMAC-SHA256 Credential={access-key}/{date}/{region}/s3/aws4_request,SignedHeaders=host;x-amz-date;,Signature={signature}'
x-amz-date: {timestamp}
Content-Type: text/plain
Host: s3.us.cloud-object-storage.appdomain.cloud
x-amz-copy-source: /apiary/queen-bee
x-amz-metadata-directive: REPLACE
x-amz-meta-key1: value1
x-amz-meta-key2: value2

示例响应

HTTP/1.1 200 OK
Date: Thu, 25 Aug 2016 18:30:02 GMT
X-Clv-Request-Id: 9f0ca49a-ae13-4d2d-925b-117b157cf5c3
Accept-Ranges: bytes
Server: Cleversafe/3.9.0.121
X-Clv-S3-Version: 2.5
x-amz-request-id: 9f0ca49a-ae13-4d2d-925b-117b157cf5c3
ETag: "3ca744fa96cb95e92081708887f63de5"
Content-Length: 0

后续步骤

在 文档 中了解有关存储区操作的更多信息。