获取任务输出（获取输出） - Amazon S3 Glacier
描述请求响应示例相关部分

此页面仅适用于使用保管库的 S3 Glacier 服务的现有客户以及 2012 年以RESTAPI来的原始客户。

如果您正在寻找档案存储解决方案，我们建议您在亚马逊 S3、S3 Glacier 即时检索、S3 Glacier 灵活检索和 S3 Glacier Deep Archive Dee p Archive 中使用 S3 Glacier 存储类。要了解有关这些存储选项的更多信息，请参阅 Amazon S3 用户指南中的 S3 Glacier 存储类和使用 S3 Glacier 存储类的长期数据存储。这些存储类别使用 Amazon S3API，适用于所有区域，并且可以在 Amazon S3 控制台中进行管理。它们提供存储成本分析、存储镜头、高级可选加密功能等功能。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

获取任务输出（获取输出）

描述

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

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

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

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

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

请求

语法

要检索任务输出，您可以向特定任务的 GET 的 URI 发送 HTTP output 请求。

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

注意

AccountId 值是拥有文件库的账户的 AWS 账户 ID。您可以指定 AWS 账户 ID，也可以选择指定“-”（连字符），在这种情况下，Amazon S3 Glacier 使用与用来对请求进行签名的凭证相关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符 ('-')。

请求参数

此操作不使用请求参数。

请求标头

除了所有操作通用的请求标头外，此操作还使用以下请求标头。有关通用请求标头的信息，请参阅常见请求标头。

名称 描述 必填
Range

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

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

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

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

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

  4. 下载任务输出的所有段后，您会拥有八个校验和值的列表。计算这些值的树形哈希，以得出整个输出的校验和。使用 描述任务（获取任务 ID） 操作，获取为您提供了输出的任务的任务信息。响应包括 S3 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

S3 Glacier 返回的字节范围。如果只下载部分输出，则响应会提供 S3 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 会作为响应标头返回。

类型：字符串

响应正文

S3 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 日期和时间。即使 S3 Glacier 每天准备一次文件库清单，清单日期也不会随时更新；只有在上次清单盘点后对文件库执行过添加或删除档案的操作时，清单日期才会更新。

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

SHA256TreeHash

档案的树形哈希。

类型：字符串

大小

档案的大小（以字节为单位）。

类型：数字

VaultARN

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

类型：字符串

错误

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

示例

以下示例显示了检索档案的任务的请求。

示例 1：下载输出

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

示例请求 

GET /-/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID/output HTTP/1.1
Host: glacier.us-west-2.amazonaws.com
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：只下载部分输出

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

示例请求 

GET /-/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID/output HTTP/1.1
Host: glacier.us-west-2.amazonaws.com
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 标头，该标头指定了 S3 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.]