**此页面仅适用于使用文件库和 2012 年原始 REST API 的 Amazon Glacier 服务的现有客户。** 如果您正在寻找归档存储解决方案，建议使用 Amazon S3 中的 Amazon Glacier 存储类别 S3 Glacier Instant Retrieval、S3 Glacier Flexible Retrieval 和 S3 Glacier Deep Archive。要了解有关这些存储选项的更多信息，请参阅 [Amazon Glacier 存储类别](https://aws.amazon.com/s3/storage-classes/glacier/)。 Amazon Glacier（最初基于保管库的独立服务）不再接受新客户。Amazon Glacier 是一项独立的服务 APIs ，拥有自己的服务，可将数据存储在文件库中，不同于亚马逊 S3 和 Amazon S3 Glacier 存储类别。在 Amazon Glacier 中，您现有的数据将确保安全，并且可以无限期地访问。无需进行迁移。对于低成本、长期的存档存储， AWS 建议[使用 Amazon S3 Glacier 存储类别，这些存储类别](https://aws.amazon.com/s3/storage-classes/glacier/)基于S3存储桶 APIs、完全 AWS 区域 可用性、更低的成本和 AWS 服务集成，可提供卓越的客户体验。如果您希望加强功能，可以考虑使用我们的 [AWS 将数据从 Amazon Glacier 文件库传输到 Amazon S3 Glacier 存储类别的解决方案指南](https://aws.amazon.com/solutions/guidance/data-transfer-from-amazon-s3-glacier-vaults-to-amazon-s3/)，迁移到 Amazon S3 Glacier 存储类别。 本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 任务操作 以下是可供在 Amazon Glacier 中使用的任务操作。 **Topics** + [描述任务（GET JobID）](api-describe-job-get.md) + [获取任务输出（GET output）](api-job-output-get.md) + [启动任务（POST jobs）](api-initiate-job-post.md) + [列出任务（GET jobs）](api-jobs-get.md) # 描述任务（GET JobID） ## 说明 此操作返回有关您之前启动的任务的信息，包括任务启动日期、启动任务的用户、任务状态代码/消息，以及要在 Amazon Glacier（Amazon Glacier）完成任务后通知的 Amazon Simple Notification Service（Amazon SNS）主题。有关启动任务的更多信息，请参阅[启动任务（POST jobs）](api-initiate-job-post.md)。 **注意** 此操作可让您检查您的任务的状态。但是，我们强烈建议您设置 Amazon SNS 主题并在您的启动任务请求中指定它，这样，Amazon Glacier 可以在完成任务后通知该主题。 Amazon Glacier 完成任务后，任务 ID 至少在 24 小时内都不会过期。 ## 请求 ### 语法 要获取有关任务的信息，您可以使用 HTTP `GET` 方法，并将请求纳入到特定任务中。请注意，相对 URI 路径是您在启动任务时 Amazon Glacier 返回给您的同一路径。 ``` 1. GET /AccountID/vaults/VaultName/jobs/JobID HTTP/1.1 2. Host: glacier.Region.amazonaws.com 3. Date: date 4. Authorization: signatureValue 5. x-amz-glacier-version: 2012-06-01 ``` **注意** 该`AccountId`值是拥有文件库的账户的 AWS 账户 ID。您可以指定一个 AWS 账户 ID，也可以选择指定一个 '`-`'（连字符），在这种情况下，Amazon Glacier 使用与用于签署请求的凭证关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符（-）。 **注意** 在该请求中，如果您省略 `JobID`，则响应会返回指定文件库中所有有效任务的列表。有关列出任务的更多信息，请参阅[列出任务（GET jobs）](api-jobs-get.md)。 ### 请求参数 此操作不使用请求参数。 ### 请求标头 此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。 ### 请求正文 此操作没有请求正文。 ## 响应 ### 语法 ``` HTTP/1.1 201 Created x-amzn-RequestId: x-amzn-RequestId Date: Date Content-Type: application/json Content-Length: Length { "Action": "string", "ArchiveId": "string", "ArchiveSHA256TreeHash": "string", "ArchiveSizeInBytes": number, "Completed": boolean, "CompletionDate": "string", "CreationDate": "string", "InventoryRetrievalParameters": { "EndDate": "string", "Format": "string", "Limit": "string", "Marker": "string", "StartDate": "string" }, "InventorySizeInBytes": number, "JobDescription": "string", "JobId": "string", "JobOutputPath": "string", "OutputLocation": { "S3": { "AccessControlList": [ { "Grantee": { "DisplayName": "string", "EmailAddress": "string", "ID": "string", "Type": "string", "URI": "string" }, "Permission": "string" } ], "BucketName": "string", "CannedACL": "string", "Encryption": { "EncryptionType": "string", "KMSContext": "string", "KMSKeyId": "string" }, "Prefix": "string", "StorageClass": "string", "Tagging": { "string": "string" }, "UserMetadata": { "string": "string" } } }, "RetrievalByteRange": "string", "SelectParameters": { "Expression": "string", "ExpressionType": "string", "InputSerialization": { "csv": { "Comments": "string", "FieldDelimiter": "string", "FileHeaderInfo": "string", "QuoteCharacter": "string", "QuoteEscapeCharacter": "string", "RecordDelimiter": "string" } }, "OutputSerialization": { "csv": { "FieldDelimiter": "string", "QuoteCharacter": "string", "QuoteEscapeCharacter": "string", "QuoteFields": "string", "RecordDelimiter": "string" } } }, "SHA256TreeHash": "string", "SNSTopic": "string", "StatusCode": "string", "StatusMessage": "string", "Tier": "string", "VaultARN": "string" } ``` ### 响应标头 此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。 ### 响应正文 响应正文包含以下 JSON 字段。 **Action** 任务类型。它为 `ArchiveRetrieval`、`InventoryRetrieval` 或 `Select`。 *类型*：字符串 **ArchiveId** 为选择任务或档案检索任务请求的档案 ID。否则，此字段为 `null`。 *类型*：字符串 **存档SHA256TreeHash** 档案检索任务的整个档案的 SHA256 树形哈希。对于清单检索任务，此字段为 `null`。 *类型*：字符串 **ArchiveSizeInBytes** 对于 `ArchiveRetrieval` 任务，这是正在请求下载的档案的大小（以字节为单位）。对于 `InventoryRetrieval` 任务，该值为 `null`。 *类型*：数字 **Completed** 任务状态。当档案或清单检索任务完成后，您将使用[获取任务输出（GET output）](api-job-output-get.md)来获取任务的输出。 *类型*：布尔值 **CompletionDate** 任务请求完成时的通用协调时间（UTC）时间。当任务正在进行时，该值将为空。 *类型*：字符串 **CreationDate** 创建任务的 UTC 时间。 *类型*：以 ISO 8601 日期格式表示的字符串，例如 `2013-03-20T17:03:43.221Z`。 **InventoryRetrievalParameters** 用于范围清单检索的输入参数。 *类型*：[InventoryRetrievalJobInput](api-InventoryRetrievalJobInput.md) 对象 **InventorySizeInBytes** 对于 `InventoryRetrieval` 任务，这是请求下载的清单的大小（以字节为单位）。对于 `ArchiveRetrieval` 或 `Select` 任务，该值为 `null`。 *类型*：数字 **JobDescription** 您在启动任务时提供的任务描述。 *类型*：字符串 **JobId** 标识 Amazon Glacier 中的任务的 ID。 *类型*：字符串 **JobOutputPath** 包含任务输出位置。 *类型*：字符串 **OutputLocation** 一个对象，其中包含有关选择任务结果和错误的存储位置的信息。 *类型*：[OutputLocation](api-OutputLocation.md) 对象 **RetrievalByteRange** 档案检索任务的检索字节范围，格式为 “*StartByteValue*-*EndByteValue*。” 如果您未在档案检索中指定范围，则会检索整个档案；也*StartByteValue*等于 0，*EndByteValue*等于档案大小减去 1。对于清单检索任务或选择任务，此字段为 `null`。 *类型*：字符串 **SelectParameters** 一个对象，其中包含有关用于选择任务的参数的信息。 *类型*：[SelectParameters](api-SelectParameters.md) 对象 **SHA256TreeHash** 档案请求范围的 SHA256 树形哈希值。如果档案的[启动任务（POST jobs）](api-initiate-job-post.md)请求指定了以树形哈希对齐的范围，则此字段会返回值。有关档案范围检索的树形哈希对齐的更多信息，请参阅[下载数据时接收校验和](checksum-calculations-range.md)。 对于检索整个档案时的特定情况，此值与 `ArchiveSHA256TreeHash` 值相同。 在以下情况中，此字段为 `null`： + 指定未以树形哈希对齐的范围的档案检索任务。 + 指定等于整个档案的范围并且任务状态为 `InProgress` 的档案任务。 + 清单任务。 + 选择任务。 *类型*：字符串 **SNSTopic** 接收通知的 Amazon SNS 主题。 *类型*：字符串 **StatusCode** 指示任务状态的代码。 *有效值*：`InProgress` \$1 `Succeeded` \$1 `Failed` *类型*：字符串 **StatusMessage** 描述任务状态的友好消息。 *类型*：字符串 **Tier** 用于选择任务或档案检索任务的数据访问套餐。 *有效值*：`Bulk` \$1`Expedited` \$1`Standard` *类型*：字符串 **VaultARN** 任务为其子资源的文件库的 Amazon 资源名称（ARN）。 *类型*：字符串 ### 错误 有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。 ## 示例 以下示例显示了检索档案的任务的请求。 ### 请求示例：获取任务描述 ``` 1. GET /-/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID HTTP/1.1 2. Host: glacier.us-west-2.amazonaws.com 3. x-amz-Date: 20170210T120000Z 4. x-amz-glacier-version: 2012-06-01 5. Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20141123/us-west-2/glacier/aws4_request,SignedHeaders=host;x-amz-date;x-amz-glacier-version,Signature=9257c16da6b25a715ce900a5b45b03da0447acf430195dcb540091b12966f2a2 ``` ### 响应示例 响应正文包括描述指定任务的 JSON。请注意，对于清单检索和档案检索任务，JSON 字段相同。但是，当字段不适用于任务类型时，其值为 `null`。以下是档案检索任务的响应示例。注意以下几点： + `Action` 字段值为 `ArchiveRetrieval`。 + `ArchiveSizeInBytes` 字段显示了档案检索任务中请求的档案的大小。 + 该`ArchiveSHA256TreeHash`字段显示整个档案的 SHA256 树形哈希。 + `RetrievalByteRange` 字段显示了启动任务请求中请求的范围。在此示例中，请求了整个档案。 + 该`SHA256TreeHash`字段显示了 Initiate Job 请求中请求的范围的 SHA256 树形哈希。在此示例中，它与 `ArchiveSHA256TreeHash` 字段相同，这意味着请求了整个档案。 + `InventorySizeInBytes` 字段值为 `null`，因为它不适用于档案检索任务。 ``` 1. HTTP/1.1 200 OK 2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q 3. Date: Wed, 10 Feb 2017 12:00:00 GMT 4. Content-Type: application/json 5. Content-Length: 419 6. { 7. "Action": "ArchiveRetrieval", 8. "ArchiveId": "NkbByEejwEggmBz2fTHgJrg0XBoDfjP4q6iu87-TjhqG6eGoOY9Z8i1_AUyUsuhPAdTqLHy8pTl5nfCFJmDl2yEZONi5L26Omw12vcs01MNGntHEQL8MBfGlqrEXAMPLEArchiveId", 9. "ArchiveSizeInBytes": 16777216, 10. "ArchiveSHA256TreeHash": "beb0fe31a1c7ca8c6c04d574ea906e3f97b31fdca7571defb5b44dca89b5af60", 11. "Completed": false, 12. "CompletionDate": null, 13. "CreationDate": "2012-05-15T17:21:39.339Z", 14. "InventorySizeInBytes": null, 15. "JobDescription": "My ArchiveRetrieval Job", 16. "JobId": "HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID", 17. "RetrievalByteRange": "0-16777215", 18. "SHA256TreeHash": "beb0fe31a1c7ca8c6c04d574ea906e3f97b31fdca7571defb5b44dca89b5af60", 19. "SNSTopic": "arn:aws:sns:us-west-2:012345678901:mytopic", 20. "StatusCode": "InProgress", 21. "StatusMessage": "Operation in progress.", 22. "Tier": "Bulk", 23. "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault" 24. } ``` 以下是清单检索任务的响应示例。注意以下几点： + `Action` 字段值为 `InventoryRetrieval`。 + `ArchiveSizeInBytes`、`ArchiveSHA256TreeHash` 和 `RetrievalByteRange` 字段值为空，因为这些字段不适用于清单检索任务。 + `InventorySizeInBytes` 字段值为 `null`，因为任务仍在进行，尚未为下载完全准备好清单。如果任务在您的描述任务请求前已完成，则此字段将为您提供输出的大小。 ``` { "Action": "InventoryRetrieval", "ArchiveId": null, "ArchiveSizeInBytes": null, "ArchiveSHA256TreeHash": null, "Completed": false, "CompletionDate": null, "CreationDate": "2012-05-15T23:18:13.224Z", "InventorySizeInBytes": null, "JobDescription": "Inventory Description", "JobId": "HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID", "RetrievalByteRange": null, "SHA256TreeHash": null, "SNSTopic": "arn:aws:sns:us-west-2:012345678901:mytopic", "StatusCode": "InProgress", "StatusMessage": "Operation in progress.", "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault" } ``` 以下例举了一个针对已完成清单检索任务的响应，该任务包含用于继续文件库清单检索分页的标记。 ``` { "Action": "InventoryRetrieval", "ArchiveId": null, "ArchiveSHA256TreeHash": null, "ArchiveSizeInBytes": null, "Completed": true, "CompletionDate": "2013-12-05T21:51:13.591Z", "CreationDate": "2013-12-05T21:51:12.281Z", "InventorySizeInBytes": 777062, "JobDescription": null, "JobId": "sCC2RZNBF2nildYD_roe0J9bHRdPQUbDRkmTdg-mXi2u3lc49uW6TcEhDF2D9pB2phx-BN30JaBru7PMyOlfXHdStzu8", "NextInventoryRetrievalMarker": null, "RetrievalByteRange": null, "SHA256TreeHash": null, "SNSTopic": null, "StatusCode": "Succeeded", "StatusMessage": "Succeeded", "Tier": "Bulk", "VaultARN": "arn:aws:glacier-devo:us-west-2:836579025725:vaults/inventory-icecube-2", "InventoryRetrievalParameters": { "StartDate": "2013-11-12T13:43:12Z", "EndDate": "2013-11-20T08:12:45Z", "Limit": "120000", "Format": "JSON", "Marker": "vyS0t2jHQe5qbcDggIeD50chS1SXwYMrkVKo0KHiTUjEYxBGCqRLKaiySzdN7QXGVVV5XZpNVG67pCZ_uykQXFMLaxOSu2hO_-5C0AtWMDrfo7LgVOyfnveDRuOSecUo3Ueq7K0" }, } ``` ## 相关部分 + [获取任务输出（GET output）](api-job-output-get.md) + [适用于 Amazon Glacier 的 Identity and Access Management](security-iam.md) # 获取任务输出（GET output） ## 说明 此操作会下载您使用[启动任务（POST jobs）](api-initiate-job-post.md)启动的任务的输出。根据您在启动任务时指定的任务类型，输出将为档案的内容或文件库清单。 您可以下载所有任务输出，也可以通过指定字节范围下载输出的一部分。对于档案和清单检索任务，您应针对在 **Get Job Output** 响应的标头中返回的大小对下载大小进行验证。 对于档案检索任务，还应验证大小是否与预期相符。如果下载部分输出，则预期大小基于您指定的字节范围。例如，如果指定 `bytes=0-1048575` 范围，则需要验证下载大小为 1048576 字节。如果下载整个档案，则预期大小是您上传到 Amazon Glacier（Amazon Glacier）的档案的大小。**Get Job Output** 响应的标头中也会返回预期大小。 对于档案检索任务的情况，根据您指定的字节范围，Amazon Glacier 返回该部分数据的校验和。要确保您下载的部分是正确的数据，请在客户端计算校验和，验证值是否匹配，并且验证大小是否和预期一致。 Amazon Glacier 完成任务后，任务 ID 至少在 24 小时内都不会过期。也就是说，您可以在 Amazon Glacier 完成任务后的 24 小时期限内下载任务输出。 ## 请求 ### 语法 要检索任务输出，您可以向特定任务的 `GET` 的 URI 发送 HTTP `output` 请求。 ``` 1. GET /AccountId/vaults/VaultName/jobs/JobID/output HTTP/1.1 2. Host: glacier.Region.amazonaws.com 3. Date: Date 4. Authorization: SignatureValue 5. Range: ByteRangeToRetrieve 6. x-amz-glacier-version: 2012-06-01 ``` **注意** 该`AccountId`值是拥有文件库的账户的 AWS 账户 ID。您可以指定一个 AWS 账户 ID，也可以选择指定一个 '`-`'（连字符），在这种情况下，Amazon Glacier 使用与用于签署请求的凭证关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符（-）。 ### 请求参数 此操作不使用请求参数。 ### 请求标头 除了所有操作通用的请求标头外，此操作还使用以下请求标头。有关通用请求标头的更多信息，请参阅[通用请求标头](api-common-request-headers.md)。 | Name | 说明 | 必填 | | --- | --- | --- | | Range | 要从输出检索的字节范围。例如，如果您要下载前 1048576 字节，请指定范围 `bytes=0-1048575`。有关更多信息，请转到[范围标头字段定义](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35)。该范围与启动任务请求中指定的任何范围是相对而言的。默认情况下，此操作会下载整个输出。 如果任务输出很大，则您可以使用 `Range` 请求标头来检索输出的一部分。这样，您能够以较小的字节区块下载整个输出。例如，假设您有 1 GB 任务输出需要下载，您决定一次下载 128 MB 数据区块，则总共有八个获取任务输出请求。您将使用以下流程下载任务输出： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/amazonglacier/latest/dev/api-job-output-get.html) 类型：字符串 默认值：无 约束：无 | 否 | ### 请求正文 此操作没有请求正文。 ## 响应 ### 语法 对于返回所有任务数据的检索请求，任务输出响应会返回 `200 OK` 响应代码。当请求部分内容（例如，如果您在请求中指定了 `Range` 标头）时，则会返回响应代码 `206 Partial Content`。 ``` 1. HTTP/1.1 200 OK 2. x-amzn-RequestId: x-amzn-RequestId 3. Date: Date 4. Content-Type: ContentType 5. Content-Length: Length 6. x-amz-sha256-tree-hash: ChecksumComputedByAmazonGlacier 7. 8. [Body containing job output.] ``` ### 响应标头 | 标题 | 说明 | | --- | --- | | Content-Range | Amazon Glacier 返回的字节范围。如果只下载部分输出，则响应会提供 Amazon Glacier 返回的字节范围。 例如，`bytes 0-1048575/8388608` 会从 8 MB 返回前 1 MB。 有关 `Content-Range` 标头的更多信息，请转到[内容范围标头字段定义](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.16)。 类型：字符串 | | Content-Type | 内容类型取决于任务输出是档案还是文件库清单。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/amazonglacier/latest/dev/api-job-output-get.html) 类型：字符串 | | x-amz-sha256-tree-hash​ | 响应中的数据的校验和。只有在检索档案检索任务的输出时，才会返回此标头。此外，如果启动任务请求中请求的检索数据范围以树形哈希对齐，并且获取任务输出中要下载的范围也以树形哈希对齐，则此标头会显示。有关以树形哈希对齐的范围的更多信息，请参阅[下载数据时接收校验和](checksum-calculations-range.md)。 例如，如果您在您的启动任务请求中指定了要检索的以树形哈希对齐的范围（包括整个档案），则您将收到您在以下条件下下载的数据的校验和： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/amazonglacier/latest/dev/api-job-output-get.html) 类型：字符串 | ### 响应正文 Amazon Glacier 会在响应正文中返回任务输出。根据任务类型，输出可以为档案内容或文件库库存。如果为文件库清单，则默认情况下，清单列表会作为以下 JSON 正文返回。 ``` 1. { 2. "VaultARN": String, 3. "InventoryDate": String, 4. "ArchiveList": [ 5. {"ArchiveId": String, 6. "ArchiveDescription": String, 7. "CreationDate": String, 8. "Size": Number, 9. "SHA256TreeHash": String 10. }, 11. ... 12. ] 13. } ``` 如果您在启动文件库清单任务时请求了 CSV 格式，则文件库清单会以 CSV 格式返回在正文中。CSV 格式有五列 ArchiveId “”、“”、ArchiveDescription “”、CreationDate “大小” 和 “”，其定义与相应的 JSON 字段相同。SHA256 TreeHash **注意** 在返回的 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 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。 ## 示例 以下示例显示了检索档案的任务的请求。 ### 示例 1：下载输出 此示例会检索 Amazon Glacier 因响应您的启动档案检索任务请求而准备的数据。 #### 请求示例 ``` 1. GET /-/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID/output HTTP/1.1 2. Host: glacier.us-west-2.amazonaws.com 3. x-amz-Date: 20170210T120000Z 4. x-amz-glacier-version: 2012-06-01 5. 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` 标头包括在响应中，这意味着返回所有任务数据。 ``` 1. HTTP/1.1 200 OK 2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q 3. x-amz-sha256-tree-hash: beb0fe31a1c7ca8c6c04d574ea906e3f97b31fdca7571defb5b44dca89b5af60 4. Date: Wed, 10 Feb 2017 12:00:00 GMT 5. Content-Type: application/octet-stream 6. Content-Length: 1048576 7. 8. [Archive data.] ``` 以下是清单检索任务的响应示例。请注意，`Content-Type` 标头为 `application/json`。另请注意，响应不包括 `x-amz-sha256-tree-hash` 标头。 ``` 1. HTTP/1.1 200 OK 2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q 3. Date: Wed, 10 Feb 2017 12:00:00 GMT 4. Content-Type: application/json 5. Content-Length: 906 6. 7. { 8. "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault", 9. "InventoryDate": "2011-12-12T14:19:01Z", 10. "ArchiveList": [ 11. { 12. "ArchiveId": "DMTmICA2n5Tdqq5BV2z7og-A20xnpAPKt3UXwWxdWsn_D6auTUrW6kwy5Qyj9xd1MCE1mBYvMQ63LWaT8yTMzMaCxB_9VBWrW4Jw4zsvg5kehAPDVKcppUD1X7b24JukOr4mMAq-oA", 13. "ArchiveDescription": "my archive1", 14. "CreationDate": "2012-05-15T17:19:46.700Z", 15. "Size": 2140123, 16. "SHA256TreeHash": "6b9d4cf8697bd3af6aa1b590a0b27b337da5b18988dbcc619a3e608a554a1e62" 17. }, 18. { 19. "ArchiveId": "2lHzwhKhgF2JHyvCS-ZRuF08IQLuyB4265Hs3AXj9MoAIhz7tbXAvcFeHusgU_hViO1WeCBe0N5lsYYHRyZ7rrmRkNRuYrXUs_sjl2K8ume_7mKO_0i7C-uHE1oHqaW9d37pabXrSA", 20. "ArchiveDescription": "my archive2", 21. "CreationDate": "2012-05-15T17:21:39.339Z", 22. "Size": 2140123, 23. "SHA256TreeHash": "7f2fe580edb35154041fa3d4b41dd6d3adaef0c85d2ff6309f1d4b520eeecda3" 24. } 25. ] 26. } ``` ### 示例 2：只下载部分输出 此示例只检索 Amazon Glacier 因响应您的启动档案检索任务请求而准备的档案的一部分。该请求使用了可选的 `Range` 标头，以便只检索前 1024 字节。 #### 请求示例 ``` 1. GET /-/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID/output HTTP/1.1 2. Host: glacier.us-west-2.amazonaws.com 3. x-amz-Date: 20170210T120000Z 4. Range: bytes=0-1023 5. x-amz-glacier-version: 2012-06-01 6. 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 返回的字节范围。 ``` 1. HTTP/1.1 206 Partial Content 2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q 3. Date: Wed, 10 Feb 2017 12:00:00 GMT 4. Content-Range: bytes 0-1023/8388608 5. Content-Type: application/octet-stream 6. Content-Length: 1024 7. 8. [Archive data.] ``` ## 相关部分 + [描述任务（GET JobID）](api-describe-job-get.md) + [启动任务（POST jobs）](api-initiate-job-post.md) + [适用于 Amazon Glacier 的 Identity and Access Management](security-iam.md) # 启动任务（POST jobs） 此操作将启动以下类型的 Amazon Glacier（Amazon Glacier）任务： + `archive-retrieval` – 检索档案 + `inventory-retrieval` – 清点文件库 **Topics** + [启动档案或文件库清单检索任务](#api-initiate-job-post-description) + [请求](#api-initiate-job-post-requests) + [响应](#api-initiate-job-post-responses) + [示例](#api-initiate-job-post-examples) + [相关部分](#more-info-api-initiate-job-post) ## 启动档案或文件库清单检索任务 检索档案或文件库清单是异步操作，这些操作要求您启动任务。任务一旦启动，便无法取消。此检索包括两个步骤： 1. 使用[启动任务（POST jobs）](#api-initiate-job-post)操作启动检索任务。 **重要** 数据检索策略可能导致您启动检索任务的请求以发生 `PolicyEnforcedException` 而失败。有关数据检索策略的更多信息，请参阅 [Amazon Glacier 数据检索策略](data-retrieval-policy.md)。有关 `PolicyEnforcedException` 异常的更多信息，请参阅[错误响应](api-error-responses.md)。 1. 在任务完成后，使用[获取任务输出（GET output）](api-job-output-get.md)操作下载字节。 检索请求会异步运行。当您启动检索任务时，Amazon Glacier 会创建任务并在响应中返回任务 ID。Amazon Glacier 完成任务时，您可以获取任务输出（档案或清单数据）。有关获取任务输出的信息，请参阅[获取任务输出（GET output）](api-job-output-get.md)操作。 任务必须先完成，然后，您才能获取其输出。要确定任务何时完成，您有以下选择： + **使用 Amazon SNS 通知** – 您可以指定一个 Amazon SNS 主题，Amazon Glacier 会在任务完成后向该主题发布通知。您可以为每个任务请求指定 SNS 主题。只有在 Amazon Glacier 完成任务后，系统才会发送通知。除了为每个任务请求指定 SNS 主题以外，您还可以配置文件库的文件库通知，这样，系统就会为所有检索操作发送任务通知。有关更多信息，请参阅[设置文件库通知配置（PUT notification-configuration）](api-vault-notifications-put.md)。 + **获取任务详细信息** – 当任务正在进行时，您可以发送[描述任务（GET JobID）](api-describe-job-get.md)请求以获取任务状态信息。但是，更有效的方法是使用 Amazon SNS 通知来确定任务何时完成。 **注意** 您通过通知获取的信息与通过调用[描述任务（GET JobID）](api-describe-job-get.md)获取的信息相同。 对于特定事件，如果您在文件库中添加了两种通知配置，并且也在您的启动任务请求中指定了 SNS 主题，则 Amazon Glacier 会发送这两种通知。有关更多信息，请参阅[设置文件库通知配置（PUT notification-configuration）](api-vault-notifications-put.md)。 ### 文件库清单 从您第一次将档案上传到文件库的日期开始，Amazon Glacier 大约每天都会更新一次文件库清单。如果在上次清单盘点后没有对文件库执行过添加或删除档案的操作，则不会更新清单日期。当您启动文件库库存任务时，Amazon Glacier 会返回其生成的最后一个库存，即 point-in-time快照而不是实时数据。 Amazon Glacier 为文件库创建第一份清单后，通常需要经过半天（最多一天）时间，该清单才可用于检索操作。 您可能没有发现为每个档案上传操作检索文件库清单有什么好处。但是，假设您在客户端维护数据库，且该客户端关联了您上传到 Amazon Glacier 的档案的元数据。此时，您可能会发现，文件库清单对于根据需要将您数据库中的信息与实际文件库清单进行协调很有用。有关清单任务输出中返回的数据字段的更多信息，请参阅[响应正文](api-job-output-get.md#api-job-output-get-responses-elements)。 ### 确定清单检索范围 您可以通过筛选档案创建日期或设置限制，来限制检索的清单项目数。 **按档案创建日期筛选** 通过在**启动任务**请求中为这些参数指定值，您可以检索在 `StartDate` 和 `EndDate` 之间创建的档案的清单项目。将会返回在 `StartDate` 之后且 `EndDate` 之前创建的档案。如果您仅提供 `StartDate`，而不提供 `EndDate`，则会检索在 `StartDate` 或之后创建的所有的档案的清单。如果您仅提供 `EndDate`，而不提供 `StartDate`，则会检索在 `EndDate` 之前创建的所有档案的清单。 **限制每次检索的清单项目** 通过在**启动任务**请求中设置 `Limit` 参数，可以限制返回的清单项目数量。清单任务输出包含的清单项目数最多为指定的 `Limit`。如果有更多清单项目可用，则结果会分页。任务完成之后，您可以使用[描述任务（GET JobID）](api-describe-job-get.md)操作获取在后续**启动任务**请求中使用的标记。该标记将指示检索下一组清单项目的起点。通过使用之前的**描述任务**输出中的标记反复提出**启动任务**请求，可以浏览整个清单。如此操作，直至从**描述任务**获取一个返回 null 的标记（这指示无更多清单项目可用）。 您可以将 `Limit` 参数与日期范围参数一起使用。 ### 关于具有范围的档案检索 您可以为整个档案或某个范围的档案启动档案检索操作。对于具有范围的档案检索操作情况，您可以指定要返回的字节范围或整个档案。指定的范围必须以兆字节（MB）对齐。换言之，范围起始值必须可被 1 MB 整除，并且范围结束值加 1 必须可被 1 MB 整除或者等于档案的结束值。如果具有范围的档案检索操作没有以兆字节对齐，则此操作会返回 `400` 响应。此外，为了确保您获取您使用**获取任务输出**（[获取任务输出（GET output）](api-job-output-get.md)）下载的数据的校验和值，范围必须以树形哈希对齐。有关以树形哈希对齐的范围的更多信息，请参阅[下载数据时接收校验和](checksum-calculations-range.md)。 ### 加速、标准和批量套餐 在启动档案检索任务时，您可以在请求正文的 `Tier` 字段中指定以下选项之一： + **`Expedited`** – 加速套餐允许您在偶尔需要紧急请求还原档案时快速访问数据。对于除了最大型档案（250 MB\$1）之外的所有其他档案，使用加速套餐访问的数据通常在 1 到 5 分钟内可用。 + **`Standard`** – 标准套餐允许您在数小时内访问您的任意档案。使用标准套餐访问的数据通常在 3–5 小时内可用。此选项是未指定套餐选项的任务请求的默认选项。 + **`Bulk`** – 批量套餐是 Amazon Glacier 的最低成本套餐，使您可以在一天内以较低的成本检索大量（甚至是 PB 级）的数据。使用批量套餐访问的数据通常在 5-12 小时内可用。 有关加速和批量检索的更多信息，请参阅[检索 Amazon Glacier 档案](downloading-an-archive-two-steps.md)。 ## 请求 要启动任务，您可以使用 HTTP `POST` 方法，并将请求纳入到文件库的 `jobs` 子资源中。您可以在您请求的 JSON 文档中指定任务请求的详细信息。任务类型是通过 `Type` 字段指定的。（可选）您可以指定 `SNSTopic` 字段来表示 Amazon Glacier 在完成任务后可以向其发布通知的 Amazon SNS 主题。 **注意** 要向 Amazon SNS 发布通知，您必须自己创建主题（如果主题不存在）。Amazon Glacier 不会为您创建主题。该主题必须具有从 Amazon Glacier 文件库接收出版物的权限。Amazon Glacier 不会验证文件库是否有权向该主题发布内容。如果没有适当配置权限，则即使任务完成后，您可能也不会收到通知。 ### 语法 以下是用于启动任务的请求语法。 ``` 1. POST /AccountId/vaults/VaultName/jobs HTTP/1.1 2. Host: glacier.Region.amazonaws.com 3. Date: Date 4. Authorization: SignatureValue 5. x-amz-glacier-version: 2012-06-01 6. 7. { 8. "jobParameters": { 9. "ArchiveId": "string", 10. "Description": "string", 11. "Format": "string", 12. "InventoryRetrievalParameters": { 13. "EndDate": "string", 14. "Limit": "string", 15. "Marker": "string", 16. "StartDate": "string" 17. }, 18. "OutputLocation": { 19. "S3": { 20. "AccessControlList": [ 21. { 22. "Grantee": { 23. "DisplayName": "string", 24. "EmailAddress": "string", 25. "ID": "string", 26. "Type": "string", 27. "URI": "string" 28. }, 29. "Permission": "string" 30. } 31. ], 32. "BucketName": "string", 33. "CannedACL": "string", 34. "Encryption": { 35. "EncryptionType": "string", 36. "KMSContext": "string", 37. "KMSKeyId": "string" 38. }, 39. "Prefix": "string", 40. "StorageClass": "string", 41. "Tagging": { 42. "string" : "string" 43. }, 44. "UserMetadata": { 45. "string" : "string" 46. } 47. } 48. }, 49. "RetrievalByteRange": "string", 50. "SelectParameters": { 51. "Expression": "string", 52. "ExpressionType": "string", 53. "InputSerialization": { 54. "csv": { 55. "Comments": "string", 56. "FieldDelimiter": "string", 57. "FileHeaderInfo": "string", 58. "QuoteCharacter": "string", 59. "QuoteEscapeCharacter": "string", 60. "RecordDelimiter": "string" 61. } 62. }, 63. "OutputSerialization": { 64. "csv": { 65. "FieldDelimiter": "string", 66. "QuoteCharacter": "string", 67. "QuoteEscapeCharacter": "string", 68. "QuoteFields": "string", 69. "RecordDelimiter": "string" 70. } 71. } 72. }, 73. "SNSTopic": "string", 74. "Tier": "string", 75. "Type": "string" 76. } 77. } ``` **注意** 该`AccountId`值是拥有文件库的账户的 AWS 账户 ID。您可以指定一个 AWS 账户 ID，也可以选择指定一个 '`-`'（连字符），在这种情况下，Amazon Glacier 使用与用于签署请求的凭证关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符（-）。 ### 请求正文 请求接受请求正文中采用 JSON 格式的以下数据。 jobParameters 提供用于指定任务信息的选项。 *类型*：[jobParameters](api-jobParameters.md) 对象 *是否必需*：是 ## 响应 Amazon Glacier 创建了任务。在响应中，它会返回任务的 URI。 ### 语法 ``` 1. HTTP/1.1 202 Accepted 2. x-amzn-RequestId: x-amzn-RequestId 3. Date: Date 4. Location: location 5. x-amz-job-id: jobId 6. x-amz-job-output-path: jobOutputPath ``` ### 响应标头 | 标题 | 说明 | | --- | --- | | Location | 任务的相对 URI 路径。您可以使用此 URI 路径来查找任务状态。有关更多信息，请参阅[描述任务（GET JobID）](api-describe-job-get.md)。 类型：字符串 默认值：无 | | x-amz-job-id | 任务的 ID。此值也包括在 `Location` 标头中，作为该标头的一部分。 类型：字符串 默认值：无 | | x-amz-job-output-path | 存储选择任务结果的位置的路径。 类型：字符串 默认值：无 | ### 响应正文 此操作不返回响应正文。 ### 错误 除了所有 Amazon Glacier 操作中常见的可能错误外，此操作还包括以下一个或多个错误。有关 Amazon Glacier 错误的信息以及错误代码列表，请参阅[错误响应](api-error-responses.md)。 | 代码 | 说明 | HTTP 状态代码 | 类型 | | --- | --- | --- | --- | | InsufficientCapacityException | 如果没有足够的容量处理此加速请求，则返回此代码。此错误仅适用于加速检索，不适用于标准或批量检索。 | 503 Service Unavailable | 服务器 | ## 示例 ### 请求示例：启动档案检索任务 ``` 1. POST /-/vaults/examplevault/jobs HTTP/1.1 2. Host: glacier.us-west-2.amazonaws.com 3. x-amz-Date: 20170210T120000Z 4. x-amz-glacier-version: 2012-06-01 5. Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20141123/us-west-2/glacier/aws4_request,SignedHeaders=host;x-amz-date;x-amz-glacier-version,Signature=9257c16da6b25a715ce900a5b45b03da0447acf430195dcb540091b12966f2a2 6. 7. { 8. "Type": "archive-retrieval", 9. "ArchiveId": "NkbByEejwEggmBz2fTHgJrg0XBoDfjP4q6iu87-TjhqG6eGoOY9Z8i1_AUyUsuhPAdTqLHy8pTl5nfCFJmDl2yEZONi5L26Omw12vcs01MNGntHEQL8MBfGlqrEXAMPLEArchiveId", 10. "Description": "My archive description", 11. "SNSTopic": "arn:aws:sns:us-west-2:111111111111:Glacier-ArchiveRetrieval-topic-Example", 12. "Tier" : "Bulk" 13. } ``` 以下是请求正文的示例，它使用 `RetrievalByteRange` 字段指定了要检索的档案范围。 ``` { "Type": "archive-retrieval", "ArchiveId": "NkbByEejwEggmBz2fTHgJrg0XBoDfjP4q6iu87-TjhqG6eGoOY9Z8i1_AUyUsuhPAdTqLHy8pTl5nfCFJmDl2yEZONi5L26Omw12vcs01MNGntHEQL8MBfGlqrEXAMPLEArchiveId", "Description": "My archive description", "RetrievalByteRange": "2097152-4194303", "SNSTopic": "arn:aws:sns:us-west-2:111111111111:Glacier-ArchiveRetrieval-topic-Example", "Tier" : "Bulk" } ``` ### 响应示例 ``` 1. HTTP/1.1 202 Accepted 2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q 3. Date: Wed, 10 Feb 2017 12:00:00 GMT 4. Location: /111122223333/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID 5. x-amz-job-id: HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID ``` ### 请求示例：启动清单检索任务 以下请求会启动清单检索任务，以从 `examplevault` 文件库获取档案列表。在请求正文中，设置为 `Format` 的 `CSV` 表示清单会以 CSV 格式返回。 ``` 1. POST /-/vaults/examplevault/jobs HTTP/1.1 2. Host: glacier.us-west-2.amazonaws.com 3. x-amz-Date: 20170210T120000Z 4. Content-Type: application/x-www-form-urlencoded 5. x-amz-glacier-version: 2012-06-01 6. Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20141123/us-west-2/glacier/aws4_request,SignedHeaders=host;x-amz-date;x-amz-glacier-version,Signature=9257c16da6b25a715ce900a5b45b03da0447acf430195dcb540091b12966f2a2 7. 8. { 9. "Type": "inventory-retrieval", 10. "Description": "My inventory job", 11. "Format": "CSV", 12. "SNSTopic": "arn:aws:sns:us-west-2:111111111111:Glacier-InventoryRetrieval-topic-Example" 13. } ``` ### 响应示例 ``` 1. HTTP/1.1 202 Accepted 2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q 3. Date: Wed, 10 Feb 2017 12:00:00 GMT 4. Location: /111122223333/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID 5. x-amz-job-id: HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID ``` ### 请求示例：使用日期筛选及设置限制来启动清单检索任务，以及检索下一页清单项目的后续请求。 以下请求通过使用日期筛选及设置限制来启动文件库清单检索任务。 ``` 1. { 2. "ArchiveId": null, 3. "Description": null, 4. "Format": "CSV", 5. "RetrievalByteRange": null, 6. "SNSTopic": null, 7. "Type": "inventory-retrieval", 8. "InventoryRetrievalParameters": { 9. "StartDate": "2013-12-04T21:25:42Z", 10. "EndDate": "2013-12-05T21:25:42Z", 11. "Limit" : "10000" 12. }, 13. } ``` 以下例举了使用从[描述任务（GET JobID）](api-describe-job-get.md)获取的标记检索下一页清单项目的后续请求。 ``` 1. { 2. "ArchiveId": null, 3. "Description": null, 4. "Format": "CSV", 5. "RetrievalByteRange": null, 6. "SNSTopic": null, 7. "Type": "inventory-retrieval", 8. "InventoryRetrievalParameters": { 9. "StartDate": "2013-12-04T21:25:42Z", 10. "EndDate": "2013-12-05T21:25:42Z", 11. "Limit": "10000", 12. "Marker": "vyS0t2jHQe5qbcDggIeD50chS1SXwYMrkVKo0KHiTUjEYxBGCqRLKaiySzdN7QXGVVV5XZpNVG67pCZ_uykQXFMLaxOSu2hO_-5C0AtWMDrfo7LgVOyfnveDRuOSecUo3Ueq7K0" 13. }, 14. } ``` ### 响应示例 ``` 1. HTTP/1.1 202 Accepted 2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q 3. Date: Wed, 10 Feb 2017 12:00:00 GMT 4. Location: /111122223333/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID 5. x-amz-job-id: HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID 6. x-amz-job-output-path: test/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID/ ``` ## 相关部分 + [描述任务（GET JobID）](api-describe-job-get.md) + [获取任务输出（GET output）](api-job-output-get.md) + [适用于 Amazon Glacier 的 Identity and Access Management](security-iam.md) # 列出任务（GET jobs） ## 说明 此操作会列出文件库的任务，包括正在进行的任务以及最近完成的任务。 **注意** Amazon Glacier（Amazon Glacier）在删除最近完成的任务前会将这些任务保留一段时间；但是，它最终会删除已完成的任务。您可以检索已完成任务的输出。在任务完成后，通过将完成的任务保留一段时间，您可以在错过任务完成通知或者首次尝试下载失败的情况下获取任务输出。例如，假设您启动档案检索任务以下载档案。任务完成后，您开始下载档案，但是遇到了网络错误。在这种情况下，您可以在任务存在时重试并下载档案。 `List Jobs` 操作支持分页。您应该始终查看响应 `Marker` 字段。如果没有更多列出的任务，则 `Marker` 字段将设置为 `null`。如果还有更多列出的任务，则 `Marker` 字段将设置为非 null 值，您可使用该值继续对列表分页。要返回从特定任务开始的任务列表，请将 `marker` 请求参数设置为您从之前的 `Marker` 请求获取的该任务的 `List Jobs` 值。 您也可以通过在请求中指定 `limit` 参数来设置响应中返回的最大任务数限制值。默认限制为 50。返回的任务数可能少于限制值，但永远不会超过限制值。 此外，您还可以通过指定可选的 `statuscode` 参数和/或 `completed` 参数来筛选返回的任务列表。使用 `statuscode` 参数，您可以指定只返回与 `InProgress`、`Succeeded` 或 `Failed` 状态匹配的任务。使用 `completed` 参数，您可以指定只返回已完成（`true`）的任务或未完成（`false`）的任务。 ## 请求 ### 语法 要返回所有类型的任务列表，请向文件库的 `GET` 子资源的 URI 发送 `jobs` 请求。 ``` 1. GET /AccountId/vaults/VaultName/jobs HTTP/1.1 2. Host: glacier.Region.amazonaws.com 3. Date: Date 4. Authorization: SignatureValue 5. x-amz-glacier-version: 2012-06-01 ``` **注意** 该`AccountId`值是拥有文件库的账户的 AWS 账户 ID。您可以指定一个 AWS 账户 ID，也可以选择指定一个 '`-`'（连字符），在这种情况下，Amazon Glacier 使用与用于签署请求的凭证关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符（-）。 ### 请求参数 | Name | 说明 | 必填 | | --- | --- | --- | | completed | 要返回的任务的状态。您可以指定 `true` 或 `false`。 类型：布尔值 约束：无 | 否 | | limit | 要返回的任务最大数目。默认限制为 50。返回的任务数可能少于指定的限制值，但永远不会超过限制值。 类型：字符串 约束：最小整数值为 1。最大整数值为 50。 | 否 | | marker | 用于分页的不透明字符串可指定应从其开始列出任务的任务。您可从之前的 `marker` 响应获取 `List Jobs` 值。只有在您要继续对之前的 `List Jobs` 请求中开始的结果进行分页时，才需要包括 `marker`。 类型：字符串 约束：无 | 否 | | statuscode | 要返回的任务状态的类型。 类型：字符串 约束：`InProgress`、`Succeeded` 或 `Failed` 这三个值之一。 | 否 | ### 请求标头 此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。 ### 请求正文 此操作没有请求正文。 ## 响应 ### 语法 ``` HTTP/1.1 200 OK x-amzn-RequestId: x-amzn-RequestId Date: Date Location: Location Content-Type: application/json Content-Length: Length { "JobList": [ { "Action": "string", "ArchiveId": "string", "ArchiveSHA256TreeHash": "string", "ArchiveSizeInBytes": number, "Completed": boolean, "CompletionDate": "string", "CreationDate": "string", "InventoryRetrievalParameters": { "EndDate": "string", "Format": "string", "Limit": "string", "Marker": "string", "StartDate": "string" }, "InventorySizeInBytes": number, "JobDescription": "string", "JobId": "string", "JobOutputPath": "string", "OutputLocation": { "S3": { "AccessControlList": [ { "Grantee": { "DisplayName": "string", "EmailAddress": "string", "ID": "string", "Type": "string", "URI": "string" }, "Permission": "string" } ], "BucketName": "string", "CannedACL": "string", "Encryption": { "EncryptionType": "string", "KMSContext": "string", "KMSKeyId": "string" }, "Prefix": "string", "StorageClass": "string", "Tagging": { "string": "string" }, "UserMetadata": { "string": "string" } } }, "RetrievalByteRange": "string", "SelectParameters": { "Expression": "string", "ExpressionType": "string", "InputSerialization": { "csv": { "Comments": "string", "FieldDelimiter": "string", "FileHeaderInfo": "string", "QuoteCharacter": "string", "QuoteEscapeCharacter": "string", "RecordDelimiter": "string" } }, "OutputSerialization": { "csv": { "FieldDelimiter": "string", "QuoteCharacter": "string", "QuoteEscapeCharacter": "string", "QuoteFields": "string", "RecordDelimiter": "string" } } }, "SHA256TreeHash": "string", "SNSTopic": "string", "StatusCode": "string", "StatusMessage": "string", "Tier": "string", "VaultARN": "string" } ], "Marker": "string" } ``` ### 响应标头 此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。 ### 响应正文 响应正文包含以下 JSON 字段。 **JobList** 任务对象的列表。每个任务对象包含描述任务的元数据。 *类型*：[GlacierJobDescription](api-GlacierJobDescription.md) 对象数组 **Marker** 表示从何处继续对结果进行分页的不透明字符串。您可以在新的 `marker` 请求中使用 ` List Jobs` 值来获取列表中的更多任务。如果没有列出更多任务，则此值为 `null`。 *类型*：字符串 ### 错误 有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。 ## 示例 以下示例展示了如何返回有关文件库任务的信息。第一个示例返回两个任务的列表，第二个示例返回各项任务的子集。 ### 示例：返回所有任务 #### 请求示例 以下 `GET` 请求可为文件库返回任务。 ``` 1. GET /-/vaults/examplevault/jobs HTTP/1.1 2. Host: glacier.us-west-2.amazonaws.com 3. x-amz-Date: 20170210T120000Z 4. x-amz-glacier-version: 2012-06-01 5. Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20141123/us-west-2/glacier/aws4_request,SignedHeaders=host;x-amz-date;x-amz-glacier-version,Signature=9257c16da6b25a715ce900a5b45b03da0447acf430195dcb540091b12966f2a2 ``` #### 响应示例 以下响应包括一个档案检索任务和一个清单检索任务，后者包含用于继续对文件库清单检索分页的标记。响应同时还可显示 `Marker` 字段已设定为 `null`，即表示没有更多列出任务。 ``` 1. HTTP/1.1 200 OK 2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q 3. Date: Wed, 10 Feb 2017 12:00:00 GMT 4. Content-Type: application/json 5. Content-Length: 1444 6. 7. { 8. "JobList": [ 9. { 10. "Action": "ArchiveRetrieval", 11. "ArchiveId": "BDfaUQul0dVzYwAMr8YSa_6_8abbhZq-i1oT69g8ByClfJyBgAGBkWl2QbF5os851P7Y7KdZDOHWJIn4rh1ZHaOYD3MgFhK_g0oDPesW34uHQoVGwoIqubf6BgUEfQm_wrU4Jlm3cA", 12. "ArchiveSizeInBytes": 1048576, 13. "ArchiveSHA256TreeHash": "25499381569ab2f85e1fd0eb93c5406a178ab77c5933056eb5d6e7d4adda609b", 14. "Completed": true, 15. "CompletionDate": "2012-05-01T00:00:09.304Z", 16. "CreationDate": "2012-05-01T00:00:06.663Z", 17. "InventorySizeInBytes": null, 18. "JobDescription": null, 19. "JobId": "hDe9t9DTHXqFw8sBGpLQQOmIM0-JrGtu1O_YFKLnzQ64548qJc667BRWTwBLZC76Ygy1jHYruqXkdcAhRsh0hYv4eVRU", 20. "RetrievalByteRange": "0-1048575", 21. "SHA256TreeHash": "25499381569ab2f85e1fd0eb93c5406a178ab77c5933056eb5d6e7d4adda609b", 22. "SNSTopic": null, 23. "StatusCode": "Succeeded", 24. "StatusMessage": "Succeeded", 25. "Tier": "Bulk", 26. "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault" 27. }, 28. { 29. "Action": "InventoryRetrieval", 30. "ArchiveId": null, 31. "ArchiveSizeInBytes": null, 32. "ArchiveSHA256TreeHash": null, 33. "Completed": true, 34. "CompletionDate": "2013-05-11T00:25:18.831Z", 35. "CreationDate": "2013-05-11T00:25:14.981Z", 36. "InventorySizeInBytes": 1988, 37. "JobDescription": null, 38. "JobId": "2cvVOnBL36btzyP3pobwIceiaJebM1bx9vZOOUtmNAr0KaVZ4WkWgVjiPldJ73VU7imlm0pnZriBVBebnqaAcirZq_C5", 39. "RetrievalByteRange": null, 40. "SHA256TreeHash": null, 41. "SNSTopic": null, 42. "StatusCode": "Succeeded", 43. "StatusMessage": "Succeeded", 44. "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault" 45. "InventoryRetrievalParameters": { 46. "StartDate": "2013-11-12T13:43:12Z", 47. "EndDate": "2013-11-20T08:12:45Z", 48. "Limit": "120000", 49. "Format": "JSON", 50. "Marker": "vyS0t2jHQe5qbcDggIeD50chS1SXwYMrkVKo0KHiTUjEYxBGCqRLKaiySzdN7QXGVVV5XZpNVG67pCZ_uykQXFMLaxOSu2hO_-5C0AtWMDrfo7LgVOyfnveDRuOSecUo3Ueq7K0" 51. } 52. ], 53. "Marker": null 54. } ``` ### 示例：返回任务的部分列表 #### 请求示例 以下 `GET` 请求返回 `marker` 参数指定的任务。如果将 `limit` 参数设置为 ，则指定最多返回两个任务。`2` ``` 1. GET /-/vaults/examplevault/jobs?marker=HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID&limit=2 HTTP/1.1 2. Host: glacier.us-west-2.amazonaws.com 3. x-amz-Date: 20170210T120000Z 4. x-amz-glacier-version: 2012-06-01 5. Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20141123/us-west-2/glacier/aws4_request,SignedHeaders=host;x-amz-date;x-amz-glacier-version,Signature=9257c16da6b25a715ce900a5b45b03da0447acf430195dcb540091b12966f2a2 ``` #### 响应示例 以下响应显示了两项返回任务，`Marker` 字段已设置为非 null 值，可用于对任务列表继续分页。 ``` 1. HTTP/1.1 200 OK 2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q 3. Date: Wed, 10 Feb 2017 12:00:00 GMT 4. Content-Type: application/json 5. Content-Length: 1744 6. 7. { 8. "JobList": [ 9. { 10. "Action": "ArchiveRetrieval", 11. "ArchiveId": "58-3KpZfcMPUznvMZNPaKyJx9wODCsWTnqcjtx2CjKZ6b-XgxEuA8yvZOYTPQfd7gWR4GRm2XR08gcnWbLV4VPV_kDWtZJKi0TFhKKVPzwrZnA4-FXuIBfViYUIVveeiBE51FO4bvg", 12. "ArchiveSizeInBytes": 8388608, 13. "ArchiveSHA256TreeHash": "106086b256ddf0fedf3d9e72f461d5983a2566247ebe7e1949246bc61359b4f4", 14. "Completed": true, 15. "CompletionDate": "2012-05-01T00:25:20.043Z", 16. "CreationDate": "2012-05-01T00:25:16.344Z", 17. "InventorySizeInBytes": null, 18. "JobDescription": "aaabbbccc", 19. "JobId": "s4MvaNHIh6mOa1f8iY4ioG2921SDPihXxh3Kv0FBX-JbNPctpRvE4c2_BifuhdGLqEhGBNGeB6Ub-JMunR9JoVa8y1hQ", 20. "RetrievalByteRange": "0-8388607", 21. "SHA256TreeHash": "106086b256ddf0fedf3d9e72f461d5983a2566247ebe7e1949246bc61359b4f4", 22. "SNSTopic": null, 23. "StatusCode": "Succeeded", 24. "StatusMessage": "Succeeded", 25. "Tier": "Bulk", 26. "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault" 27. }, 28. { 29. "Action": "ArchiveRetrieval", 30. "ArchiveId": "2NVGpf83U6qB9M2u-Ihh61yoFLRDEoh7YLZWKBn80A2i1xG8uieBwGjAr4RkzOHA0E07ZjtI267R03Z-6Hxd8pyGQkBdciCSH1-Lw63Kx9qKpZbPCdU0uTW_WAdwF6lR6w8iSyKdvw", 31. "ArchiveSizeInBytes": 1048576, 32. "ArchiveSHA256TreeHash": "3d2ae052b2978727e0c51c0a5e32961c6a56650d1f2e4ceccab6472a5ed4a0", 33. "Completed": true, 34. "CompletionDate": "2012-05-01T16:59:48.444Z", 35. "CreationDate": "2012-05-01T16:59:42.977Z", 36. "InventorySizeInBytes": null, 37. "JobDescription": "aaabbbccc", 38. "JobId": "CQ_tf6fOR4jrJCL61Mfk6VM03oY8lmnWK93KK4gLig1UPAbZiN3UV4G_5nq4AfmJHQ_dOMLOX5k8ItFv0wCPN0oaz5dG", 39. "RetrievalByteRange": "0-1048575", 40. "SHA256TreeHash": "3d2ae052b2978727e0c51c0a5e32961c6a56650d1f2e4ceccab6472a5ed4a0", 41. "SNSTopic": null, 42. "StatusCode": "Succeeded", 43. "StatusMessage": "Succeeded", 44. "Tier": "Standard", 45. "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault" 46. } 47. ], 48. "Marker": "CQ_tf6fOR4jrJCL61Mfk6VM03oY8lmnWK93KK4gLig1UPAbZiN3UV4G_5nq4AfmJHQ_dOMLOX5k8ItFv0wCPN0oaz5dG" 49. } ``` ## 相关部分 + [描述任务（GET JobID）](api-describe-job-get.md) + [适用于 Amazon Glacier 的 Identity and Access Management](security-iam.md)