Amazon Glacier
开发人员指南 (API 版本 2012-06-01)
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 Amazon AWS 入门

启动作业(POST 作业)

此操作启动以下类型的 Amazon Glacier 任务:

  • select– 对档案执行 select 查询

  • archive-retrieval– 检索档案

  • inventory-retrieval– 清点文件库

处理 Amazon Glacier Select 任务

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

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

  • 为 select 查询的输出定义输出位置。该位置必须是与包含要查询的档案对象的文件库相同的 AWS 区域中的一个 Amazon S3 存储桶。启动任务的 AWS 账户必须具有写入 S3 存储桶的权限。您可以为存储在 Amazon S3 中的输出对象指定存储类和加密。当设置 S3 位置 时,阅读 Amazon S3 文档中的以下主题可能会有所帮助:

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

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

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

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

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

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

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

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

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

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

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

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

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

  • 使用具有范围的选择。

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

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

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

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

    重要

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

  2. 在任务完成后,使用 获取任务输出(获取输出) 操作下载字节。

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

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

  • 使用 Amazon SNS 通知 – 您可以指定 Amazon SNS 主题;完成任务后,Amazon Glacier 可以向其发布通知。您可以为每个任务请求指定 SNS 主题。只有在 Amazon Glacier 完成任务后,系统才会发送通知。除了为每个任务请求指定 SNS 主题以外,您还可以配置文件库的文件库通知,这样,系统就会为所有取回操作发送任务通知。有关更多信息,请参阅 设置文件库通知配置(设置通知配置)

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

注意

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

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

文件库清单

从您第一次将档案上传到文件库的日期开始,Amazon Glacier 大约每天都会更新一次文件库清单。如果在上次编制清单后没有对文件库执行过添加或删除档案的操作,则不会更新清单日期。当您为文件库清单启动任务时,Amazon Glacier 返回其最近一次生成的清单,该清单是时间点快照,而不是实时数据。

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

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

确定清单检索范围

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

按档案创建日期筛选

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

限制每次检索的清单项目

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

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

关于具有范围的档案检索

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

加速、标准和批量层

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

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

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

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

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

请求

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

注意

要向 Amazon SNS 发布通知,您必须自己创建主题 (如果主题不存在)。Amazon Glacier 不会为您创建主题。主题必须拥有从 Amazon Glacier 文件库接收发布的通知的权限。Amazon 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 值为拥有文件库的账户的 AWS 账户 ID。您可以指定一个 AWS 账户 ID 或者选择指定单一的“-” (连字符),在这种情况下,Amazon Glacier 会使用与用于对请求签名的证书关联的 AWS 账户 ID。如果您使用账户 ID,请勿在该 ID 中包括连字符 (“-”)。

请求正文

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

jobParameters

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

类型jobParameters 对象

必需:是

响应

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

类型:字符串

默认值:无

响应正文

此操作不返回响应正文。

错误

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

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

示例

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

POST /-/vaults/examplevault/jobs HTTP/1.1 Host: glacier.us-west-2.amazonaws.com x-amz-Date: 20141123T120000Z 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: Sun, 23 Nov 2014 12:00:00 GMT Location: /111122223333/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID x-amz-job-id: HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID

示例请求:启动清单取回任务

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

POST /-/vaults/examplevault/jobs HTTP/1.1 Host: glacier.us-west-2.amazonaws.com x-amz-Date: 20141123T120000Z 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: Sun, 23 Nov 2014 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 任务

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

POST /-/vaults/examplevault/jobs HTTP/1.1 Host: glacier.us-west-2.amazonaws.com x-amz-Date: 20141123T120000Z 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: Sun, 23 Nov 2014 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/

相关部分