启动作业(POST 作业) - Amazon S3 Glacier
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 Amazon Web Services 服务入门

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

启动作业(POST 作业)

此操作会启动以下类型的 Amazon S3 Glacier (S3 Glacier) 作业:

  • select— 对档案执行查询

  • archive-retrieval— 检索档案

  • inventory-retrieval— 清点文件库

使用 Amazon S3 Glacier 选择作业

您使用一个 S3 Glacier Select 作业对档案对象执行 SQL 查询。要由 select 任务查询的档案对象必须格式化为未压缩的逗号分隔值 (CSV) 文件。有关 S3 Glacier Select 作业的概述信息,请参阅。使用 S3 冰川选择查询档案.

当启动 select 任务时,您可执行以下操作:

  • 为 select 查询的输出定义输出位置。此位置必须是同一Amazon作为包含要查询的档案对象的文件库。这些区域有: Amazon Web Services 账户 必须具有写入 S3 存储桶的权限。您可以为存储在 Amazon S3 中的输出对象指定存储类和加密。设置时S3Location,则阅读 Amazon S3 文档中的以下主题可能会有所帮助:

  • SelectParameters 中定义要对查询的 SELECT 使用的 SQL 表达式。例如,您可以使用类似以下示例的表达式:

    • 下面的示例表达式返回指定对象中的所有记录。

      SELECT * FROM archive
    • 假设您没有对存储在对象中的数据使用任何标头,则可以使用位置标头指定列。

      SELECT s._1, s._2 FROM archive s WHERE s._3 > 100
    • 如果您具有标头并且将 fileHeaderInfo 中的 CSVInput 设置为 Use,则可以在查询中指定标头。(如果将 fileHeaderInfo 字段设置为 Ignore,则查询会跳过第一行。) 您无法将序号位置与标题列名混合。

      SELECT s.Id, s.FirstName, s.SSN FROM archive s

有关将 SQL 与 S3 Glacier Select 搭配使用的更多信息,请参阅。Amazon S3 Select 和 S3 Glacier Select 的 SQL 参考.

当启动 select 任务时,您还可执行以下操作:

  • 指定 Expedited 层以加快您的查询。有关更多信息,请参阅加速、标准和批量层

  • 指定有关要查询的输入对象和 CSV 编码查询结果的序列化的数据序列化格式的详细信息。

  • 指定 Amazon Simple Notification Service (Amazon SNS) 主题,S3 Glacier 可以在任务完成后将通知发布到的 Amazon Simple Notification Service (Amazon SNS) 主题。您可以为每个任务请求指定 SNS 主题。只有在 S3 Glacier 完成作业后,系统才会发送通知。

  • 当任务正在进行时,您可以使用描述任务(获取任务 ID)以获取任务状态信息。但是,更有效的方法是使用 Amazon SNS 通知来确定任务何时完成。

当处理 select 任务时,您无法执行以下操作:

  • 调用 GetJobOutput 操作。任务输出写入到输出位置。

  • 使用具有范围的选择。

有关启动 select 任务的示例,请参阅示例请求:启动所选任务

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

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

  1. 使用 启动作业(POST 作业) 操作启动检索任务。

    重要

    数据检索策略可能导致您启动检索任务的请求以发生 PolicyEnforcedException 而失败。有关数据检索策略的更多信息,请参阅Amazon 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 返回其最近一次生成的清单,该清单是时间点快照,而不是实时数据。

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

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

确定清单检索范围

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

按档案创建日期筛选

您可以检索库存项目,以便在StartDateEndDate,方法是在启动任务请求. 将会返回在 StartDate 之后且 EndDate 之前创建的档案。如果您仅提供 StartDate,而不提供 EndDate,则会检索在 StartDate 或之后创建的所有的档案的清单。如果您仅提供 EndDate,而不提供 StartDate,则会检索在 EndDate 之前创建的所有档案的清单。

限制每次检索的清单项目

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

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

关于具有范围的档案检索

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

加速、标准和批量层

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

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

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

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

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

Requests

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

注意

要向 Amazon SNS 发布通知,您必须自己创建主题(如果主题不存在)。S3 冰川不会为您创建主题。主题必须有权从 S3 Glacier 文件库接收发布。S3 Glacier 不会验证文件库是否有权发布到主题。如果没有适当配置权限,则即使任务完成后,您可能也不会收到通知。

Syntax

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

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 冰川使用 Amazon Web Services 账户 与用来对请求签名的证书相匹配的 ID 相匹配。如果您使用账户 ID,请勿在 ID 中包含任何连字符 (“-”)。

请求正文

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

jobParameters

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

类型jobParameters 对象

必需:是

Responses

S3 冰川创建的作业。在响应中,它会返回任务的 URI。

Syntax

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 任务类型返回此标头。存储 Select 结果的位置的路径。

类型: 字符串

默认值:无

响应正文

此操作不返回响应正文。

Errors

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

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

Examples

示例请求:启动档案取回任务

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 文件库获取档案列表。在请求正文中,设置为 FormatCSV 表示清单会以 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" }, }

示例请求:启动所选任务

以下请求会启动一个 select 任务。

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": "select", "ArchiveId": "NkbByEejwEggmBz2fTHgJrg0XBoDfjP4q6iu87-TjhqG6eGoOY9Z8i1_AUyUsuhPAdTqLHy8pTl5nfCFJmDl2yEZONi5L26Omw12vcs01MNGntHEQL8MBfGlqrEXAMPLEArchiveId", "Description": null, "SNSTopic": null, "Tier": "Bulk", "SelectParameters": { "Expression": "select * from archive", "ExpressionType": "SQL", "InputSerialization": { "csv": { "Comments": null, "FileHeaderInfo": "None", "QuoteEscapeCharacter": "\"", "RecordDelimiter": "\n", "FieldDelimiter": ",", "QuoteCharacter": "\"" } }, "OutputSerialization": { "csv": { "QuoteFields": "AsNeeded", "QuoteEscapeCharacter": null, "RecordDelimiter": "\n", "FieldDelimiter": ",", "QuoteCharacter": "\"" } } }, "OutputLocation": { "S3": { "BucketName": "bucket-name", "Prefix": "test", "Encryption": { "EncryptionType": "AES256" }, "CannedACL": "private", "StorageClass": "STANDARD" } } }

响应示例

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/

相关部分