**此页面仅适用于使用文件库和 2012 年原始 REST API 的 Amazon Glacier 服务的现有客户。**
如果您正在寻找归档存储解决方案，建议使用 Amazon S3 中的 Amazon Glacier 存储类别 S3 Glacier Instant Retrieval、S3 Glacier Flexible Retrieval 和 S3 Glacier Deep Archive。要了解有关这些存储选项的更多信息，请参阅 [Amazon Glacier 存储类别](https://www.amazonaws.cn/s3/storage-classes/glacier/)。
Amazon Glacier（最初基于保管库的独立服务）不再接受新客户。Amazon Glacier 是一项独立的服务 APIs ，拥有自己的服务，可将数据存储在文件库中，不同于亚马逊 S3 和 Amazon S3 Glacier 存储类别。在 Amazon Glacier 中，您现有的数据将确保安全，并且可以无限期地访问。无需进行迁移。对于低成本、长期的存档存储， Amazon 建议[使用 Amazon S3 Glacier 存储类别，这些存储类别](https://www.amazonaws.cn/s3/storage-classes/glacier/)基于S3存储桶 APIs、完全 Amazon Web Services 区域 可用性、更低的成本和 Amazon 服务集成，可提供卓越的客户体验。如果您希望加强功能，可以考虑使用我们的 [Amazon 将数据从 Amazon Glacier 文件库传输到 Amazon S3 Glacier 存储类别的解决方案指南](https://www.amazonaws.cn/solutions/guidance/data-transfer-from-amazon-s3-glacier-vaults-to-amazon-s3/)，迁移到 Amazon S3 Glacier 存储类别。
本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 启动任务（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 到 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`值是拥有文件库的账户的 Amazon Web Services 账户 ID。您可以指定一个 Amazon Web Services 账户 ID，也可以选择指定一个 '`-`'（连字符），在这种情况下，Amazon Glacier 使用与用于签署请求的凭证关联的 Amazon Web Services 账户 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)