此页面仅适用于使用保管库的 S3 Glacier 服务的现有客户以及 2012 年以RESTAPI来的原始客户。
如果您正在寻找档案存储解决方案,我们建议您在亚马逊 S3、S3 Glacier 即时检索、S3 Glacier 灵活检索和 S3 Glacier Deep Archive Dee p Archive 中使用 S3 Glacier 存储类。要了解有关这些存储选项的更多信息,请参阅 Amazon S3 用户指南中的 S3 Glacier 存储类
本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
获取任务输出(获取输出)
描述
此操作会下载您使用 启动 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
值是拥有文件库的账户的 Amazon Web Services 账户 ID。您可以指定 Amazon Web Services 账户 ID,也可以选择指定“-
”(连字符),在这种情况下,Amazon S3 Glacier 使用与用来对请求进行签名的凭证相关联的 Amazon Web Services 账户 ID。如果您使用账户 ID,请勿在 ID 中包含任何连字符 ('-')。
请求参数
此操作不使用请求参数。
请求标头
除了所有操作通用的请求标头外,此操作还使用以下请求标头。有关通用请求标头的信息,请参阅常见请求标头。
名称 | 描述 | 必填 |
---|---|---|
Range
|
要从输出检索的字节范围。例如,如果您要下载前 1048576 字节,请指定范围 如果任务输出很大,则您可以使用
类型:字符串 默认值:无 限制:无 |
否 |
请求正文
此操作没有请求正文。
响应
语法
对于返回所有任务数据的检索请求,任务输出响应会返回 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 返回的字节范围。 例如, 有关 类型:字符串 |
Content-Type
|
内容类型取决于任务输出是档案还是文件库清单。
类型:字符串 |
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.]
相关部分