启动作业（POST 作业） - Amazon S3 Glacier
初始化档案或文件库清单检索任务 请求响应示例相关部分
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

此页面仅适用于使用文件库和 2012 年原始 REST API 的 S3 Glacier 服务的现有客户。

如果您正在寻找归档存储解决方案，建议使用 Amazon S3 中的 S3 Glacier 存储类 S3 Glacier Instant Retrieval、S3 Glacier Flexible Retrieval 和 S3 Glacier Deep Archive。要了解有关这些存储选项的更多信息，请参阅《Amazon S3 用户指南》中的 S3 Glacier 存储类和使用 S3 Glacier 存储类的长期数据存储。这些存储类使用 Amazon S3 API，适用于所有区域，并且可以在 Amazon S3 控制台中管理。它们提供存储成本分析、Storage Lens 存储分析功能、高级可选加密功能等功能。

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

启动作业（POST 作业）

此操作将启动以下类型的 Amazon S3 Glacier（S3 Glacier）任务：

  • archive-retrieval — 检索档案

  • inventory-retrieval — 清点文件库

初始化档案或文件库清单检索任务

检索档案或文件库清单是异步操作，这些操作要求您启动任务。一旦启动，就无法取消作业。此检索包括两个步骤：

  1. 使用 启动作业（POST 作业） 操作启动检索任务。

    重要

    数据检索策略可能导致您启动检索任务的请求以发生 PolicyEnforcedException 而失败。有关数据检索策略的更多信息，请参阅S3 Glacier 数据检索策略。有关 PolicyEnforcedException 异常的更多信息，请参阅错误响应。

  2. 在任务完成后，使用 获取任务输出（获取输出） 操作下载字节。

检索请求会异步运行。当您启动检索任务时，S3 Glacier 会创建任务并在响应中返回任务 ID。S3 Glacier 完成任务时，您可以获取任务输出（档案或清单数据）。有关获取任务输出的信息，请参阅“获取任务输出（获取输出）”操作。

任务必须先完成，然后，您才能获取其输出。要确定任务何时完成，您有以下选择：

  • 使用 Amazon SNS 通知 — 您可以指定一个 Amazon SNS 主题，S3 Glacier 会在任务完成后向该主题发布通知。您可以为每个任务请求指定 SNS 主题。只有在 S3 Glacier 完成任务后，系统才会发送通知。除了为每个任务请求指定 SNS 主题以外，您还可以配置文件库的文件库通知，这样，系统就会为所有检索操作发送任务通知。有关更多信息，请参阅 设置文件库通知配置（设置通知配置）。

  • 获取任务详细信息 — 当任务正在进行时，您可以发送 描述任务（获取任务 ID） 请求以获取任务状态信息。但是，更有效的方法是使用 Amazon SNS 通知来确定任务何时完成。

注意

您通过通知获取的信息与通过调用 描述任务（获取任务 ID） 获取的信息相同。

对于特定事件，如果您在文件库中添加了两种通知配置，并且也在您的启动任务请求中指定了 SNS 主题，则 S3 Glacier 会发送这两种通知。有关更多信息，请参阅 设置文件库通知配置（设置通知配置）。

文件库清单

从您第一次将档案上传到文件库的日期开始，S3 Glacier 大约每天都会更新一次文件库清单。如果在上次清单盘点后没有对文件库执行过添加或删除档案的操作，则不会更新库存日期。当您启动文件库清单任务时，S3 Glacier 会返回其生成的最后一个清单，即 point-in-time快照而不是实时数据。

S3 Glacier 为文件库创建第一份清单后，通常需要经过半天（最多一天）时间，该清单才可用于检索操作。

您可能没有发现为每个档案上传操作检索文件库清单有什么好处。但是，假设您在客户端维护数据库，且该客户端关联了您上传到 S3 Glacier 的档案的元数据。此时，您可能会发现，文件库库存对于根据需要将您数据库中的信息与实际文件库库存进行协调很有用。有关清单任务输出中返回的数据字段的更多信息，请参阅响应正文。

确定清单检索范围

您可以通过筛选档案创建日期或设置限制，来限制检索的清单项目数。

按档案创建日期筛选

通过在启动任务请求中为这些参数指定值，您可以检索在 StartDate 和 EndDate 之间创建的档案的清单项目。将会返回在 StartDate 之后且 EndDate 之前创建的档案。如果您仅提供 StartDate，而不提供 EndDate，则会检索在 StartDate 或之后创建的所有的档案的清单。如果您仅提供 EndDate，而不提供 StartDate，则会检索在 EndDate 之前创建的所有档案的清单。

限制每次检索的清单项目

通过在启动任务请求中设置 Limit 参数，可以限制返回的清单项目数量。清单任务输出包含的清单项目数最多为指定的 Limit。如果有更多清单项目可用，则结果会分页。任务完成之后，您可以使用 描述任务（获取任务 ID） 操作获取在后续启动任务请求中使用的标记。该标记将指示检索下一组清单项目的起点。通过使用之前的描述任务输出中的标记反复提出启动任务请求，可以浏览整个清单。如此操作，直至从描述任务获取一个返回 null 的标记 (这指示无更多清单项目可用)。

您可以将 Limit 参数与日期范围参数一起使用。

关于具有范围的档案检索

您可以为整个档案或某个范围的档案启动档案检索操作。对于具有范围的档案检索操作情况，您可以指定要返回的字节范围或整个档案。指定的范围必须以兆字节 (MB) 对齐。换言之，范围起始值必须可被 1MB 整除，并且范围结束值加 1 必须可被 1MB 整除或者等于档案的结束值。如果具有范围的档案检索操作没有以兆字节对齐，则此操作会返回 400 响应。此外，为了确保您获取您使用获取任务输出 (获取任务输出（获取输出）) 下载的数据的校验和值，范围必须以树形哈希对齐。有关以树形哈希对齐的范围的更多信息，请参阅“下载数据时接收校验和”。

加速、标准和批量层

在启动档案检索任务时，您可以在请求正文的 Tier 字段中指定以下选项之一：

  • Expedited – 加速层允许您在偶尔需要紧急请求还原档案时快速访问数据。对于除了最大型档案 (250 MB+) 之外的所有其他档案，使用加速层访问的数据通常在 1 到 5 分钟内可用。

  • Standard – 标准层允许您在数小时内访问您的任意档案。使用标准层访问的数据通常在 3–5 小时内可用。此选项是未指定层选项的任务请求的默认选项。

  • Bulk – 批量层是 S3 Glacier 的最低成本层，使您可以在一天内以较低的成本检索大量（甚至是 PB 级）的数据。使用批量层访问的数据通常在 5–12 小时内可用。

有关加速和批量检索的更多信息，请参阅检索 S3 冰川档案。

请求

要启动任务，您可以使用 HTTP POST 方法，并将请求纳入到文件库的 jobs 子资源中。您可以在您请求的 JSON 文档中指定任务请求的详细信息。任务类型是通过 Type 字段指定的。（可选）您可以指定 SNSTopic 字段来表示 S3 Glacier 在完成任务后可以向其发布通知的 Amazon SNS 主题。

注意

要向 Amazon SNS 发布通知，您必须自己创建主题（如果主题不存在）。S3 Glacier 不会为您创建主题。该主题必须具有从 S3 Glacier 文件库接收出版物的权限。S3 Glacier 不会验证文件库是否有权向该主题发布内容。如果没有适当配置权限，则即使任务完成后，您可能也不会收到通知。

语法

以下是用于启动任务的请求语法。

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

{
   "jobParameters": { 
      "ArchiveId": "string",
      "Description": "string",
      "Format": "string",
      "InventoryRetrievalParameters": { 
         "EndDate": "string",
         "Limit": "string",
         "Marker": "string",
         "StartDate": "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"
            }
         }
      },
      "SNSTopic": "string",
      "Tier": "string",
      "Type": "string"
   }
}
注意

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

请求正文

请求接受请求正文中采用 JSON 格式的以下数据。

jobParameters

提供用于指定任务信息的选项。

类型：jobParameters 对象

必需：是

响应

S3 Glacier 创建了任务。在响应中，它会返回任务的 URI。

语法

HTTP/1.1 202 Accepted
x-amzn-RequestId: x-amzn-RequestId
Date: Date
Location: location
x-amz-job-id: jobId
x-amz-job-output-path: jobOutputPath

响应标头

标题 描述
Location

任务的相对 URI 路径。您可以使用此 URI 路径来查找任务状态。有关更多信息，请参阅 描述任务（获取任务 ID）。

类型：字符串

默认值：无
x-amz-job-id

任务的 ID。此值也包括在 Location 标头中，作为该标头的一部分。

类型：字符串

默认值：无
x-amz-job-output-path

存储 Select 结果的位置的路径。

类型：字符串

默认值：无

响应正文

此操作不返回响应正文。

错误

除了所有 Amazon S3 Glacier 操作中常见的可能错误外，此操作还包括以下一个或多个错误。有关 Amazon S3 Glacier 错误的信息以及错误代码列表，请参阅错误响应。

代码 描述 HTTP 状态代码 类型
InsufficientCapacityException 如果没有足够的容量处理此加速请求，则返回此代码。此错误仅适用于加速检索，不适用于标准或批量检索。 503 Service Unavailable 服务器

示例

示例请求：启动档案检索任务

POST /-/vaults/examplevault/jobs 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

{
  "Type": "archive-retrieval",
  "ArchiveId": "NkbByEejwEggmBz2fTHgJrg0XBoDfjP4q6iu87-TjhqG6eGoOY9Z8i1_AUyUsuhPAdTqLHy8pTl5nfCFJmDl2yEZONi5L26Omw12vcs01MNGntHEQL8MBfGlqrEXAMPLEArchiveId",
  "Description": "My archive description",
  "SNSTopic": "arn:aws:sns:us-west-2:111111111111:Glacier-ArchiveRetrieval-topic-Example",
  "Tier" : "Bulk"
}

以下是请求正文的示例，它使用 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"
}

响应示例

HTTP/1.1 202 Accepted
x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
Date: Wed, 10 Feb 2017 12:00:00 GMT
Location: /111122223333/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID
x-amz-job-id: HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID

示例请求：启动清单检索任务

以下请求会启动清单检索任务，以从 examplevault 文件库获取档案列表。在请求正文中，设置为 Format 的 CSV 表示清单会以 CSV 格式返回。

POST /-/vaults/examplevault/jobs HTTP/1.1
Host: glacier.us-west-2.amazonaws.com
x-amz-Date: 20170210T120000Z
Content-Type: application/x-www-form-urlencoded
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

{
  "Type": "inventory-retrieval",
  "Description": "My inventory job",
  "Format": "CSV",  
  "SNSTopic": "arn:aws:sns:us-west-2:111111111111:Glacier-InventoryRetrieval-topic-Example"
}

响应示例

HTTP/1.1 202 Accepted
x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
Date: Wed, 10 Feb 2017 12:00:00 GMT 
Location: /111122223333/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID
x-amz-job-id: HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID

示例请求：使用日期筛选及设置限制来启动清单检索任务，以及检索下一页清单项目的后续请求。

以下请求通过使用日期筛选及设置限制来启动文件库清单检索任务。


{
    "ArchiveId": null, 
    "Description": null, 
    "Format": "CSV", 
    "RetrievalByteRange": null, 
    "SNSTopic": null, 
    "Type": "inventory-retrieval", 
    "InventoryRetrievalParameters": {
        "StartDate": "2013-12-04T21:25:42Z",
        "EndDate": "2013-12-05T21:25:42Z", 
        "Limit" : "10000"
    }, 
}

以下例举了使用从描述任务（获取任务 ID） 获取的标记检索下一页清单项目的后续请求。

{
    "ArchiveId": null, 
    "Description": null, 
    "Format": "CSV", 
    "RetrievalByteRange": null, 
    "SNSTopic": null, 
    "Type": "inventory-retrieval", 
    "InventoryRetrievalParameters": {
        "StartDate": "2013-12-04T21:25:42Z",
        "EndDate": "2013-12-05T21:25:42Z", 
        "Limit": "10000",
        "Marker": "vyS0t2jHQe5qbcDggIeD50chS1SXwYMrkVKo0KHiTUjEYxBGCqRLKaiySzdN7QXGVVV5XZpNVG67pCZ_uykQXFMLaxOSu2hO_-5C0AtWMDrfo7LgVOyfnveDRuOSecUo3Ueq7K0"
    }, 
}

响应示例

HTTP/1.1 202 Accepted
x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
Date: Wed, 10 Feb 2017 12:00:00 GMT 
Location: /111122223333/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID
x-amz-job-id: HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID
x-amz-job-output-path: test/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID/

相关部分