大型对象

默认情况下，对象的容量不能超过 5 GB。但是，您可以使用多个较小的对象来构建一个大型对象。大型对象由两种类型的对象组成

• 分段对象存储对象内容。您可以将内容划分为多个分段，并将每个分段上传到自己的分段对象中。分段对象没有任何特殊功能。您可以像处理普通对象一样创建、更新、下载和删除分段对象。

• 一个 清单对象将分段对象链接成一个逻辑上的大型对象。当您下载清单对象时，对象存储会连接并返回响应体中的分段对象内容。此行为扩展到由 GET 和 HEAD 请求返回的响应头。 Content-Length 响应头的值是所有分段对象的大小总和。对象存储通过获取每个分段的 ETag 值，将它们连接在一起，并返回结果的 MD5 校验和来计算 ETag 响应头的值。清单对象的类型有

  静态大型对象

  清单对象的内容是 JSON 格式的有序分段对象名称列表。

  动态大型对象

  清单对象具有 X-Object-Manifest 元数据头。此头的值为 {container}/{prefix}，其中 {container} 是存储分段对象的容器的名称，而 {prefix} 是所有分段对象共有的字符串。清单对象不应包含任何内容。但是，这并非强制执行。

注意

如果您使用清单对象作为源执行 COPY 请求，则新对象将是一个普通对象，而不是分段对象。如果源分段对象的大小总和超过 5 GB，则 COPY 请求将失败。但是，您可以复制清单对象，并且此新对象可以大于 5 GB。

静态大型对象

要创建静态大型对象，请将内容划分为多个部分，并创建（上传）一个分段对象来包含每个部分。

创建一个清单对象。在清单对象名称的末尾包含 multipart-manifest=put 查询参数，以指示这是一个清单对象。

清单对象上的 PUT 请求的主体是一个 json 列表，其中每个元素都是一个代表分段的对象。这些对象可以包含以下属性

• path（必需）。容器和对象名称的格式为：{container-name}/{object-name}

• etag（可选）。如果提供，此值必须与分段对象的 ETag 匹配。这包含在创建分段时响应头中。通常，这将是分段的 MD5 总和。

• size_bytes（可选）。分段对象的大小。如果提供，此值必须与该对象的内容长度 Content-Length 匹配。

• range（可选）。应使用分段数据的引用对象的子集。此行为类似于 Range 头。如果省略，将使用整个对象。

为每个分段提供可选的 etag 和 size_bytes 属性可确保上传不会损坏您的数据。

示例静态大型对象清单列表

此示例显示了三个分段对象。您可以使用多个容器，并且对象名称不必符合特定模式，与动态大型对象相反。

[
    {
        "path": "mycontainer/objseg1",
        "etag": "0228c7926b8b642dfb29554cd1f00963",
        "size_bytes": 1468006
    },
    {
        "path": "mycontainer/pseudodir/seg-obj2",
        "etag": "5bfc9ea51a00b790717eeb934fb77b9b",
        "size_bytes": 1572864
    },
    {
        "path": "other-container/seg-final",
        "etag": "b9c3da507d2557c1ddc51f27c54bae51",
        "size_bytes": 256
    }
]

Content-Length 请求头必须包含 json 内容的长度——而不是分段对象的大小。但是，在 PUT 操作完成后，Content-Length 元数据设置为所有对象分段的总长度。在使用 PUT 操作中的 ETag 请求头时，它必须包含对象分段的 ETag 值的连接 MD5 校验和。您还可以设置 Content-Type 请求头和自定义对象元数据。

当 PUT 操作看到 multipart-manifest=put 查询参数时，它会读取请求主体并验证每个分段对象是否存在，并且大小和 ETag 匹配。如果存在不匹配，则 PUT 操作将失败。

此验证过程可能需要很长时间才能完成，尤其是在分段数量增加时。您可以包含 heartbeat=on 查询参数，以便服务器

1. 在开始验证分段之前发送 202 Accepted 响应，

2. 定期发送空格字符以保持连接活动，以及

3. 在主体中发送最终响应代码。

注意

如果服务器能够在进行后端请求之前确定请求无效，则服务器仍然可以立即使用 400 Bad Request 响应。

如果一切匹配，则创建清单对象。将 X-Static-Large-Object 元数据设置为 true，指示这是一个静态对象清单。

通常，当您对清单对象执行 GET 操作时，响应主体包含分段对象的连接内容。要下载清单列表，请使用 multipart-manifest=get 查询参数。生成的列表的格式与最初在 PUT 操作中使用的清单不同。

如果您对清单对象使用 DELETE 操作，则会删除清单对象。分段对象不受影响。但是，如果您添加 multipart-manifest=delete 查询参数，则会删除分段对象，如果所有分段都成功删除，清单对象也会被删除。

要更改清单，请使用带有 multipart-manifest=put 查询参数的 PUT 操作。此请求创建一个清单对象。您还可以以通常的方式更新对象元数据。

动态大型对象

您必须在上传之前对大于 5 GB 的对象进行分段。然后，您像上传任何其他对象一样上传分段对象，并创建一个动态大型清单对象。清单对象告诉对象存储如何找到构成大型对象的段对象。分段仍然可以单独寻址，但检索清单对象会流式传输所有分段的连接内容。单个大型对象可以包含的分段数量没有限制，但如果分段数量小于容器列表限制，则 Content-Length 仅包含在 GET 或 HEAD 响应中。换句话说，适合单个容器列表页面的分段数量。

为了确保下载正常工作，您必须将所有对象分段上传到同一个容器，并确保每个对象名称都以某种方式进行前缀，以便按应连接的顺序进行排序。您还需要创建并上传一个清单文件。清单文件是一个零字节文件，带有额外的 X-Object-Manifest {container}/{prefix} 头，其中 {container} 是对象分段所在的容器，而 {prefix} 是所有分段的通用前缀。您必须对容器和通用前缀进行 UTF-8 编码，然后在 X-Object-Manifest 头中进行 URL 编码。

最好先上传所有分段，然后再创建或更新清单。使用此方法，在上传完成之前，整个对象不可用于下载。此外，您可以将一组新的分段上传到第二个位置，并更新清单以指向此新位置。在上传新的分段期间，原始清单仍然可用于下载第一组分段。

注意

在使用 POST 请求更新清单对象时，必须包含 X-Object-Manifest 头，以便对象继续作为清单对象运行。

示例上传大型对象分段请求：HTTP

PUT /{api_version}/{account}/{container}/{object} HTTP/1.1
Host: storage.clouddrive.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
ETag: 8a964ee2a5e88be344f36c22562a6486
Content-Length: 1
X-Object-Meta-PIN: 1234

不返回响应主体。状态代码为 2``nn``（包括 200 到 299 之间）表示写入成功；状态 411 Length Required 表示请求中缺少 Content-Length 或 Content-Type 头。如果写入到存储系统的 MD5 校验和与（可选）提供的 ETag 值不匹配，则返回 422 Unprocessable Entity 响应。

您可以在此示例所示之前继续上传分段。

示例上传大型对象的下一个分段请求：HTTP

PUT /{api_version}/{account}/{container}/{object} HTTP/1.1
Host: storage.clouddrive.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
ETag: 8a964ee2a5e88be344f36c22562a6486
Content-Length: 1
X-Object-Meta-PIN: 1234

接下来，上传您创建的指示对象分段所在容器的清单。

示例上传清单请求：HTTP

PUT /{api_version}/{account}/{container}/{object} HTTP/1.1
Host: storage.clouddrive.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
Content-Length: 0
X-Object-Meta-PIN: 1234
X-Object-Manifest: {container}/{prefix}

示例上传清单响应：HTTP

[...]

在对清单执行 GET 或 HEAD 操作时，Content-Type 与在创建清单的 PUT 请求期间设置的 Content-Type 相同。您可以很容易地通过重新发出 PUT 请求来更改 Content-Type。

静态和动态大型对象的比较

虽然静态对象和动态对象具有相似的行为，但以下是它们的区别

端到端完整性

对于静态大型对象，可以保证完整性。列表可以包含每个分段的 MD5 校验和（ETag）。如果列表中的 ETag 与上传的分段对象不同，则无法上传清单对象。如果某个分段丢失，则尝试下载清单对象会导致错误。

对于动态大型对象，不保证完整性。最终一致性模型意味着，即使您已上传了分段对象，它可能在稍后才会出现在容器列表中。如果您在它出现在容器之前下载清单，它不会形成响应中返回的内容。

上传顺序

对于静态大型对象，您必须先上传分段对象，然后才能上传清单对象。

对于动态大型对象，您可以按任何顺序上传清单和分段对象。如果过早下载清单，我们建议用户在分段之后上传清单。但是，系统不会强制执行顺序。

删除或添加分段对象

对于静态大型对象，您无法从清单中添加或删除分段对象。但是，您可以创建一个具有不同清单列表的相同名称的全新清单对象。

对于动态大型对象，您可以上传新的分段对象或删除现有分段。名称必须简单地与 X-Object-Manifest 中提供的 {prefix} 匹配。

分段对象大小和数量

对于静态大型对象，分段对象的大小必须至少为 1 字节。但是，如果分段对象小于 1MB（默认情况下），则 SLO 下载（默认情况下）受到速率限制。最多支持 1000 个分段（默认情况下），并且清单的大小（默认情况下）限制为 2MB。

对于动态大型对象，分段对象的大小可以是任意大小。

分段对象容器名称

对于静态大对象，清单列表包含每个对象所在的容器名称。分段对象可以位于不同的容器中。

对于动态大对象，所有分段对象必须位于同一个容器中。

清单对象元数据

对于静态大对象，清单对象会将 X-Static-Large-Object 设置为 true。您无需直接设置此元数据。系统在您 PUT 静态清单对象时会自动设置它。

对于动态大对象，X-Object-Manifest 的值是 {container}/{prefix}，它指示分段对象的位置。您需要在 PUT 操作中提供此请求头。

复制清单对象

对于静态和动态大对象，语义相同。复制大对象时，COPY 操作不会创建清单对象，而是创建一个与向原始清单对象发送 GET 请求所获得的内容相同的普通对象。

要复制清单对象，您需要在 COPY 请求中包含 multipart-manifest=get 查询参数。新对象包含与原始对象相同的清单。分段对象不会被复制。相反，原始清单对象和新清单对象共享相同的一组分段对象。