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

获取任务输出(获取输出)

描述

此操作会下载您使用 启动作业(POST 作业) 启动的任务的输出。根据您在启动任务时指定的任务类型,输出将为档案的内容或文件库清单。

您可以下载所有任务输出,也可以通过指定字节范围下载输出的一部分。对于档案和清单检索任务,您应针对在 Get Job Output 响应的标头中返回的大小对下载大小进行验证。

对于档案检索任务,还应验证大小是否与预期相符。如果下载部分输出,则预期大小基于您指定的字节范围。例如,如果指定 bytes=0-1048575 范围,则需要验证下载大小为 1048576 字节。如果下载整个档案,则预期大小是您上传到 Amazon Glacier 的档案的大小。Get Job Output 响应的标头中也会返回预期大小。

对于档案检索任务的情况,根据您指定的字节范围,Amazon Glacier 返回该部分数据的校验和。要确保您下载的部分是正确的数据,请在客户端计算校验和,验证值是否匹配,并且验证大小是否和预期一致。

Amazon Glacier 完成任务后,任务 ID 至少在 24 小时内都不会过期。也就是说,您可以在 Amazon Glacier 完成任务后的 24 小时期限内下载任务输出。

请求

语法

要取回任务输出,您可以向特定任务的 output 的 URI 发送 HTTP GET 请求。

GET /AccountId/vaults/VaultName/jobs/JobID/output HTTP/1.1 Host: glacier.Region.amazonaws.com.cn Date: Date Authorization: SignatureValue Range: ByteRangeToRetrieve x-amz-glacier-version: 2012-06-01

注意

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

请求参数

此操作不使用请求参数。

请求标头

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

名称 描述 必需
Range

要从输出取回的字节范围。例如,如果您要下载前 1048576 字节,请指定范围 bytes=0-1048575。有关更多信息,请转到“范围标头字段定义”。该范围与启动任务请求中指定的任何范围是相对而言的。默认情况下,此操作会下载整个输出。

如果任务输出很大,则您可以使用 Range 请求标头来取回输出的一部分。这样,您能够以较小的字节区块下载整个输出。例如,假设您有 1GB 任务输出需要下载,您决定一次下载 128MB 数据区块,则总共有八个获取任务输出请求。您将使用以下流程下载任务输出:

  1. 通过使用 Range 标头指定相应的字节范围来下载 128MB 输出区块。验证是否收到所有 128MB 数据。

  2. 随数据一起,响应将包括有效负载的校验和。您可以计算客户端有效负载的校验和,并将它与您在响应中接收到的校验和相比较,以确保您收到了所有预期的数据。

  3. 对输出数据的所有八个 128MB 区块重复执行步骤 1 和 2,每次都指定相应的字节范围。

  4. 下载任务输出的所有段后,您会拥有八个校验和值的列表。计算这些值的树形哈希,以得出整个输出的校验和。使用 描述任务(获取任务 ID) 操作,获取为您提供了输出的任务的任务信息。响应包括 Amazon Glacier 中存储的整个档案的校验和。您可以将此值与您计算的校验和相比较,以确保您正确地下载了整个档案内容。

类型:字符串

默认值:无

限制:无

请求正文

此操作没有请求正文。

响应

语法

对于返回所有任务数据的取回请求,任务输出响应会返回 200 OK 响应代码。当请求部分内容(例如,如果您在请求中指定了 Range 标头)时,则会返回响应代码 206 Partial Content

HTTP/1.1 200 OK x-amzn-RequestId: x-amzn-RequestId Date: Date Content-Type: ContentType Content-Length: Length x-amz-sha256-tree-hash: ChecksumComputedByAmazonGlacier [Body containing job output.]

响应标头

标头 描述
Content-Range

Amazon Glacier 返回的字节范围。如果只下载部分输出,则响应会提供 Amazon Glacier 返回的字节范围。

例如,bytes 0-1048575/8388608 会从 8MB 返回前 1MB。

有关 Content-Range 标头的更多信息,请转到“内容范围标头字段定义”

类型:字符串

Content-Type

内容类型取决于任务输出是档案还是文件库清单。

  • 对于档案数据,内容类型为 application/octet-stream

  • 对于文件库清单,如果您在启动任务时请求了 CSV 格式,则内容类型为 text/csv。否则,默认情况下,以 JSON 返回文件库清单,并且内容类型为 application/json

类型:字符串

x-amz-sha256-tree-hash

响应中的数据的校验和。只有在取回档案取回任务的输出时,才会返回此标头。此外,如果启动任务请求中请求的取回数据范围以树形哈希对齐,并且获取任务输出中要下载的范围也以树形哈希对齐,则此标头会显示。有关以树形哈希对齐的范围的更多信息,请参阅“下载数据时接收校验和”。

例如,如果您在您的启动任务请求中指定了要取回的以树形哈希对齐的范围(包括整个档案),则您将收到您在以下条件下下载的数据的校验和:

  • 您获取了取回数据的整个范围。

  • 您请求了取回数据的字节范围,该数据的大小为 1 兆字节 (1024KB) 乘以 2 的幂,并且其起始位置和结束位置为请求范围大小的倍数。例如,如果您有 3.1MB 的取回数据,并且您指定了要返回的范围(该范围起始于 1MB,结束于 2MB),则 x-amz-sha256-tree-hash 会作为响应标头返回。

  • 您请求了取回数据中要返回的范围(该范围的结束位置为数据的结束位置),该范围的起始位置为要取回的范围向上舍入到下一个 2 的幂但不小于 1 兆字节 (1024KB) 的大小的倍数。例如,如果您有 3.1MB 的取回数据,并且您指定了范围(该范围起始于 2MB,结束于数据的结束位置 3.1MB),则 x-amz-sha256-tree-hash 会作为响应标头返回。

类型:字符串

响应正文

Amazon Glacier 会在响应正文中返回任务输出。根据任务类型,输出可以为档案内容或文件库清单。如果为文件库清单,则默认情况下,清单列表会作为以下 JSON 正文返回。

{ "VaultARN": String, "InventoryDate": String, "ArchiveList": [ {"ArchiveId": String, "ArchiveDescription": String, "CreationDate": String, "Size": Number, "SHA256TreeHash": String }, ... ] }

如果您在启动文件库清单任务时请求了 CSV 格式,则文件库清单会以 CSV 格式返回在正文中。该 CSV 格式有五列:“ArchiveId”、“ArchiveDescription”、“CreationDate”、“Size”和“SHA256TreeHash”,它们的定义与相应 JSON 字段的定义相同。

注意

在返回的 CSV 格式中,返回的字段可能整个字段用双引号括起来。包含逗号或双引号的字段在返回时始终用双引号括起来。例如,my archive description,1 返回为 "my archive description,1"。用双引号括起来的返回字段中的双引号字符通过在前面附加反斜杠字符来转义。例如,my archive description,1"2 返回为 "my archive description,1\"2"my archive description,1\"2 返回为 "my archive description,1\\"2"。反斜杠字符不进行转义。

JSON 响应正文包含以下 JSON 字段。

ArchiveDescription

档案的描述。

类型:字符串

ArchiveId

档案的 ID。

类型:字符串

ArchiveList

档案元数据数组。数组中的每个数据元均表示文件库中包含的一个档案的元数据。

类型:数组

CreationDate

创建档案的 UTC 日期和时间。

类型:ISO 8601 日期格式的字符串表示形式,例如,2013-03-20T17:03:43.221Z

InventoryDate

对文件库进行更改后完成文件库上次编制清单的 UTC 日期和时间。即使 Amazon Glacier 每天准备一次文件库清单,清单日期也不会随时更新;只有在上次清单盘点后对文件库执行过添加或删除档案的操作时,清单日期才会更新。

类型:ISO 8601 日期格式的字符串表示形式,例如,2013-03-20T17:03:43.221Z

SHA256TreeHash

档案的树形哈希。

类型:字符串

Size

档案的大小(以字节为单位)。

类型:数字

VaultARN

从中请求档案取回的Amazon 资源名称 (ARN) 资源。

类型:字符串

错误

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

示例

以下示例显示了取回档案的任务的请求。

示例 1:下载输出

此示例会检索 Amazon Glacier 因响应您的启动档案检索任务请求而准备的数据。

示例请求

GET /-/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID/output HTTP/1.1 Host: glacier.us-west-2.amazonaws.com.cn x-amz-Date: 20170210T120000Z 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

响应示例

以下是档案取回任务的示例响应。请注意,Content-Type 标头为 application/octet-stream,并且 x-amz-sha256-tree-hash 标头包括在响应中,这意味着返回所有任务数据。

HTTP/1.1 200 OK x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q x-amz-sha256-tree-hash: beb0fe31a1c7ca8c6c04d574ea906e3f97b31fdca7571defb5b44dca89b5af60 Date: Wed, 10 Feb 2017 12:00:00 GMT Content-Type: application/octet-stream Content-Length: 1048576 [Archive data.]

以下是清单取回任务的示例响应。请注意,Content-Type 标头为 application/json。另请注意,响应不包括 x-amz-sha256-tree-hash 标头。

HTTP/1.1 200 OK x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q Date: Wed, 10 Feb 2017 12:00:00 GMT Content-Type: application/json Content-Length: 906 { "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault", "InventoryDate": "2011-12-12T14:19:01Z", "ArchiveList": [ { "ArchiveId": "DMTmICA2n5Tdqq5BV2z7og-A20xnpAPKt3UXwWxdWsn_D6auTUrW6kwy5Qyj9xd1MCE1mBYvMQ63LWaT8yTMzMaCxB_9VBWrW4Jw4zsvg5kehAPDVKcppUD1X7b24JukOr4mMAq-oA", "ArchiveDescription": "my archive1", "CreationDate": "2012-05-15T17:19:46.700Z", "Size": 2140123, "SHA256TreeHash": "6b9d4cf8697bd3af6aa1b590a0b27b337da5b18988dbcc619a3e608a554a1e62" }, { "ArchiveId": "2lHzwhKhgF2JHyvCS-ZRuF08IQLuyB4265Hs3AXj9MoAIhz7tbXAvcFeHusgU_hViO1WeCBe0N5lsYYHRyZ7rrmRkNRuYrXUs_sjl2K8ume_7mKO_0i7C-uHE1oHqaW9d37pabXrSA", "ArchiveDescription": "my archive2", "CreationDate": "2012-05-15T17:21:39.339Z", "Size": 2140123, "SHA256TreeHash": "7f2fe580edb35154041fa3d4b41dd6d3adaef0c85d2ff6309f1d4b520eeecda3" } ] }

示例 2:只下载部分输出

此示例只检索 Amazon Glacier 因响应您的启动档案检索任务请求而准备的档案的一部分。该请求使用了可选的 Range 标头,以便只取回前 1024 字节。

示例请求

GET /-/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID/output HTTP/1.1 Host: glacier.us-west-2.amazonaws.com.cn x-amz-Date: 20170210T120000Z Range: bytes=0-1023 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

响应示例

以下成功的响应显示了 206 Partial Content 响应。在此案例中,响应还包括 Content-Range 标头,该标头指定了 Amazon Glacier 返回的字节范围。

HTTP/1.1 206 Partial Content x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q Date: Wed, 10 Feb 2017 12:00:00 GMT Content-Range: bytes 0-1023/8388608 Content-Type: application/octet-stream Content-Length: 1024 [Archive data.]