大型对象

updated: 2017-07-18 08:53

大型对象

大型对象¶

要查看你的对象存储系统是否支持这些特性，请见参考:`discoverability`或者与你的服务供应商核实。

默认情况下，对象的内容不能大于5CB。然而，你可以使用一些较小的对象来构建一个大的对象。这个大的对象是由两种类型的对象组成的：

“Segment objects”存储对象内容。您可以将您的内容分为段，并将每一段上传到它自己的段对象中。段对象没有任何特殊的功能。您与正常对象一样创建、更新、下载和删除段对象。
“清单对象”将段对象链接到一个大的逻辑对象中。当你下载一个清单对象，对象存储连接和响应体返回段对象的内容。这种行为延伸到由“GET”和“HEAD”请求返回的响应的头部。“Content-Length”反应头部包含的所有段对象的总大小。

对象存储获取每个segment的``ETag``值，将其合并并返回MD5作为响应消息头 ``ETag``的的值。骂你fest对象类型为：

静态大型对象

manifest对象内容为segment名称组成的JSON格式的有序列表。请参考静态大型对象.

动态大型对象

manifest对象只有一个``X-Object-Manifest`` 元数据头。其值为``CONTAINER/PREFIX``, 其中``CONTAINER`` 为segment对象所在的容器名称，PREFIX 为所有segment对象共有的字符串值。请参考动态大型对象.

注解

如果使用一个manifest对象作为``COPY``请求的源，新的对象为正常的对象而不是segment对象。如果源segmeng对象超过5 GB，COPY 请求会失败。不过，可以制作manifest对象的副本，新对象的大小可以超过5 GB.

静态大型对象¶

如需创建静态大型对象，可以将内容分割为多个部分并为每一部分创建一个segment对象。

必须记录``PUT``请求的响应消息中的 ETag 值。或者在上传之前计算segment的MD5值并设置到请求消息头``ETag`` 中。这样可以保证上传操作不会破坏数据。

按顺序列出segment对象的名称、大小和MD5值。

创建manifest对象。在名称后添加``?multipart-manifest=put``查询参数标明是一个manifest对象。

``PUT``请求消息中JSON各节点包含以下属性：

路径: 容器和对象名称格式：CONTAINER_NAME/OBJECT_NAME.
etag: 对段对象内容的MD5校验。这个值必须匹配该对象的“ Etag ”。
size_bytes: 段对象的大小。这个值必须匹配该对象的“Content-Length”。

静态大型对象manifest列表¶

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

[
    {
        "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内容的长度，而不是segment对象的长度。然而``PUT 操作结束后，Content-Length 元数据被设置为所有对象的长度。相同的情形也适用于``ETag``。如果在``PUT``操作中使用，它必须包含JSON内容的MD5校验值。然后``ETag``元数据值被设置为segment对象的``ETag``级联值的MD5校验值。你也可以设置``Content-Type``请求头部和自定义对象元数据。

When the PUT operation sees the ?multipart-manifest=put query parameter, it reads the request body and verifies that each segment object exists and that the sizes and ETags match. If there is a mismatch, the PUT operation fails.

如果全部匹配，API创建manifest对象并设置元数据``X-Static-Large-Object``为``true``, 标明manifest是静态对象。

正常情况下，对manifest对象发起``GET``操作时，响应消息体包含合并后的segment对象。可以通过查询参数``?multipart-manifest=get``来下载manifest列表。响应中的内容未格式化。

使用``DELETE``可以删除manifest对象。segment对象不受影响。然而，添加``?multipart-manifest=delete``可以删除segment对象。如果segment对象成功删除，manifest对象也会被删除。

使用 PUT``请求和?multipart-manifest=put``可以修改manifest. 该请求会创建一个manifest对象。也可以更新对象的元数据。

动态大型对象¶

上传5GB以上的对象前须将其分段。上传segment对象方式同其他对象，创建动态大型manifest对象。该对象告知对象存储服务如何发现其segment对象。你仍可以单独访问每个segment对象，但访问manifest对象时，API会将segment对象合并。在一个大型对象中可以包含任意数量的segment.

为保证下载正常执行，必须将全部对象片段上传到同一容器且按顺序添加名称前缀。

可以创建并上传manifest文件。manifest文件是一个带有 X-Object-Manifest 和``CONTAINER/PREFIX``头的0字节文件。CONTAINER 是包含对象片段的容器，``PREFIX``是对象片段名称前缀。``X-Object-Manifest``的值必须经过UTF-8和URL-encode编码。

最好先上传所有对象片段然后创建并上传manifest. 这样可以保证完整对象上传完成前不能被下载。另外，也可以上传一组新的对象片段到一个新的位置，然后更新一个已有的manifest使其指向这个位置。上传过程中，manifest仍指向原来的对象片段组，仍是可用的。

上传大型对象片段: HTTP¶

PUT /API_VERSION/ACCOUNT/CONTAINER/OBJECT HTTP/1.1
Host: storage.example.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
ETag: 8a964ee2a5e88be344f36c22562a6486
Content-Length: 1
X-Object-Meta-PIN: 1234

无响应体返回

类似2``nn``形式的响应码表示成功写入. nn 是 00 到 99 之间的值。

Length Required (411)``响应码表示请求缺少``Content-Length 或 Content-Type 请求头.

``Unprocessable Entity (422)``响应码表示写入存储系统的数据的MD5值与请求时提供的ETag值不一致。

上传manifest之前可以继续上传片段对象，如示例中展示。

上传下一个大型对象片段请求: HTTP¶

PUT /API_VERSION/ACCOUNT/CONTAINER/OBJECT HTTP/1.1
Host: storage.example.com
X-Auth-Token: eaaafd18-0fed-4b3a-81b4-663c99ec1cbb
ETag: 8a964ee2a5e88be344f36c22562a6486
Content-Length: 1
X-Object-Meta-PIN: 1234

然后上传声明文件。该文件指定了对象segments所在容器。注意，如果在创建声明文件后上传额外的segments, 不需要重新创建声明文件。

上传 manifest 请求: 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

上传 manifest 响应: HTTP¶

[...]

对manifest的``GET`` 或 HEAD 请求返回的``Content-Type``响应头，与创建manifest的 PUT 请求中的``Content-Type``值是一致的。如需改变这个值，可以重新发送``PUT`` 请求。

额外事务信息¶

可以使用``X-Trans-Id-Extra``请求头携带信息，用来定位上传大型对象及对象存储事务相关错误。

对象存储API会将``X-Trans-Id-Extra``的前32个字符添加到响应头的``X-Trans-Id`` 值中。发送请求前，``X-Trans-Id-Extra``的值须经过UTF-8和URL-encode编码。

例如，当您上传大的对象如镜像时，您可以计入额外的业务信息。

上传对象片段和manifest时，每次请求都要包含相同的 ``X-Trans-Id-Extra``请求头。如果发生错误，可以在对象存储日志中找到与该大型对象相关的所有请求。

可以使用``X-Trans-Id-Extra``请求头来帮助定位无法收到响应的问题。可以在日志中搜索该请求头的值。

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

静态和动态大型对象具有相同的行为，该表格展示它们的不同之处：

描述	静态大型对象	动态大型对象
端对端通信完整性	当然，段列表中包含每个段的MD5校验合（“ETag”）。如果上传的段对象的（“ETag”）与列表中的不同，则对象清单无法上传。如果某些段数据丢失，尝试下载对象清单会出错。	不确定。最终连续模型意味着，尽管你已经上传了段对象，但是它可能不会立即出现在容器列表中，如果你在它未出现在容器之前下载了清单，它不会生成一个不完整的内容来回应GET请求。
上传顺序	上传manifest对象前必须上传对象片段。	可以按任意顺序上传manifest和对象片段。建议完成对象片段上传后再上传manifest以避免提前下载manifest. 然而这不是强制的。
移除或增加对象片段	不能从manifest中增加或移除对象片段。然而可以创建一个新的同名manifest对象，指向不同的对象列表。	可以上传新的对象片段或移除已有的对象片段。名称要符合``X-Object-Manifest``中提供的 ``PREFIX``规则。
段对象大小和序号	默认情况下段对象最小为1MB. 最后一个段对象可以为任意大小。默认最多支持1000个段对象。	段对象可以为任意大小。
段对象容器名称	manifest列表包含每个对象的容器名。段对象可以位于不同的容器。	所有段对象必须在同一容器。
manifest对象元数据	对象的``X-Static-Large-Object``被设置为``true``. 不能直接设置该元数据。``PUT``静态manifest对象时系统自动设置该值。	X-Object-Manifest``的值为``CONTAINER/PREFIX，表示段对象位置。在 `PUT` 请求中提供该请求头。
复制manifest对象	在``COPY``请求中包含 ``?multipart-manifest=get`查询参数。新的对象包含于原对象相同的manifest. 段对象不会被复制。原有的和新的manifest共享相同的段对象。	``COPY``操作不会创建manifest对象。如需复制manifest对象，使用``GET``操作读取 ``X-Object-Manifest``的值并将该值作为``PUT``请求的``X-Object-Manifest``请求头的值。这样可以创建一个新的manifest对象，指向原有的manifest的段对象。

Upload large objects with python-swiftclient¶

You can use python-swiftclient to easily upload large objects.

Upload a large file by specifying the segment size with the --segment-size or -S arguments:
```
$ swift upload CONTAINER OBJECT_FILENAME --segment-size <bytes>
```
This will automatically break the file into the desired segment size and upload segments to a container named <container>_segments.
After upload has completed, you can download the large object as a single file:
```
$ swift download CONTAINER OBJECT_FILENAME
```
Additional large object arguments can be found by using --help:
```
$ swift upload --help
```