Amazon S3 Glacier
开发人员指南 (API 版本 2012-06-01)
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

启动分段上传(发布分段上传)

描述

此操作会启动分段上传(请参阅分段上传大型档案(分段上传))。Amazon S3 Glacier (Glacier) 将创建分段上传资源并在响应中返回其 ID。在后续的分段上传操作中,您可以使用此上传 ID。

启动分段上传时,您可以指定段大小(以字节数为单位)。段大小必须为 1 兆字节 (1024KB) 乘以 2 的幂—例如,1048576 (1 MB)、2097152 (2 MB)、4194304 (4 MB)、8388608 (8 MB) 等。允许的最小段大小为 1MB,最大为 4GB。

除了最后一段以外,您使用此上传 ID 上传的每一段都必须具有相同的大小。最后一段可以为相同的大小或较小的大小。例如,假设您要上传一个 16.2MB 的文件。如果您以 4MB 的段大小启动分段上传,则您将首先上传四段(每段 4MB),最后再上传一段 (0.2MB)。

注意

启动分段上传时,您不需要知道档案的大小,因为 Glacier 不要求您指定整个档案大小。

在完成分段上传后,Glacier 会删除 ID 引用的分段上传资源。如果您取消分段上传,Glacier 也会删除分段上传资源;或者,如果它在 24 小时内没有活动,则也可能会被删除。24 小时后,该 ID 可能仍然可用,但是应用程序不应期望此行为。

请求

要启动分段上传,您可以将 HTTP POST 请求发送到要在其中保存档案的文件库的 multipart-uploads 子资源 URI。请求必须包括段大小,并且可以选择性地包括档案的描述。

语法

POST /AccountId/vaults/VaultName/multipart-uploads Host: glacier.us-west-2.amazonaws.com.cn Date: Date Authorization: SignatureValue x-amz-glacier-version: 2012-06-01 x-amz-archive-description: ArchiveDescription x-amz-part-size: PartSize

注意

AccountId 值为拥有文件库的账户的 AWS 账户 ID。您可以指定一个 AWS 账户 ID 或者选择指定单一的“-”(连字符),在这种情况下,Amazon S3 Glacier 会使用与用于对请求签名的凭证关联的 AWS 账户 ID。如果您使用账户 ID,请勿在该 ID 中包括连字符 (“-”)。

请求参数

此操作不使用请求参数。

请求标头

除了所有操作都具有的请求头之外,此操作还使用以下请求头。有关通用请求头的更多信息,请参阅常见请求标头

名称 描述 必需
x-amz-part-size

除了最后一段以外的每一段的大小(以字节为单位)。最后一段可以小于此段大小。

类型:字符串

默认值:无

约束:段大小必须为 1 MB (1024KB) 乘以 2 的幂—例如,1048576 (1 MB)、2097152 (2 MB)、4194304 (4 MB)、8388608 (8 MB) 等。允许的最小段大小为 1MB,最大为 4GB (4096MB)。

x-amz-archive-description

您正在分段上传的档案描述。它可以为明语描述或者您选择来分配的某个唯一的标识符。当您取回文件库清单(请参阅“启动作业(POST 作业)”)时,清单会包括因做出响应而返回的每个档案的此描述。档案描述中的前导空白会被删除。

类型:字符串

默认值:无

约束:描述必须小于或等于 1024 字节。允许的字符为不含控制代码的 7 位 ASCII 字符,明确说来就是 ASCII 值为 32-126(十进制)或 0x20-0x7E(十六进制)的字符。

请求正文

此操作没有请求正文。

响应

在响应中,Glacier 会创建由 ID 标识的分段上传资源,并返回分段上传 ID 的相对 URI 路径。

语法

HTTP/1.1 201 Created x-amzn-RequestId: x-amzn-RequestId Date: Date Location: Location x-amz-multipart-upload-id: multiPartUploadId

响应标头

除了所有操作都具有的响应头之外,成功的响应还包括以下响应头。有关通用响应头的更多信息,请参阅常用响应标头

名称 描述
Location

Glacier 创建的分段上传 ID 的相对 URI 路径。您可以使用此 URI 路径来纳入您的请求以上传段,以及完成分段上传。

类型:字符串

x-amz-multipart-upload-id

分段上传的 ID。此值也包括在 Location 标头中,作为该标头的一部分。

类型:字符串

响应正文

此操作不返回响应正文。

错误

有关 Amazon S3 Glacier 异常和错误消息的信息,请参阅错误响应

示例

示例请求

以下示例通过向名为 POST 的文件库的 multipart-uploads 子资源 URI 发送 HTTP examplevault 请求来启动分段上传。该请求包括标头,以指定段大小 4MB(4 194 304 字节)和可选的档案描述。

POST /-/vaults/examplevault/multipart-uploads Host: glacier.us-west-2.amazonaws.com.cn x-amz-Date: 20170210T120000Z x-amz-archive-description: MyArchive-101 x-amz-part-size: 4194304 x-amz-glacier-version: 2012-06-01 Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20141123/us-west-2/glacier/aws4_request,SignedHeaders=host;x-amz-date;x-amz-glacier-version,Signature=9257c16da6b25a715ce900a5b45b03da0447acf430195dcb540091b12966f2a2

响应示例

Glacier 会创建分段上传资源,并将它添加到文件库的 multipart-uploads 子资源。Location 响应标头包括分段上传 ID 的相对 URI 路径。

HTTP/1.1 201 Created x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q Date: Wed, 10 Feb 2017 12:00:00 GMT Location: /111122223333/vaults/examplevault/multipart-uploads/OW2fM5iVylEpFEMM9_HpKowRapC3vn5sSL39_396UW9zLFUWVrnRHaPjUJddQ5OxSHVXjYtrN47NBZ-khxOjyEXAMPLE x-amz-multipart-upload-id: OW2fM5iVylEpFEMM9_HpKowRapC3vn5sSL39_396UW9zLFUWVrnRHaPjUJddQ5OxSHVXjYtrN47NBZ-khxOjyEXAMPLE

有关上传各段的信息,请参阅“上传段(设置上传 ID)”。