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

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

启动作业（POST 作业）

此操作会访问您的任意存档案案案案案案案案案Amazon S3 案案案案案案案案案案案案案案

  • 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 的档案的元数据。此时，您可能会发现，文件库库存对于根据需要将您数据库中的信息与实际文件库库存进行协调很有用。有关清单任务输出中返回的数据字段的更多信息，请参阅响应正文。

确定清单检索范围

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

按档案创建日期筛选

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

限制每次检索的清单项目

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

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

关于具有范围的档案检索

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

加速、标准和批量层

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

  • Expedited— Expeditexpedited 允许您在偶尔尔尔尔尔尔尔尔访问数据。对于除了最大型档案 (250 MB+) 之外的所有其他档案，使用加速层访问的数据通常在 1 到 5 分钟内可用。

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

  • Bulk— 批量是 S3 Glacier 中成本最低的访问数据，甚至是 PB 级（甚至是 PB 级）的数据。使用批量层访问的数据通常在 5–12 小时内可用。

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

请求

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

注意

要向 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/

相关部分