**此页面仅适用于使用文件库和 2012 年原始 REST API 的 Amazon Glacier 服务的现有客户。**
如果您正在寻找归档存储解决方案，建议使用 Amazon S3 中的 Amazon Glacier 存储类别 S3 Glacier Instant Retrieval、S3 Glacier Flexible Retrieval 和 S3 Glacier Deep Archive。要了解有关这些存储选项的更多信息，请参阅 [Amazon Glacier 存储类别](https://aws.amazon.com/s3/storage-classes/glacier/)。
Amazon Glacier（最初基于保管库的独立服务）不再接受新客户。Amazon Glacier 是一项独立的服务 APIs ，拥有自己的服务，可将数据存储在文件库中，不同于亚马逊 S3 和 Amazon S3 Glacier 存储类别。在 Amazon Glacier 中，您现有的数据将确保安全，并且可以无限期地访问。无需进行迁移。对于低成本、长期的存档存储， AWS 建议[使用 Amazon S3 Glacier 存储类别，这些存储类别](https://aws.amazon.com/s3/storage-classes/glacier/)基于S3存储桶 APIs、完全 AWS 区域 可用性、更低的成本和 AWS 服务集成，可提供卓越的客户体验。如果您希望加强功能，可以考虑使用我们的 [AWS 将数据从 Amazon Glacier 文件库传输到 Amazon S3 Glacier 存储类别的解决方案指南](https://aws.amazon.com/solutions/guidance/data-transfer-from-amazon-s3-glacier-vaults-to-amazon-s3/)，迁移到 Amazon S3 Glacier 存储类别。
本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# Amazon Glacier 的 API 参考
API 参考
Amazon Glacier 支持一系列操作，特别是一组用于与服务交互的 RESTful API 调用。
您可以使用能够发送 HTTP 请求的任何编程库，将您的 REST 请求发送到 Amazon Glacier。发送 REST 请求时，Amazon Glacier 会要求您通过对请求签名来验证每个请求。此外，上传档案时，您还必须计算有效载荷的校验和，并将它包括在您的请求中。有关更多信息，请参阅[对请求进行签名](amazon-glacier-signing-requests.md)。
如果发生错误，您需要知道 Amazon Glacier 在错误响应中发送的内容，以便进行处理。除了介绍 REST 操作以外，此部分还提供了所有的此类信息，以便您直接进行 REST API 调用。
您可以直接使用 REST API 调用或者使用 Amazon SDK，这些 SDK 提供了包装程序库。这些库会对您发送的每个请求签名，并对您请求中的有效载荷计算校验和。因此，使用 Amazon SDK 可以简化您的编码任务。此开发人员指南通过实际案例举例说明使用适用于 Java 的 AWS SDK 和 .NET 的基本 Amazon Glacier 操作。有关更多信息，请参阅[AWS SDKs 与 Amazon Glacier 搭配使用](using-aws-sdk.md)。
**Topics**
+ [
# 通用请求标头
](api-common-request-headers.md)
+ [
# 通用响应标头
](api-common-response-headers.md)
+ [
# 对请求进行签名
](amazon-glacier-signing-requests.md)
+ [
# 计算校验和
](checksum-calculations.md)
+ [
# 错误响应
](api-error-responses.md)
+ [
# 文件库操作
](vault-operations.md)
+ [
# 档案操作
](archive-operations.md)
+ [
# 分段上传操作
](multipart-archive-operations.md)
+ [
# 任务操作
](job-operations.md)
+ [
# 在任务操作中使用的数据类型
](api-data-types.md)
+ [
# 数据检索操作
](data-retrieval-policy-operations.md)
# 通用请求标头
Amazon Glacier（Amazon Glacier）REST 请求采用包含此请求基本说明的标头。下表描述了所有 Amazon Glacier REST 请求均可使用的标头。
| 标头名称 | 描述 | 是否必需 |
| --- | --- | --- |
| Authorization | 对请求签名所需的标头。Amazon Glacier 需要签名版本 4。有关更多信息，请参阅[对请求进行签名](amazon-glacier-signing-requests.md)。 类型：字符串 | 是 |
| Content-Length | 请求正文（不带标头）的长度。 类型：字符串 条件：只有 [上传档案（POST archive）](api-archive-post.md) API 才需要。 | 有条件 |
| Date | 可以用于创建 `Authorization` 标头中包含的签名的日期。如果要将 `Date` 标头用于签名，则必须使用 ISO 8601 基本格式来指定它。在这种情况下，不需要 `x-amz-date` 标头。请注意，存在 `x-amz-date` 时，它始终会覆盖 `Date` 标头的值。 如果 Date 标头不用于签名，则可以为 [RFC 2616](http://tools.ietf.org/html/rfc2616#section-3.3) 第 3.3 部分指定的完整日期格式之一。例如，以下日期/时间 `Wed, 10 Feb 2017 12:00:00 GMT` 是用于 Amazon Glacier 的有效日期/时间标头。 如果您要将 `Date` 标头用于签名，则它必须使用 ISO 8601 基本 `YYYYMMDD'T'HHMMSS'Z'` 格式。 类型：字符串 条件：如果指定了 `Date`，但它没有使用 ISO 8601 基本格式，则您还必须包括 `x-amz-date` 标头。如果使用 ISO 8601 基本格式指定了 `Date`，则它足够用于对请求签名，您无需 `x-amz-date` 标头。有关更多信息，请参阅《Amazon Web 服务词汇表》中的[处理签名版本 4 中的日期](https://docs.aws.amazon.com/general/latest/gr/sigv4-date-handling.html)**。 | 有条件 |
| Host | 此标头指定您要将请求发送到的服务端点。值必须为“`glacier.region.amazonaws.com`”格式，其中，*区域*由 AWS 区域名称（例如 `us-west-2`）代替。 类型：字符串 | 是 |
| x-amz-content-sha256 | 对通过 [上传档案（POST archive）](api-archive-post.md) 或 [上传段（PUT uploadID）](api-upload-part.md) 上传的整个有效载荷进行计算得出的 SHA256 校验和。虽然此标头与 `x-amz-sha256-tree-hash` 标头不同，但是，对于某些小型有效载荷，值是相同的。如果需要 `x-amz-content-sha256`，则必须指定 `x-amz-content-sha256` 和 `x-amz-sha256-tree-hash`。 类型：字符串 条件：流式处理 API、[上传档案（POST archive）](api-archive-post.md) 和 [上传段（PUT uploadID）](api-upload-part.md) 需要。 | 有条件 |
| x-amz-date | 用于在 Authorization 标头中创建签名的日期。格式必须为使用 `YYYYMMDD'T'HHMMSS'Z'` 格式的 ISO 8601 基本格式。例如，以下日期/时间 `20170210T120000Z` 是用于 Amazon Glacier 的有效 `x-amz-date`。 类型：字符串 条件：`x-amz-date` 对所有请求而言是可选的；它可以用于覆盖对请求签名所使用的日期。如果使用 ISO 8601 基本格式指定了 `Date` 标头，则无需 `x-amz-date`。存在 `x-amz-date` 时，它始终会覆盖 `Date` 标头的值。有关更多信息，请参阅《Amazon Web 服务词汇表》中的[处理签名版本 4 中的日期](https://docs.aws.amazon.com/general/latest/gr/sigv4-date-handling.html)**。 | 有条件 |
| x-amz-glacier-version | 要使用的 Amazon Glacier API 版本。当前版本为 `2012-06-01`。 类型：字符串 | 是 |
| x-amz-sha256-tree-hash | 对上传的档案（[上传档案（POST archive）](api-archive-post.md)）或档案段（[上传段（PUT uploadID）](api-upload-part.md)）进行计算得出的 SHA256 树形哈希校验和。有关计算此校验和的更多信息，请参阅[计算校验和](checksum-calculations.md)。 类型：字符串 默认值：无 条件：[上传档案（POST archive）](api-archive-post.md) 和 [上传段（PUT uploadID）](api-upload-part.md) 需要。 | 有条件 |
# 通用响应标头
下表描述了大多数 API 响应通用的响应标头。
| 名称 | 描述 |
| --- | --- |
| Content-Length | 响应正文的长度（以字节为单位）。 类型：字符串 |
| Date | Amazon Glacier（Amazon Glacier）响应的日期和时间，例如 `Wed, 10 Feb 2017 12:00:00 GMT`。日期的格式必须是 [RFC 2616](https://datatracker.ietf.org/doc/html/rfc2616#section-3.3) 第 3.3 节中指定的完整日期格式之一。请注意，返回的 `Date` 可能与其他日期略有偏差，因此，例如，从[上传档案（POST archive）](api-archive-post.md) 请求返回的日期可能与文件库库存列表中的档案所显示的日期不匹配。 类型：字符串 |
| x-amzn-RequestId | 由 Amazon Glacier 创建的唯一标识您请求的值。如果您在使用 Amazon Glacier 时遇到问题，AWS 可以使用此值来解决问题。建议您记录这些值。 类型：字符串 |
| x-amz-sha256-tree-hash | 档案或清单正文的 SHA256 树形哈希校验和。有关计算此校验和的更多信息，请参阅[计算校验和](checksum-calculations.md)。 类型：字符串 |
# 对请求进行签名
Amazon Glacier 要求通过对请求进行签名，验证所发送的每个请求的身份。您使用加密哈希函数计算数字签名，从而对请求签名。加密哈希是根据输入内容返回唯一哈希值的函数。对哈希函数的输入内容包括您的请求文本和秘密访问密钥。哈希函数返回哈希值，您将该值包含在请求中，作为签名。该签名是您的请求的 `Authorization` 标头的一部分。
收到您的请求后，Amazon Glacier 使用与您用于对该请求进行签名的相同哈希函数和输入重新计算签名。如果所得签名与该请求中的签名相匹配，则 Amazon Glacier 处理该请求。否则，请求将被拒绝。
Amazon Glacier 支持使用 [AWS 签名版本 4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) 进行身份验证。计算签名的过程可分为三个任务：
+ [任务 1：创建规范请求](https://docs.aws.amazon.com/general/latest/gr/sigv4-create-canonical-request.html)
将您的 HTTP 请求重新排列为规范格式。必须使用规范格式，因为 Amazon Glacier 在重新计算签名以与您发送的签名进行比较时使用同一规范格式。
+ [任务 2：创建待签字符串](https://docs.aws.amazon.com/general/latest/gr/sigv4-create-string-to-sign.html)
创建一个字符串，将该字符串用作您的加密哈希函数输入值中的一项。该字符串称为*待签字符串*，是哈希算法名称、请求日期、*凭证范围*字符串以及来自上一任务的规范化请求的结合。*凭证范围*字符串本身就是日期、 AWS 区域和服务信息的串联。
+ [任务 3：创建签名](https://docs.aws.amazon.com/general/latest/gr/sigv4-calculate-signature.html)
使用加密哈希函数为您的请求创建签名，该函数接受两种输入字符串：*待签字符串*和*派生密钥*。*派生密钥*的计算方法是从您的私有访问密钥开始，然后使用*凭证范围*字符串创建一系列基于哈希的消息身份验证代码 () HMACs。请注意，此签名步骤中使用的哈希函数不是 Amazon Glacier APIs 中用于上传数据的树形哈希算法。
**Topics**
+ [
## 签名计算示例
](#example-signature-calculation)
+ [
## 为流式处理操作计算签名
](#signature-calculation-streaming)
## 签名计算示例
以下示例引导您了解为[创建文件库（PUT vault）](api-vault-put.md)创建签名的详细信息。该示例可用作核查您的签名计算方法的参考。有关更多信息，请参阅 I *AM 用户指南*中的[签署 AWS API 请求](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html)。
示例假定以下各项：
+ 请求的时间戳为 `Fri, 25 May 2012 00:24:53 GMT`。
+ 端点为美国东部（弗吉尼亚州北部）区域 ` us-east-1`。
通用请求语法（包括 JSON 正文）为：
```
PUT /-/vaults/examplevault HTTP/1.1
Host: glacier.us-east-1.amazonaws.com
Date: Fri, 25 May 2012 00:24:53 GMT
Authorization: SignatureToBeCalculated
x-amz-glacier-version: 2012-06-01
```
为[任务 1：创建规范请求](#SignatureCalculationTask1)计算的规范请求格式为：
```
PUT
/-/vaults/examplevault
host:glacier.us-east-1.amazonaws.com
x-amz-date:20120525T002453Z
x-amz-glacier-version:2012-06-01
host;x-amz-date;x-amz-glacier-version
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
```
规范请求的最后一行是请求正文的哈希值。另外，请注意规范请求的第三行是空的。这是因为此 API 没有查询参数。
[任务 2：创建待签字符串](#SignatureCalculationTask2)的*待签字符串*为：
```
AWS4-HMAC-SHA256
20120525T002453Z
20120525/us-east-1/glacier/aws4_request
5f1da1a2d0feb614dd03d71e87928b8e449ac87614479332aced3a701f916743
```
*待签字符串*的第一行是算法，第二行是时间戳，第三行是*凭证范围*，最后一行是来自[任务 1：创建规范请求](#SignatureCalculationTask1)的规范请求的哈希。要在凭证范围中使用的服务名称为 `glacier`。
对于[任务 3：创建签名](#SignatureCalculationTask3)，*派生密钥*可以表示为：
```
derived key = HMAC(HMAC(HMAC(HMAC("AWS4" + YourSecretAccessKey,"20120525"),"us-east-1"),"glacier"),"aws4_request")
```
如果使用秘密访问密钥 `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`，则计算出的签名为：
```
3ce5b2f2fffac9262b4da9256f8d086b4aaf42eba5f111c21681a65a127b7c2a
```
最终步骤是构造 `Authorization` 标头。对于示例访问密钥 `AKIAIOSFODNN7EXAMPLE`，标头（为了便于阅读，添加了换行符）为：
```
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20120525/us-east-1/glacier/aws4_request,
SignedHeaders=host;x-amz-date;x-amz-glacier-version,
Signature=3ce5b2f2fffac9262b4da9256f8d086b4aaf42eba5f111c21681a65a127b7c2a
```
## 为流式处理操作计算签名
[上传档案（POST archive）](api-archive-post.md)和[上传段（PUT uploadID）](api-upload-part.md)为流式处理操作，这些操作要求您在对请求签名以及发送请求时包括一个附加标头 `x-amz-content-sha256`。流式处理操作的签名步骤与其他操作的签名步骤完全相同，只是要另外添加流式处理标头。
直播标头的计算基于`x-amz-content-sha256`要上传的全部内容（有效负载）的SHA256 哈希值。请注意，此计算与 SHA256 树形哈希 ([计算校验和](checksum-calculations.md)) 不同。除了微不足道的情况外，有效载荷数据的 SHA 256 哈希值将与有效载荷数据的 SHA256 树形哈希值不同。
如果将有效载荷数据指定为字节数组，则可以使用以下 Java 代码片段来计算 SHA256 哈希。
```
public static byte[] computePayloadSHA256Hash2(byte[] payload) throws NoSuchAlgorithmException, IOException {
BufferedInputStream bis =
new BufferedInputStream(new ByteArrayInputStream(payload));
MessageDigest messageDigest = MessageDigest.getInstance("SHA-256");
byte[] buffer = new byte[4096];
int bytesRead = -1;
while ( (bytesRead = bis.read(buffer, 0, buffer.length)) != -1 ) {
messageDigest.update(buffer, 0, bytesRead);
}
return messageDigest.digest();
}
```
同样，在 C\$1 中，您可以计算有效载荷数据的 SHA256 哈希值，如以下代码片段所示。
```
public static byte[] CalculateSHA256Hash(byte[] payload)
{
SHA256 sha256 = System.Security.Cryptography.SHA256.Create();
byte[] hash = sha256.ComputeHash(payload);
return hash;
}
```
### 流式处理 API 的示例签名计算
以下示例将引导您详细了解创建签名的详细信息[上传档案（POST archive）](api-archive-post.md)，该签名是 Amazon Glacier APIs 中直播的两个签名之一。示例假定以下各项：
+ 请求的时间戳为 `Mon, 07 May 2012 00:00:00 GMT`。
+ 端点为美国东部（弗吉尼亚州北部）区域 us-east-1。
+ 内容有效载荷为字符串“Welcome to Amazon Glacier”。
通用请求语法（包括 JSON 正文）显示在以下示例中。请注意，其中包括了` x-amz-content-sha256` 标头。在此简化示例中，`x-amz-sha256-tree-hash` 和 `x-amz-content-sha256` 是相同的值。但是，对于大于 1 MB 的档案上传，情况就不是这样。
```
POST /-/vaults/examplevault HTTP/1.1
Host: glacier.us-east-1.amazonaws.com
Date: Mon, 07 May 2012 00:00:00 GMT
x-amz-archive-description: my archive
x-amz-sha256-tree-hash: SHA256 tree hash
x-amz-content-sha256: SHA256 payload hash
Authorization: SignatureToBeCalculated
x-amz-glacier-version: 2012-06-01
```
为[任务 1：创建规范请求](#SignatureCalculationTask1)计算的规范请求格式显示如下。请注意，其中包括了流式处理标头 `x-amz-content-sha256` 及其值。这意味着您必须先读取有效负载并计算 SHA256 哈希值，然后再计算签名。
```
POST
/-/vaults/examplevault
host:glacier.us-east-1.amazonaws.com
x-amz-content-sha256:726e392cb4d09924dbad1cc0ba3b00c3643d03d14cb4b823e2f041cff612a628
x-amz-date:20120507T000000Z
x-amz-glacier-version:2012-06-01
host;x-amz-content-sha256;x-amz-date;x-amz-glacier-version
726e392cb4d09924dbad1cc0ba3b00c3643d03d14cb4b823e2f041cff612a628
```
签名计算的其余操作遵循[签名计算示例](#example-signature-calculation)中所述的步骤。使用秘密访问密钥 `Authorization` 和访问密钥 `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY` 的 `AKIAIOSFODNN7EXAMPLE` 标头显示如下（为了便于阅读，添加了换行符）：
```
Authorization=AWS4-HMAC-SHA256
Credential=AKIAIOSFODNN7EXAMPLE/20120507/us-east-1/glacier/aws4_request,
SignedHeaders=host;x-amz-content-sha256;x-amz-date;x-amz-glacier-version,
Signature=b092397439375d59119072764a1e9a144677c43d9906fd98a5742c57a2855de6
```
# 计算校验和
计算校验和
上传档案时，您必须包括 `x-amz-sha256-tree-hash` 和 `x-amz-content-sha256` 标头。`x-amz-sha256-tree-hash` 标头是您的请求正文中有效载荷的校验和。此主题描述了如何计算 `x-amz-sha256-tree-hash` 标头。`x-amz-content-sha256` 标头是整个有效载荷的哈希，并且是授权所必需的项目。有关更多信息，请参阅[流式处理 API 的示例签名计算](amazon-glacier-signing-requests.md#example-signature-calculation-streaming)。
您的请求的有效载荷可以是：
+ **整个档案** – 在单一请求中使用上传档案 API 上传档案时，您可以在请求正文中发送整个档案。在这种情况下，您必须包括整个档案的校验和。
+ **档案段** – 使用分段上传 API 分段上传档案时，您可以在请求正文中只发送档案的一段。在这种情况下，您可以包括档案段的校验和。上传所有段后，您可以发送完成分段上传请求，该请求必须包括整个档案的校验和。
有效载荷的校验和为 SHA256 树形哈希。它被称为树形哈希是因为，在计算校验和的过程中，您会计算 SHA256 哈希值树。根部的哈希值为整个档案的校验和。
**注意**
此部分描述了一种计算 SHA256 树形哈希的方法。但是，只要能得出相同的结果，您可以使用任何方法。
您可以按以下方法计算 SHA256 树形哈希：
1. 针对有效载荷数据的每个 1 MB 分块，计算 SHA256 哈希。数据的最后一个分块可以小于 1 MB。例如，如果您要上传一个 3.2 MB 的档案，则您需要计算数据的前三个 1 MB 分块中每一个分块的 SHA256 哈希值，然后计算剩余 0.2 MB 数据的 SHA256 哈希。这些哈希值构成了树的叶节点。
1. 构建树的下一层。
1. 连接两个连续子节点的哈希值，然后计算连接的哈希值的 SHA256 哈希。此连接和 SHA256 哈希的生成会产生这两个子节点的父节点。
1. 如果只剩下一个子节点，您可以将该哈希值提升到树的下一层。
1. 重复步骤 2，直到结果树具有根为止。树根提供了整个档案的哈希，相应的子树根提供了分段上传中的段的哈希。
**Topics**
+ [
## 树形哈希示例 1：在单一请求中上传档案
](#checksum-calculations-upload-archive-in-single-payload)
+ [
## 树形哈希示例 2：使用分段上传来上传档案
](#checksum-calculations-upload-archive-using-mpu)
+ [
## 计算文件的树形哈希
](#checksum-calculations-examples)
+ [
# 下载数据时接收校验和
](checksum-calculations-range.md)
## 树形哈希示例 1：在单一请求中上传档案
在单一请求中使用上传档案 API（请参阅[上传档案（POST archive）](api-archive-post.md)）上传档案时，请求的有效载荷会包括整个档案。因此，您必须在 `x-amz-sha256-tree-hash` 请求标头中包括整个档案的树形哈希。假设您要上传一个 6.5 MB 的档案。下图说明了创建档案的 SHA256 哈希的流程。您读取档案并为每个 1 MB 分块计算 SHA256 哈希。此外，您还要为剩余的 0.5 MB 数据计算哈希，然后按前面的步骤所述构建树。
![\[示意图显示树形哈希示例在单一请求中上传档案。\]](http://docs.aws.amazon.com/zh_cn/amazonglacier/latest/dev/images/TreeHash-ArchiveUploadSingleRequest.png)
## 树形哈希示例 2：使用分段上传来上传档案
在使用分段上传来上传档案时计算树形哈希的流程与在单一请求中上传档案时相同。唯一的区别是，在分段上传中，您在每个请求中只（使用[上传段（PUT uploadID）](api-upload-part.md)API）上传档案的一段，因此，您在 `x-amz-sha256-tree-hash` 请求标头中只提供该段的校验和。但是，上传所有段后，您必须发送完成分段上传（请参阅[完成分段上传（POST uploadID）](api-multipart-complete-upload.md)）请求，并在 `x-amz-sha256-tree-hash` 请求标头中包含整个档案的树形哈希。
![\[示意图显示树形哈希示例使用分段上传来上传档案。\]](http://docs.aws.amazon.com/zh_cn/amazonglacier/latest/dev/images/TreeHash-MPU.png)
## 计算文件的树形哈希
计算文件的树形哈希
此处显示的算法是出于演示目的而选择的。您可以根据实施情况的需要而优化代码。如果您使用 Amazon SDK 对 Amazon Glacier（Amazon Glacier）进行编程，则系统会为您完成树形哈希计算，您只需提供文件引用。
**Example 1：Java 示例**
以下示例说明如何使用 Java 计算文件的 SHA256 树形哈希。您可以通过提供文件位置作为参数来运行此示例，也可以直接从您的代码使用 `TreeHashExample.computeSHA256TreeHash` 方法。
```
import java.io.File;
import java.io.FileInputStream;
import java.io.IOException;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
public class TreeHashExample {
static final int ONE_MB = 1024 * 1024;
/**
* Compute the Hex representation of the SHA-256 tree hash for the specified
* File
*
* @param args
* args[0]: a file to compute a SHA-256 tree hash for
*/
public static void main(String[] args) {
if (args.length < 1) {
System.err.println("Missing required filename argument");
System.exit(-1);
}
File inputFile = new File(args[0]);
try {
byte[] treeHash = computeSHA256TreeHash(inputFile);
System.out.printf("SHA-256 Tree Hash = %s\n", toHex(treeHash));
} catch (IOException ioe) {
System.err.format("Exception when reading from file %s: %s", inputFile,
ioe.getMessage());
System.exit(-1);
} catch (NoSuchAlgorithmException nsae) {
System.err.format("Cannot locate MessageDigest algorithm for SHA-256: %s",
nsae.getMessage());
System.exit(-1);
}
}
/**
* Computes the SHA-256 tree hash for the given file
*
* @param inputFile
* a File to compute the SHA-256 tree hash for
* @return a byte[] containing the SHA-256 tree hash
* @throws IOException
* Thrown if there's an issue reading the input file
* @throws NoSuchAlgorithmException
*/
public static byte[] computeSHA256TreeHash(File inputFile) throws IOException,
NoSuchAlgorithmException {
byte[][] chunkSHA256Hashes = getChunkSHA256Hashes(inputFile);
return computeSHA256TreeHash(chunkSHA256Hashes);
}
/**
* Computes a SHA256 checksum for each 1 MB chunk of the input file. This
* includes the checksum for the last chunk even if it is smaller than 1 MB.
*
* @param file
* A file to compute checksums on
* @return a byte[][] containing the checksums of each 1 MB chunk
* @throws IOException
* Thrown if there's an IOException when reading the file
* @throws NoSuchAlgorithmException
* Thrown if SHA-256 MessageDigest can't be found
*/
public static byte[][] getChunkSHA256Hashes(File file) throws IOException,
NoSuchAlgorithmException {
MessageDigest md = MessageDigest.getInstance("SHA-256");
long numChunks = file.length() / ONE_MB;
if (file.length() % ONE_MB > 0) {
numChunks++;
}
if (numChunks == 0) {
return new byte[][] { md.digest() };
}
byte[][] chunkSHA256Hashes = new byte[(int) numChunks][];
FileInputStream fileStream = null;
try {
fileStream = new FileInputStream(file);
byte[] buff = new byte[ONE_MB];
int bytesRead;
int idx = 0;
int offset = 0;
while ((bytesRead = fileStream.read(buff, offset, ONE_MB)) > 0) {
md.reset();
md.update(buff, 0, bytesRead);
chunkSHA256Hashes[idx++] = md.digest();
offset += bytesRead;
}
return chunkSHA256Hashes;
} finally {
if (fileStream != null) {
try {
fileStream.close();
} catch (IOException ioe) {
System.err.printf("Exception while closing %s.\n %s", file.getName(),
ioe.getMessage());
}
}
}
}
/**
* Computes the SHA-256 tree hash for the passed array of 1 MB chunk
* checksums.
*
* This method uses a pair of arrays to iteratively compute the tree hash
* level by level. Each iteration takes two adjacent elements from the
* previous level source array, computes the SHA-256 hash on their
* concatenated value and places the result in the next level's destination
* array. At the end of an iteration, the destination array becomes the
* source array for the next level.
*
* @param chunkSHA256Hashes
* An array of SHA-256 checksums
* @return A byte[] containing the SHA-256 tree hash for the input chunks
* @throws NoSuchAlgorithmException
* Thrown if SHA-256 MessageDigest can't be found
*/
public static byte[] computeSHA256TreeHash(byte[][] chunkSHA256Hashes)
throws NoSuchAlgorithmException {
MessageDigest md = MessageDigest.getInstance("SHA-256");
byte[][] prevLvlHashes = chunkSHA256Hashes;
while (prevLvlHashes.length > 1) {
int len = prevLvlHashes.length / 2;
if (prevLvlHashes.length % 2 != 0) {
len++;
}
byte[][] currLvlHashes = new byte[len][];
int j = 0;
for (int i = 0; i < prevLvlHashes.length; i = i + 2, j++) {
// If there are at least two elements remaining
if (prevLvlHashes.length - i > 1) {
// Calculate a digest of the concatenated nodes
md.reset();
md.update(prevLvlHashes[i]);
md.update(prevLvlHashes[i + 1]);
currLvlHashes[j] = md.digest();
} else { // Take care of remaining odd chunk
currLvlHashes[j] = prevLvlHashes[i];
}
}
prevLvlHashes = currLvlHashes;
}
return prevLvlHashes[0];
}
/**
* Returns the hexadecimal representation of the input byte array
*
* @param data
* a byte[] to convert to Hex characters
* @return A String containing Hex characters
*/
public static String toHex(byte[] data) {
StringBuilder sb = new StringBuilder(data.length * 2);
for (int i = 0; i < data.length; i++) {
String hex = Integer.toHexString(data[i] & 0xFF);
if (hex.length() == 1) {
// Append leading zero.
sb.append("0");
}
sb.append(hex);
}
return sb.toString().toLowerCase();
}
}
```
**Example 2：C\$1 .NET 示例**
以下示例说明如何计算文件的 SHA256 树形哈希。您可以通过提供文件位置作为参数来运行此示例。
```
using System;
using System.IO;
using System.Security.Cryptography;
namespace ExampleTreeHash
{
class Program
{
static int ONE_MB = 1024 * 1024;
/**
* Compute the Hex representation of the SHA-256 tree hash for the
* specified file
*
* @param args
* args[0]: a file to compute a SHA-256 tree hash for
*/
public static void Main(string[] args)
{
if (args.Length < 1)
{
Console.WriteLine("Missing required filename argument");
Environment.Exit(-1);
}
FileStream inputFile = File.Open(args[0], FileMode.Open, FileAccess.Read);
try
{
byte[] treeHash = ComputeSHA256TreeHash(inputFile);
Console.WriteLine("SHA-256 Tree Hash = {0}", BitConverter.ToString(treeHash).Replace("-", "").ToLower());
Console.ReadLine();
Environment.Exit(-1);
}
catch (IOException ioe)
{
Console.WriteLine("Exception when reading from file {0}: {1}",
inputFile, ioe.Message);
Console.ReadLine();
Environment.Exit(-1);
}
catch (Exception e)
{
Console.WriteLine("Cannot locate MessageDigest algorithm for SHA-256: {0}",
e.Message);
Console.WriteLine(e.GetType());
Console.ReadLine();
Environment.Exit(-1);
}
Console.ReadLine();
}
/**
* Computes the SHA-256 tree hash for the given file
*
* @param inputFile
* A file to compute the SHA-256 tree hash for
* @return a byte[] containing the SHA-256 tree hash
*/
public static byte[] ComputeSHA256TreeHash(FileStream inputFile)
{
byte[][] chunkSHA256Hashes = GetChunkSHA256Hashes(inputFile);
return ComputeSHA256TreeHash(chunkSHA256Hashes);
}
/**
* Computes a SHA256 checksum for each 1 MB chunk of the input file. This
* includes the checksum for the last chunk even if it is smaller than 1 MB.
*
* @param file
* A file to compute checksums on
* @return a byte[][] containing the checksums of each 1MB chunk
*/
public static byte[][] GetChunkSHA256Hashes(FileStream file)
{
long numChunks = file.Length / ONE_MB;
if (file.Length % ONE_MB > 0)
{
numChunks++;
}
if (numChunks == 0)
{
return new byte[][] { CalculateSHA256Hash(null, 0) };
}
byte[][] chunkSHA256Hashes = new byte[(int)numChunks][];
try
{
byte[] buff = new byte[ONE_MB];
int bytesRead;
int idx = 0;
while ((bytesRead = file.Read(buff, 0, ONE_MB)) > 0)
{
chunkSHA256Hashes[idx++] = CalculateSHA256Hash(buff, bytesRead);
}
return chunkSHA256Hashes;
}
finally
{
if (file != null)
{
try
{
file.Close();
}
catch (IOException ioe)
{
throw ioe;
}
}
}
}
/**
* Computes the SHA-256 tree hash for the passed array of 1MB chunk
* checksums.
*
* This method uses a pair of arrays to iteratively compute the tree hash
* level by level. Each iteration takes two adjacent elements from the
* previous level source array, computes the SHA-256 hash on their
* concatenated value and places the result in the next level's destination
* array. At the end of an iteration, the destination array becomes the
* source array for the next level.
*
* @param chunkSHA256Hashes
* An array of SHA-256 checksums
* @return A byte[] containing the SHA-256 tree hash for the input chunks
*/
public static byte[] ComputeSHA256TreeHash(byte[][] chunkSHA256Hashes)
{
byte[][] prevLvlHashes = chunkSHA256Hashes;
while (prevLvlHashes.GetLength(0) > 1)
{
int len = prevLvlHashes.GetLength(0) / 2;
if (prevLvlHashes.GetLength(0) % 2 != 0)
{
len++;
}
byte[][] currLvlHashes = new byte[len][];
int j = 0;
for (int i = 0; i < prevLvlHashes.GetLength(0); i = i + 2, j++)
{
// If there are at least two elements remaining
if (prevLvlHashes.GetLength(0) - i > 1)
{
// Calculate a digest of the concatenated nodes
byte[] firstPart = prevLvlHashes[i];
byte[] secondPart = prevLvlHashes[i + 1];
byte[] concatenation = new byte[firstPart.Length + secondPart.Length];
System.Buffer.BlockCopy(firstPart, 0, concatenation, 0, firstPart.Length);
System.Buffer.BlockCopy(secondPart, 0, concatenation, firstPart.Length, secondPart.Length);
currLvlHashes[j] = CalculateSHA256Hash(concatenation, concatenation.Length);
}
else
{ // Take care of remaining odd chunk
currLvlHashes[j] = prevLvlHashes[i];
}
}
prevLvlHashes = currLvlHashes;
}
return prevLvlHashes[0];
}
public static byte[] CalculateSHA256Hash(byte[] inputBytes, int count)
{
SHA256 sha256 = System.Security.Cryptography.SHA256.Create();
byte[] hash = sha256.ComputeHash(inputBytes, 0, count);
return hash;
}
}
}
```
# 下载数据时接收校验和
当您使用启动任务 API（请参阅[启动任务（POST jobs）](api-initiate-job-post.md)）检索档案时，您可以选择性地指定要检索的档案范围。类似地，当您使用获取任务输出 API（请参阅[获取任务输出（GET output）](api-job-output-get.md)）下载您的数据时，您可以选择性地指定要下载的数据范围。这些范围有两个特征，您在检索和下载档案的数据时务必要了解这两个特征。要检索的范围必须与档案*以兆字节对齐*。为了在下载数据时接收校验和值，要检索的范围与要下载的范围必须*以树形哈希对齐*。这两种类型的范围对齐的定义如下：
+ 兆字节对齐-当范围 [*StartByte*, *EndBytes*] 可被 1 MB 整除且*EndBytes*加 1 可被 1 MB 整除或等于指定存档的末尾（存档字节大小减去 1）时 *StartBytes*，则以兆字节 (1024\$11024) 对齐。启动任务 API 中使用的范围（如果指定了范围）必须以兆字节对齐。
+ Tree-hash 对齐-当且仅当在该范围内构建的树形哈希的根等同于整个档案的树形哈希中的节点时，范围 [*StartBytes*，*EndBytes*] 才与档案进行树形哈希对齐。为了接收您下载的数据的校验和值，要检索的范围以及要下载的范围必须以树形哈希对齐。有关范围以及它们与档案树形哈希的关系的示例，请参阅[树形哈希示例：检索以树形哈希对齐的档案范围](#checksum-calculations-upload-archive-with-ranges)。
请注意，以树形哈希对齐的范围也是以兆字节对齐的。但是，以兆字节对齐的范围却不一定是以树形哈希对齐的。
以下案例描述了您在下载档案数据时，会在哪些情况下收到校验和值：
+ 如果您在启动任务请求中未指定要检索的范围，并且在获取任务请求中下载整个档案。
+ 如果您在启动任务请求中未指定要检索的范围，并且在获取任务请求中指定要下载的以树形哈希对齐的范围。
+ 如果您在启动任务请求中指定要检索的以树形哈希对齐的范围，并且在获取任务请求中下载整个范围。
+ 如果您在启动任务请求中指定要检索的以树形哈希对齐的范围，并且在获取任务请求中指定要下载的以树形哈希对齐的范围。
如果您在启动任务请求中指定要检索的范围，而该范围未以树形哈希对齐，则您在获取任务请求中下载数据时，仍然可以获取档案数据，但系统却不会返回校验和值。
## 树形哈希示例：检索以树形哈希对齐的档案范围
假设您的文件库中有一个 6.5 MB 的档案，您要检索该档案的 2 MB。您在启动任务请求中指定 2 MB 范围的方式决定了您在下载数据时是否会收到数据校验和值。下图说明了对于 6.5 MB 档案您可以下载的两个 2 MB 范围。这两个范围均以兆字节对齐，但只有一个范围以树形哈希对齐。
![\[示意图显示检索以树形哈希对齐的档案范围。\]](http://docs.aws.amazon.com/zh_cn/amazonglacier/latest/dev/images/TreeHash-ArchiveWithRanges.png)
## 以树形哈希对齐的范围说明
此部分对构成以树形哈希对齐的范围的内容给出了确切的说明。您在下载档案的一部分并且指定要检索的数据范围以及要从检索的数据下载的范围时，以树形哈希对齐的范围非常重要。如果这两个范围均以树形哈希对齐，则您在下载数据时将收到校验和数据。
当且仅当在范围 [*A*, *B*]之上构建新的树形哈希，且该范围的树形哈希的根相当于整个档案的树形哈希中的一个节点时，范围 [*A*, *B*] 才相对于档案是*以树形哈希对齐的*。您可以看到[树形哈希示例：检索以树形哈希对齐的档案范围](#checksum-calculations-upload-archive-with-ranges)中的图表显示了这一点。在此部分中，我们提供了树形哈希对齐的说明。
可将 [*P*, *Q*) 视为 *N* 兆字节（MB）的档案的范围查询，而 *P* 和 *Q* 是 1 MB 的倍数。请注意，实际包括范围为 [*P* MB, *Q* MB – 1 字节]，但为了简单起见，我们将它显示为 [*P*, *Q*)。基于这些考虑因素得知：
+ 如果 *P* 为奇数，则只有一个可能的以树形哈希对齐的范围即，[*P*, *P* \$1 1 MB)。
+ 如果 *P* 是偶数，*k* 是最大数，其中 *P* 可以写成 2*k* \$1 *X*，则最多有 *k* 个以 *P* 开头的树形哈希对齐的范围。 *X* 是大于 0 的整数。以树形哈希对齐的范围分为以下类别：
+ 对于每个 *i*，其中（0 <= *i* <= *k*）并且 *P* \$1 2*i* < *N*，则 [*P*, *Q* \$1 2*i*) 是以树形哈希对齐的范围。
+ *P* = 0 是 *A* = 2[lgN]\$10 时的特殊情况
# 错误响应
如果发生错误，API 将返回下列异常之一：
| 代码 | 说明 | HTTP 状态代码 | 类型 |
| --- | --- | --- | --- |
| AccessDeniedException | 如果有人尝试访问 AWS Identity and Access Management (IAM) 策略不允许的资源，或者请求 URI 中使用了错误的 AWS 账户 ID，则返回。有关更多信息，请参阅 [适用于 Amazon Glacier 的 Identity and Access Management](security-iam.md)。 | 403 Forbidden | 客户端 |
| BadRequest | 如果无法处理请求，则返回此异常。 | 400 Bad Request | 客户端 |
| ExpiredTokenException | 如果请求中使用的安全令牌已过期，则返回此异常。 | 403 Forbidden | 客户端 |
| InsufficientCapacityException | 如果没有足够的容量处理此加速请求，则返回此代码。此错误仅适用于加速检索，不适用于标准或批量检索。 | 503 Service Unavailable | 服务器 |
| InvalidParameterValueException | 如果错误地指定了请求的参数，则返回此异常。 | 400 Bad Request | 客户端 |
| InvalidSignatureException | 如果请求签名无效，则返回此异常。 | 403 Forbidden | 客户端 |
| LimitExceededException | 如果请求导致超过文件库限制、标签限制或预配置容量限制中的任何一项，则返回此代码。 | 400 Bad Request | 客户端 |
| MissingAuthenticationTokenException | 如果没有为请求找到身份验证数据，则返回此异常。 | 400 Bad Request | 客户端 |
| MissingParameterValueException | 如果请求中缺失必需的标头或参数，则返回此异常。 | 400 Bad Request | 客户端 |
| PolicyEnforcedException | 如果检索作业将超出当前数据策略的检索速率限制，则返回此异常。有关数据检索策略的更多信息，请参阅 [Amazon Glacier 数据检索策略](data-retrieval-policy.md)。 | 400 Bad Request | 客户端 |
| ResourceNotFoundException | 如果指定的资源（例如文件库、上传 ID 或任务 ID）不存在，则返回此异常。 | 404 Not Found | 客户端 |
| RequestTimeoutException | 如果正在上传档案并且 Amazon Glacier（Amazon Glacier）在接收上传时超时，则返回此异常。 | 408 Request Timeout | 客户端 |
| SerializationException | 如果请求正文无效，则返回此异常。如果包括 JSON 有效载荷，则检查其格式是否正确。 | 400 Bad Request | 客户端 |
| ServiceUnavailableException | 如果服务无法完成请求，则返回此异常。 | 500 Internal Server Error | 服务器 |
| ThrottlingException | 如果您需要降低向 Amazon Glacier 发送请求的速率，则返回此异常。 | 400 Bad Request | 客户端 |
| UnrecognizedClientException | 如果访问密钥 ID 或安全令牌无效，则返回此异常。 | 400 Bad Request | 客户端 |
各种 Amazon Glacier 会 APIs 返回相同的异常，但会有不同的异常消息来帮助您解决遇到的特定错误。
Amazon Glacier 会在响应正文中返回错误信息。以下示例显示了某些错误响应。
## 示例 1：具有不存在的任务 ID 的描述任务请求
假设您为不存在的任务发送[描述任务（GET JobID）](api-describe-job-get.md)请求。即，您指定一个不存在的任务 ID。
```
1. GET /-/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVEXAMPLEbadJobID HTTP/1.1
2. Host: glacier.us-west-2.amazonaws.com
3. 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
```
作为响应，Amazon Glacier 返回以下错误响应。
```
HTTP/1.1 404 Not Found
x-amzn-RequestId: AAABaZ9N92Iiyv4N7sru3ABEpSQkuFtmH3NP6aAC51ixfjg
Content-Type: application/json
Content-Length: 185
Date: Wed, 10 Feb 2017 12:00:00 GMT
{
"code": "ResourceNotFoundException",
"message": "The job ID was not found: HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVEXAMPLEbadJobID",
"type": "Client"
}
```
其中：
**Code**
常规异常之一。
*类型*：字符串
**Message**
特定于返回错误的 API 的错误条件一般描述。
*类型*：字符串
**Type**
错误源。该字段可以为以下值之一：`Client`、`Server` 或 `Unknown`。
*类型*：字符串。
请注意前面响应中的以下情况：
+ 对于错误响应，Amazon Glacier 返回状态代码值 `4xx` 和 `5xx`。在此示例中，状态代码为 `404 Not Found`。
+ `Content-Type` 标头值 `application/json` 表示正文中的 JSON
+ 正文中的 JSON 提供了错误信息。
在之前的请求中，假设您指定不存在的文件库，而不是错误的任务 ID。响应会返回不同的消息。
```
HTTP/1.1 404 Not Found
x-amzn-RequestId: AAABBeC9Zw0rp_5D0L8VfB3FA_WlTupqTKAUehMcPhdgni0
Content-Type: application/json
Content-Length: 154
Date: Wed, 10 Feb 2017 12:00:00 GMT
{
"code": "ResourceNotFoundException",
"message": "Vault not found for ARN: arn:aws:glacier:us-west-2:012345678901:vaults/examplevault",
"type": "Client"
}
```
## 示例 2：请求参数具有无效值的列出任务请求
在此示例中，您发送[列出任务（GET jobs）](api-jobs-get.md)请求以检索具有特定 `statuscode` 的文件库任务，而您提供了错误的 `statuscode` 值 `finished`，而不是可接受的值 `InProgress`、`Succeeded` 或 `Failed`。
```
GET /-/vaults/examplevault/jobs?statuscode=finished HTTP/1.1
Host: glacier.us-west-2.amazonaws.com
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
```
Amazon Glacier 返回 `InvalidParameterValueException` 以及相应的消息。
```
HTTP/1.1 400 Bad Request
x-amzn-RequestId: AAABaZ9N92Iiyv4N7sru3ABEpSQkuFtmH3NP6aAC51ixfjg
Content-Type: application/json
Content-Length: 141
Date: Wed, 10 Feb 2017 12:00:00 GMT
{
"code": "InvalidParameterValueException",
"message": "The job status code is not valid: finished",
"type: "Client"
}
```
# 文件库操作
以下是可供在 Amazon Glacier 中使用的文件库操作。
**Topics**
+ [
# 中止文件库锁定（DELETE lock-policy）
](api-AbortVaultLock.md)
+ [
# 向文件库添加标签（POST tags add）
](api-AddTagsToVault.md)
+ [
# 创建文件库（PUT vault）
](api-vault-put.md)
+ [
# 完成文件库锁定（POST lockId）
](api-CompleteVaultLock.md)
+ [
# 删除文件库（DELETE vault）
](api-vault-delete.md)
+ [
# 删除文件库访问策略（DELETE access-policy）
](api-DeleteVaultAccessPolicy.md)
+ [
# 删除文件库通知（DELETE notification-configuration）
](api-vault-notifications-delete.md)
+ [
# 描述文件库（GET vault）
](api-vault-get.md)
+ [
# 获取文件库访问策略（GET access-policy）
](api-GetVaultAccessPolicy.md)
+ [
# 获取文件库锁定（GET lock-policy）
](api-GetVaultLock.md)
+ [
# 获取文件库通知（GET notification-configuration）
](api-vault-notifications-get.md)
+ [
# 启动文件库锁定（POST lock-policy）
](api-InitiateVaultLock.md)
+ [
# 列出文件库的标签（GET tags）
](api-ListTagsForVault.md)
+ [
# 列出文件库（GET vaults）
](api-vaults-get.md)
+ [
# 从文件库删除标签（POST tags remove）
](api-RemoveTagsFromVault.md)
+ [
# 设置文件库访问策略（PUT access-policy）
](api-SetVaultAccessPolicy.md)
+ [
# 设置文件库通知配置（PUT notification-configuration）
](api-vault-notifications-put.md)
# 中止文件库锁定（DELETE lock-policy）
中止文件库锁定
## 描述
如果文件库锁定未处于 `Locked` 状态，则此操作会停止文件库锁定过程。如果在请求此操作时文件库锁定处于 `Locked` 状态，则此操作会返回 `AccessDeniedException` 错误。停止文件库锁定过程会从指定文件库中删除文件库锁定策略。
通过调用[启动文件库锁定（POST lock-policy）](api-InitiateVaultLock.md)，可将文件库锁定置于 `InProgress` 状态。通过调用[完成文件库锁定（POST lockId）](api-CompleteVaultLock.md)，可将文件库锁定置于 `Locked` 状态。您可通过调用[获取文件库锁定（GET lock-policy）](api-GetVaultLock.md)，获取文件库锁定的状态。有关文件库锁定过程的更多信息，请参阅 [Amazon Glacier 文件库锁定](vault-lock.md)。有关文件库锁定策略的更多信息，请参阅[文件库锁定策略](vault-lock-policy.md)。
此操作是幂等的。如果文件库锁定处于 `InProgress` 状态或没有与文件库关联的策略，则您可多次成功地调用此操作。
## 请求
要删除文件库锁定策略，请向文件库的 `DELETE` 子资源的 URI 发送 HTTP `lock-policy` 请求。
### 语法
```
1. DELETE /AccountId/vaults/vaultName/lock-policy HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. x-amz-glacier-version: 2012-06-01
```
**注意**
`AccountId` 值为 AWS 账户 ID。此值必须与用来对请求进行签名的凭证相关联的 AWS 账户 ID 相匹配。您可以指定 AWS 账户 ID，也可以选择指定“`-`”（连字符），在这种情况下，Amazon Glacier 使用与用来对请求进行签名的凭证相关联的 AWS 账户 ID。如果您指定账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
此操作不使用请求参数。
### 请求标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
### 请求正文
此操作没有请求正文。
## 响应
如果成功删除此策略，则 Amazon Glacier 会返回 `HTTP 204 No Content` 响应。
### 语法
```
HTTP/1.1 204 No Content
x-amzn-RequestId: x-amzn-RequestId
Date: Date
```
### 响应标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 响应正文
此操作不返回响应正文。
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
以下示例演示如何停止文件库锁定过程。
### 请求示例
在此示例中，`DELETE` 请求被发送到名为 `lock-policy` 的文件库的 **examplevault** 子资源。
```
1. DELETE /-/vaults/examplevault/lock-policy HTTP/1.1
2. Host: glacier.us-west-2.amazonaws.com
3. x-amz-Date: 20170210T120000Z
4. Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20141123/us-west-2/glacier/aws4_request,SignedHeaders=host;x-amz-date;x-amz-glacier-version,Signature=9257c16da6b25a715ce900a5b45b03da0447acf430195dcb540091b12966f2a2
5. x-amz-glacier-version: 2012-06-01
```
### 响应示例
如果成功删除此策略，则 Amazon Glacier 会返回 `HTTP 204 No Content` 响应，如以下示例中所示。
```
1. HTTP/1.1 204 No Content
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:00:00 GMT
```
## 相关部分
+ [完成文件库锁定（POST lockId）](api-CompleteVaultLock.md)
+ [获取文件库锁定（GET lock-policy）](api-GetVaultLock.md)
+ [启动文件库锁定（POST lock-policy）](api-InitiateVaultLock.md)
## 另请参阅
有关在特定语言的 Amazon SDK 中使用此 API 的更多信息，请参阅以下内容：
+ [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/reference/glacier/abort-vault-lock.html)
# 向文件库添加标签（POST tags add）
向文件库添加标签
此操作会向文件库添加指定的标签。每个标签由一个键和一个值组成。每个文件库可最多有 50 个标签。如果您的请求会导致超出文件库的标签限制，则此操作会引发 `LimitExceededException` 错误。
如果在文件库上的某个指定键的下面已存在一个标签，则将覆盖现有的键值。有关标签的更多信息，请参阅[标记 Amazon Glacier 资源](tagging.md)。
## 请求语法
要向文件库添加标签，请将 HTTP POST 请求发送到标签 URI，如以下语法示例中所示。
```
1. POST /AccountId/vaults/vaultName/tags?operation=add HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. Content-Length: Length
6. x-amz-glacier-version: 2012-06-01
7.
8. {
9. "Tags":
10. {
11. "string": "string",
12. "string": "string"
13. }
14. }
```
**注意**
`AccountId` 值为 AWS 账户 ID。此值必须与用来对请求进行签名的凭证相关联的 AWS 账户 ID 相匹配。您可以指定 AWS 账户 ID，也可以选择指定“`-`”（连字符），在这种情况下，Amazon Glacier 使用与用来对请求进行签名的凭证相关联的 AWS 账户 ID。如果您指定账户 ID，请勿在 ID 中包含任何连字符（-）。
## 请求参数
| 名称 | 描述 | 是否必需 |
| --- | --- | --- |
| operation=add | 带有 `add` 值的单个查询字符串参数 `operation`，用于与 [从文件库删除标签（POST tags remove）](api-RemoveTagsFromVault.md) 进行区分。 | 是 |
### 请求标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
### 请求正文
请求正文中包含以下 JSON 字段。
**标签**
要添加到文件库的标签。每个标签由一个键和一个值组成。该值可为空字符串。
*类型：*字符串到字符串映射
*长度约束：*最小长度为 1。最大长度为 10。
*是否必需*：是
## 响应
如果操作请求成功，则该服务会返回 HTTP `204 No Content` 响应。
### 语法
```
HTTP/1.1 204 No Content
x-amzn-RequestId: x-amzn-RequestId
Date: Date
```
### 响应标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 响应正文
此操作不返回响应正文。
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
### 请求示例
以下示例发送一个带有要添加到文件库的标签的 HTTP POST 请求。
```
1. POST /-/vaults/examplevault/tags?operation=add HTTP/1.1
2. Host: glacier.us-west-2.amazonaws.com
3. x-amz-Date: 20170210T120000Z
4. Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20141123/us-west-2/glacier/aws4_request,SignedHeaders=host;x-amz-date;x-amz-glacier-version,Signature=9257c16da6b25a715ce900a5b45b03da0447acf430195dcb540091b12966f2a2
5. Content-Length: length
6. x-amz-glacier-version: 2012-06-01
7.
8. {
9. "Tags":
10. {
11. "examplekey1": "examplevalue1",
12. "examplekey2": "examplevalue2"
13. }
14. }
```
### 响应示例
如果请求成功，Amazon Glacier 会返回 `HTTP 204 No Content`，如以下示例中所示。
```
1. HTTP/1.1 204 No Content
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:02:00 GMT
```
## 相关部分
+ [列出文件库的标签（GET tags）](api-ListTagsForVault.md)
+ [从文件库删除标签（POST tags remove）](api-RemoveTagsFromVault.md)
## 另请参阅
有关在特定语言的 Amazon SDK 中使用此 API 的更多信息，请参阅以下内容：
+ [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/reference/glacier/add-tags-to-vault.html)
# 创建文件库（PUT vault）
创建文件库
## 描述
此操作会使用指定的名称创建新的文件库。 文件库的名称在 AWS 账户的某个 AWS 区域内必须是唯一的。您最多可以为每个账户创建 1000 个文件库。有关创建更多文件库的信息，请转到 [Amazon Glacier 产品详细信息页](https://aws.amazon.com/glacier)。
为文件库命名时，您必须使用以下准则。
+ 名称长度在 1 和 255 个字符之间。
+ 允许的字符包括 a-z、A-Z、0-9、-（下划线）、\$1（连字符）和 .（半角句点）。
此操作是幂等性的，您可以多次发送相同的请求，但在 Amazon Glacier（Amazon Glacier）第一次创建指定的文件库后，它不会再产生影响。
## 请求
### 语法
要创建文件库，请将 HTTP PUT 请求发送到要创建的文件库的 URI。
```
1. PUT /AccountId/vaults/VaultName HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. Content-Length: Length
6. x-amz-glacier-version: 2012-06-01
```
**注意**
`AccountId` 值为 AWS 账户 ID。此值必须与用来对请求进行签名的凭证相关联的 AWS 账户 ID 相匹配。您可以指定 AWS 账户 ID，也可以选择指定“`-`”（连字符），在这种情况下，Amazon Glacier 使用与用来对请求进行签名的凭证相关联的 AWS 账户 ID。如果您指定账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
此操作不使用请求参数。
### 请求标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
### 请求正文
此操作的请求正文必须为空（0 字节）。
## 响应
### 语法
```
HTTP/1.1 201 Created
x-amzn-RequestId: x-amzn-RequestId
Date: Date
Location: Location
```
### 响应标头
除了所有操作通用的响应标头外，成功的响应中还包括以下响应标头。有关通用响应标头的更多信息，请参阅[通用响应标头](api-common-response-headers.md)。
| 名称 | 描述 |
| --- | --- |
| `Location` | 已创建的文件库的相对 URI 路径。 类型：字符串 |
### 响应正文
此操作不返回响应正文。
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
### 请求示例
以下示例发送 HTTP PUT 请求，以创建名为 `examplevault` 的文件库。
```
1. PUT /-/vaults/examplevault 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. Content-Length: 0
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
```
### 响应示例
Amazon Glacier 创建文件库并在 `Location` 标头中返回文件库的相对 URI 路径。无论请求中指定的是账户 ID 还是连字符（`Location`），账户 ID 始终都会显示在 `-` 标头中。
```
1. HTTP/1.1 201 Created
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:02:00 GMT
4. Location: /111122223333/vaults/examplevault
```
## 相关部分
+ [列出文件库（GET vaults）](api-vaults-get.md)
+ [删除文件库（DELETE vault）](api-vault-delete.md)
+ [适用于 Amazon Glacier 的 Identity and Access Management](security-iam.md)
## 另请参阅
有关在特定语言的 Amazon SDK 中使用此 API 的更多信息，请参阅以下内容：
+ [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/reference/glacier/create-vault.html)
# 完成文件库锁定（POST lockId）
完成文件库锁定
## 描述
此操作通过将文件库锁定的状态从 `InProgress` 状态转换为 `Locked` 状态来完成文件库锁定过程，这会导致文件库锁定策略不可更改。通过调用`InProgress`，可将文件库锁定置于 [启动文件库锁定（POST lock-policy）](api-InitiateVaultLock.md) 状态。您可通过调用[获取文件库锁定（GET lock-policy）](api-GetVaultLock.md)，获取文件库锁定的状态。有关文件库锁定过程的更多信息，请参阅 [Amazon Glacier 文件库锁定](vault-lock.md)。
此操作是幂等的。如果文件库锁定处于 `Locked` 状态而且提供的锁定 ID 与最初用于锁定文件库的锁定 ID 匹配，则此请求始终将会成功。
如果当文件库锁定处于 `Locked` 状态时在请求中传递无效的锁定 ID，则此操作会返回 `AccessDeniedException` 错误。如果当文件库锁定处于 `InProgress` 状态时在请求中传递无效的锁定 ID，则此操作会引发 `InvalidParameter` 错误。
## 请求
要完成文件库锁定过程，请向文件库的 `POST` 子资源的 URI 发送带有有效的锁定 ID 的 HTTP `lock-policy` 请求。
### 语法
```
1. POST /AccountId/vaults/vaultName/lock-policy/lockId HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. Content-Length: Length
6. x-amz-glacier-version: 2012-06-01
```
**注意**
`AccountId` 值为 AWS 账户 ID。此值必须与用来对请求进行签名的凭证相关联的 AWS 账户 ID 相匹配。您可以指定 AWS 账户 ID，也可以选择指定“`-`”（连字符），在这种情况下，Amazon Glacier 使用与用来对请求进行签名的凭证相关联的 AWS 账户 ID。如果您指定账户 ID，请勿在 ID 中包含任何连字符（-）。
`lockId` 值是从 [启动文件库锁定（POST lock-policy）](api-InitiateVaultLock.md) 请求获取的锁定 ID。
### 请求参数
#### 请求标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
#### 请求正文
此操作没有请求正文。
## 响应
如果操作请求成功，则该服务会返回 HTTP `204 No Content` 响应。
### 语法
```
HTTP/1.1 204 No Content
x-amzn-RequestId: x-amzn-RequestId
Date: Date
```
### 响应标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 响应正文
此操作不返回响应正文。
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
### 请求示例
以下示例发送带有锁定 ID 的 HTTP POST 请求以完成文件库锁定过程。
```
1. POST /-/vaults/examplevault/lock-policy/AE863rKkWZU53SLW5be4DUcW HTTP/1.1
2. Host: glacier.us-west-2.amazonaws.com
3. x-amz-Date: 20170210T120000Z
4. Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20141123/us-west-2/glacier/aws4_request,SignedHeaders=host;x-amz-date;x-amz-glacier-version,Signature=9257c16da6b25a715ce900a5b45b03da0447acf430195dcb540091b12966f2a2
5. Content-Length: length
6. x-amz-glacier-version: 2012-06-01
```
### 响应示例
如果请求成功，Amazon Glacier（Amazon Glacier）将返回 `HTTP 204 No Content` 响应，如以下示例中所示。
```
1. HTTP/1.1 204 No Content
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:02:00 GMT
```
## 相关部分
+ [中止文件库锁定（DELETE lock-policy）](api-AbortVaultLock.md)
+ [获取文件库锁定（GET lock-policy）](api-GetVaultLock.md)
+ [启动文件库锁定（POST lock-policy）](api-InitiateVaultLock.md)
## 另请参阅
有关在特定语言的 Amazon SDK 中使用此 API 的更多信息，请参阅以下内容：
+ [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/reference/glacier/complete-vault-lock.html)
# 删除文件库（DELETE vault）
删除文件库
## 描述
此操作会删除文件库。只有在上次清单盘点时文件库中没有任何档案，并且自上次清单盘点以来文件库没有执行过任何写入操作，Amazon Glacier（Amazon Glacier）才会删除文件库。如果不满足其中的任一条件，文件库删除操作会失败（即，不会删除文件库），并且 Amazon Glacier 返回错误。
您可以使用[描述文件库（GET vault）](api-vault-get.md)操作，它会提供文件库信息，包括文件库中的档案数；但是，该信息是基于 Amazon Glacier 上次生成的文件库清单的。
此操作是幂等的。
**注意**
当您删除文件库时，已附加到文件库的文件库访问策略也会被删除。有关文件库访问策略的更多信息，请参阅[文件库访问策略](vault-access-policy.md)。
## 请求
要删除文件库，请向文件库资源 URI 发送 `DELETE` 请求。
### 语法
```
1. DELETE /AccountId/vaults/VaultName HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. x-amz-glacier-version: 2012-06-01
```
**注意**
`AccountId` 值是拥有文件库的账户的 AWS 账户 ID。您可以指定 AWS 账户 ID，也可以选择指定“`-`”（连字符），在这种情况下，Amazon Glacier 使用与用来对请求进行签名的凭证相关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
此操作不使用请求参数。
### 请求标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
### 请求正文
此操作没有请求正文。
## 响应
### 语法
```
HTTP/1.1 204 No Content
x-amzn-RequestId: x-amzn-RequestId
Date: Date
```
### 响应标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 响应正文
此操作不返回响应正文。
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
### 请求示例
以下示例会删除名为 `examplevault` 的文件库。该请求示例是针对要删除的资源（文件库）的 URI 的 `DELETE` 请求。
```
1. DELETE /-/vaults/examplevault 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
```
### 响应示例
```
1. HTTP/1.1 204 No Content
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:02:00 GMT
```
## 相关部分
+ [创建文件库（PUT vault）](api-vault-put.md)
+ [列出文件库（GET vaults）](api-vaults-get.md)
+ [启动任务（POST jobs）](api-initiate-job-post.md)
+ [适用于 Amazon Glacier 的 Identity and Access Management](security-iam.md)
## 另请参阅
有关在特定语言的 Amazon SDK 中使用此 API 的更多信息，请参阅以下内容：
+ [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/reference/glacier/delete-vault.html)
# 删除文件库访问策略（DELETE access-policy）
删除文件库访问策略
## 说明
此操作将删除与指定文件库关联的访问策略。该操作最终是一致的 – 也就是说，Amazon Glacier（Amazon Glacier）可能需要花一些时间来完全删除访问策略，并且在您发送删除请求后，短时间内可能仍将看到该策略的效果。
此操作是幂等的。您可以多次调用删除操作，即使没有与文件库关联的策略。有关文件库访问策略的更多信息，请参阅[文件库访问策略](vault-access-policy.md)。
## 请求
要删除当前文件库访问策略，请向文件库的 `access-policy` 子资源的 URI 发送一个 HTTP `DELETE` 请求。
### 语法
```
1. DELETE /AccountId/vaults/vaultName/access-policy HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. x-amz-glacier-version: 2012-06-01
```
**注意**
该`AccountId`值是拥有文件库的账户的 AWS 账户 ID。您可以指定一个 AWS 账户 ID，也可以选择指定一个 '`-`'（连字符），在这种情况下，Amazon Glacier 使用与用于签署请求的凭证关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
此操作不使用请求参数。
### 请求标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
### 请求正文
此操作没有请求正文。
## 响应
作为响应，Amazon Glacier 会在成功删除策略时返回 `204 No Content`。
### 语法
```
HTTP/1.1 204 No Content
x-amzn-RequestId: x-amzn-RequestId
Date: Date
```
### 响应标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 响应正文
此操作不返回响应正文。
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
以下示例演示如何删除文件库访问策略。
### 请求示例
在此示例中，`DELETE` 请求被发送到名为 `access-policy` 的文件库的 **examplevault** 子资源。
```
1. DELETE /-/vaults/examplevault/access-policy HTTP/1.1
2. Host: glacier.us-west-2.amazonaws.com
3. x-amz-Date: 20170210T120000Z
4. Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20141123/us-west-2/glacier/aws4_request,SignedHeaders=host;x-amz-date;x-amz-glacier-version,Signature=9257c16da6b25a715ce900a5b45b03da0447acf430195dcb540091b12966f2a2
5. x-amz-glacier-version: 2012-06-01
```
### 响应示例
作为响应，如果已成功删除策略，则 Amazon Glacier 将返回 `204 No Content`，如以下示例所示。
```
1. HTTP/1.1 204 No Content
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:00:00 GMT
```
## 相关部分
+ [获取文件库访问策略（GET access-policy）](api-GetVaultAccessPolicy.md)
+ [设置文件库访问策略（PUT access-policy）](api-SetVaultAccessPolicy.md)
## 另请参阅
有关在特定语言的 Amazon 中使用此 API 的更多信息 SDKs，请参阅以下内容：
+ [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/reference/glacier/delete-vault-access-policy.html)
# 删除文件库通知（DELETE notification-configuration）
删除文件库通知
## 说明
此操作会删除为文件库 [设置文件库通知配置（PUT notification-configuration）](api-vault-notifications-put.md) 设置的通知配置。该操作最终是一致的即，Amazon Glacier（Amazon Glacier）可能需要花一些时间来完全禁用通知，并且您在发送删除请求后的短时间内，仍可能会收到一些通知。
## 请求
要删除文件库的通知配置，请向文件库的 `DELETE` 子资源发送 `notification-configuration` 请求。
### 语法
```
1. DELETE /AccountId/vaults/VaultName/notification-configuration HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. x-amz-glacier-version: 2012-06-01
```
**注意**
该`AccountId`值是拥有文件库的账户的 AWS 账户 ID。您可以指定一个 AWS 账户 ID，也可以选择指定一个 '`-`'（连字符），在这种情况下，Amazon Glacier 使用与用于签署请求的凭证关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
此操作不使用请求参数。
### 请求标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
### 请求正文
此操作没有请求正文。
## 响应
### 语法
```
HTTP/1.1 204 No Content
x-amzn-RequestId: x-amzn-RequestId
Date: Date
```
### 响应标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 响应正文
此操作不返回响应正文。
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
以下示例展示了如何删除文件库的通知配置。
### 请求示例
在此示例中，`DELETE` 请求被发送到名为 `notification-configuration` 的文件库的 `examplevault` 子资源。
```
1. DELETE /111122223333/vaults/examplevault/notification-configuration 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
```
### 响应示例
```
1. HTTP/1.1 204 No Content
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:00:00 GMT
```
## 相关部分
+ [获取文件库通知（GET notification-configuration）](api-vault-notifications-get.md)
+ [设置文件库通知配置（PUT notification-configuration）](api-vault-notifications-put.md)
+ [适用于 Amazon Glacier 的 Identity and Access Management](security-iam.md)
## 另请参阅
有关在特定语言的 Amazon 中使用此 API 的更多信息 SDKs，请参阅以下内容：
+ [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/reference/glacier/delete-vault-notifications.html)
# 描述文件库（GET vault）
描述文件库
## 描述
此操作会返回有关文件库的信息，包括文件库的 Amazon 资源名称（ARN）、文件库的创建日期、文件库中包含的档案数，以及文件库中所有档案的总大小。档案数量及其总大小截至 Amazon Glacier（Amazon Glacier）上次生成的文件库清单（参阅[在 Amazon Glacier 中处理文件库](working-with-vaults.md)）。Amazon Glacier 大约每天都会生成文件库清单。这意味着，如果您在文件库中添加档案或者从文件库中删除档案，然后立即发送描述文件库请求，则响应可能不会反映这些更改。
## 请求
要获取有关文件库的信息，请向特定文件库资源的 URI 发送 `GET` 请求。
### 语法
```
1. GET /AccountId/vaults/VaultName HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. x-amz-glacier-version: 2012-06-01
```
**注意**
`AccountId` 值是拥有文件库的账户的 AWS 账户 ID。您可以指定 AWS 账户 ID，也可以选择指定“`-`”（连字符），在这种情况下，Amazon Glacier 使用与用来对请求进行签名的凭证相关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
此操作不使用请求参数。
### 请求标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
### 请求正文
此操作没有请求正文。
## 响应
### 语法
```
HTTP/1.1 200 OK
x-amzn-RequestId: x-amzn-RequestId
Date: Date
Content-Type: application/json
Content-Length: Length
{
"CreationDate" : String,
"LastInventoryDate" : String,
"NumberOfArchives" : Number,
"SizeInBytes" : Number,
"VaultARN" : String,
"VaultName" : String
}
```
### 响应标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 响应正文
响应正文包含以下 JSON 字段。
**CreationDate**
创建文件库的 UTC 日期。
*类型*：以 ISO 8601 日期格式表示的字符串，例如 `2013-03-20T17:03:43.221Z`。
**LastInventoryDate**
Amazon Glacier 完成上次文件库清单盘点的 UTC 日期。有关启动文件库清单的信息，请参阅[启动任务（POST jobs）](api-initiate-job-post.md)。
*类型*：以 ISO 8601 日期格式表示的字符串，例如 `2013-03-20T17:03:43.221Z`。
**NumberOfArchives**
上次文件库库存盘点时，文件库中的档案数。如果文件库中尚未运行清单操作（例如，您刚刚创建了文件库），则此字段将返回 null。
*类型*：数字
**SizeInBytes**
截止到上次编制清单日期，文件库中的档案总大小（以字节为单位），包括每个档案所具有的任何开销。如果文件库中尚未运行清单操作（例如，您刚刚创建了文件库），则此字段将返回 `null`。
*类型*：数字
**VaultARN**
文件库的 Amazon 资源名称（ARN）。
*类型*：字符串
**VaultName**
在创建时间指定的文件库名称。文件库名称也包括在文件库的 ARN 中。
*类型*：字符串
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
### 请求示例
以下示例展示了如何获取有关名为 `examplevault` 的文件库的信息。
```
GET /-/vaults/examplevault 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
```
### 响应示例
```
1. HTTP/1.1 200 OK
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:02:00 GMT
4. Content-Type: application/json
5. Content-Length: 260
6.
7. {
8. "CreationDate" : "2012-02-20T17:01:45.198Z",
9. "LastInventoryDate" : "2012-03-20T17:03:43.221Z",
10. "NumberOfArchives" : 192,
11. "SizeInBytes" : 78088912,
12. "VaultARN" : "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault",
13. "VaultName" : "examplevault"
14. }
```
## 相关部分
+ [创建文件库（PUT vault）](api-vault-put.md)
+ [列出文件库（GET vaults）](api-vaults-get.md)
+ [删除文件库（DELETE vault）](api-vault-delete.md)
+ [启动任务（POST jobs）](api-initiate-job-post.md)
+ [适用于 Amazon Glacier 的 Identity and Access Management](security-iam.md)
## 另请参阅
有关在特定语言的 Amazon SDK 中使用此 API 的更多信息，请参阅以下内容：
+ [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/reference/glacier/describe-vault.html)
# 获取文件库访问策略（GET access-policy）
获取文件库访问策略
## 说明
此操作将检索文件库上设置的 `access-policy` 子资源有关设置此子资源的更多信息，请参阅[设置文件库访问策略（PUT access-policy）](api-SetVaultAccessPolicy.md)。如果未在文件库上设置访问策略，该操作将返回 `404 Not found` 错误。有关文件库访问策略的更多信息，请参阅[文件库访问策略](vault-access-policy.md)。
## 请求
要返回当前的文件库访问策略，请向文件库的 `GET` 子资源的 URI 发送一个 HTTP `access-policy` 请求。
### 语法
```
1. GET /AccountId/vaults/vaultName/access-policy HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. x-amz-glacier-version: 2012-06-01
```
**注意**
该`AccountId`值是拥有文件库的账户的 AWS 账户 ID。您可以指定一个 AWS 账户 ID，也可以选择指定一个 '`-`'（连字符），在这种情况下，Amazon Glacier 使用与用于签署请求的凭证关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
此操作不使用请求参数。
### 请求标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
### 请求正文
此操作没有请求正文。
## 响应
作为响应，Amazon Glacier（Amazon Glacier）将在响应正文中以 JSON 格式返回文件库访问策略。
### 语法
```
HTTP/1.1 200 OK
x-amzn-RequestId: x-amzn-RequestId
Date: Date
Content-Type: application/json
Content-Length: length
{
"Policy": "string"
}
```
### 响应标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 响应正文
响应正文包含以下 JSON 字段。
**Policy**
以 JSON 字符串形式表示的文件库访问策略（使用“\$1”作为转义符）。
类型：字符串
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
以下示例演示如何获取文件库访问策略。
### 请求示例
在此示例中，`GET` 请求会发送到文件库的 `access-policy` 子资源的 URI。
```
1. GET /-/vaults/examplevault/access-policy 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
```
### 响应示例
如果请求成功，Amazon Glacier 将在响应正文中以 JSON 字符串形式返回文件库访问策略。返回的 JSON 字符串使用“\$1”作为转义符，如[设置文件库访问策略（PUT access-policy）](api-SetVaultAccessPolicy.md)示例中所示。但为了便于阅读，以下示例显示了不带转义符的返回的 JSON 字符串。
```
1. HTTP/1.1 200 OK
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:00:00 GMT
4. Content-Type: application/json
5. Content-Length: length
6.
7. {
8. "Policy": "
9. {
10. "Version": "2012-10-17",
11. "Statement": [
12. {
13. "Sid": "allow-time-based-deletes",
14. "Principal": {
15. "AWS": "999999999999"
16. },
17. "Effect": "Allow",
18. "Action": "glacier:Delete*",
19. "Resource": [
20. "arn:aws:glacier:us-west-2:999999999999:vaults/examplevault"
21. ],
22. "Condition": {
23. "DateGreaterThan": {
24. "aws:CurrentTime": "2018-12-31T00:00:00Z"
25. }
26. }
27. }
28. ]
29. }
30. "
31. }
```
## 相关部分
+ [删除文件库访问策略（DELETE access-policy）](api-DeleteVaultAccessPolicy.md)
+ [设置文件库访问策略（PUT access-policy）](api-SetVaultAccessPolicy.md)
## 另请参阅
有关在特定语言的 Amazon 中使用此 API 的更多信息 SDKs，请参阅以下内容：
+ [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/reference/glacier/get-vault-access-policy.html)
# 获取文件库锁定（GET lock-policy）
获取文件库锁定
## 说明
此操作会从指定文件库上设置的 `lock-policy` 子资源中检索以下属性：
+ 在文件库上设置的文件库锁定策略。
+ 文件库锁定的状态（`InProgess` 或 `Locked`）。
+ 当锁定 ID 到期时。锁定 ID 用于完成文件库锁定过程。
+ 当文件库锁定启动并进入 `InProgress` 状态时。
通过调用`InProgress`，可将文件库锁定置于 [启动文件库锁定（POST lock-policy）](api-InitiateVaultLock.md) 状态。通过调用`Locked`，可将文件库锁定置于 [完成文件库锁定（POST lockId）](api-CompleteVaultLock.md) 状态。您可通过调用[中止文件库锁定（DELETE lock-policy）](api-AbortVaultLock.md)，停止文件库锁定过程。有关文件库锁定过程的更多信息，请参阅 [Amazon Glacier 文件库锁定](vault-lock.md)。
如果未在文件库上设置文件库锁定策略，则该操作会返回 `404 Not found` 错误。有关文件库锁定策略的更多信息，请参阅[文件库锁定策略](vault-lock-policy.md)。
## 请求
要返回当前的文件库锁定策略和其他属性，请向文件库的 `GET` 子资源的 URI 发送一个 HTTP `lock-policy` 请求，如以下语法示例中所示。
### 语法
```
1. GET /AccountId/vaults/vaultName/lock-policy HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. x-amz-glacier-version: 2012-06-01
```
**注意**
该`AccountId`值是拥有文件库的账户的 AWS 账户 ID。您可以指定一个 AWS 账户 ID，也可以选择指定一个 '`-`'（连字符），在这种情况下，Amazon Glacier 使用与用于签署请求的凭证关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
此操作不使用请求参数。
### 请求标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
### 请求正文
此操作没有请求正文。
## 响应
作为响应，Amazon Glacier（Amazon Glacier）将在响应正文中以 JSON 格式返回文件库访问策略。
### 语法
```
HTTP/1.1 200 OK
x-amzn-RequestId: x-amzn-RequestId
Date: Date
Content-Type: application/json
Content-Length: length
{
"Policy": "string",
"State": "string",
"ExpirationDate": "string",
"CreationDate":"string"
}
```
### 响应标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 响应正文
响应正文包含以下 JSON 字段。
**Policy**
以 JSON 字符串形式表示的文件库锁定策略（使用“\$1”作为转义符）。
类型：字符串
**State**
文件库锁定的状态。
类型：字符串
有效值：`InProgress``|Locked`
**ExpirationDate**
锁定 ID 到期的 UTC 日期和时间。如果文件库锁定处于 `null` 状态，则此值可为 `Locked`。
*类型*：以 ISO 8601 日期格式表示的字符串，例如 `2013-03-20T17:03:43.221Z`。
**CreationDate**
将文件库锁定置于 `InProgress` 状态的 UTC 日期和时间。
*类型*：以 ISO 8601 日期格式表示的字符串，例如 `2013-03-20T17:03:43.221Z`。
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
以下示例演示如何获取文件库锁定策略。
### 请求示例
在此示例中，`GET` 请求会发送到文件库的 `lock-policy` 子资源的 URI。
```
1. GET /-/vaults/examplevault/lock-policy 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
```
### 响应示例
如果请求成功，Amazon Glacier 将在响应正文中以 JSON 字符串形式返回文件库访问策略。返回的 JSON 字符串使用“\$1”作为转义符，如[启动文件库锁定（POST lock-policy）](api-InitiateVaultLock.md)请求示例中所示。但为了便于阅读，以下示例显示了不带转义符的返回的 JSON 字符串。
```
1. HTTP/1.1 200 OK
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:00:00 GMT
4. Content-Type: application/json
5. Content-Length: length
6.
7. {
8. "Policy": "
9. {
10. "Version": "2012-10-17",
11. "Statement": [
12. {
13. "Sid": "Define-vault-lock",
14. "Principal": {
15. "AWS": "arn:aws:iam::999999999999:root"
16. },
17. "Effect": "Deny",
18. "Action": "glacier:DeleteArchive",
19. "Resource": [
20. "arn:aws:glacier:us-west-2:999999999999:vaults/examplevault"
21. ],
22. "Condition": {
23. "NumericLessThanEquals": {
24. "glacier:ArchiveAgeInDays": "365"
25. }
26. }
27. }
28. ]
29. }
30. ",
31. "State": "InProgress",
32. "ExpirationDate": "exampledate",
33. "CreationDate": "exampledate"
34. }
```
## 相关部分
+ [中止文件库锁定（DELETE lock-policy）](api-AbortVaultLock.md)
+ [完成文件库锁定（POST lockId）](api-CompleteVaultLock.md)
+ [启动文件库锁定（POST lock-policy）](api-InitiateVaultLock.md)
## 另请参阅
有关在特定语言的 Amazon 中使用此 API 的更多信息 SDKs，请参阅以下内容：
+ [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/reference/glacier/get-vault-lock.html)
# 获取文件库通知（GET notification-configuration）
获取文件库通知
## 说明
此操作会检索文件库中设置的 `notification-configuration` 子资源（请参阅[设置文件库通知配置（PUT notification-configuration）](api-vault-notifications-put.md)）。如果未设置文件库的通知配置，则该操作会返回 `404 Not Found` 错误。有关文件库通知的更多信息，请参阅[在 Amazon Glacier 中配置文件库通知](configuring-notifications.md)。
## 请求
要检索通知配置信息，请向文件库的 `GET` 子资源的 URI 发送 `notification-configuration` 请求。
### 语法
```
1. GET /AccountId/vaults/VaultName/notification-configuration HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. x-amz-glacier-version: 2012-06-01
```
**注意**
该`AccountId`值是拥有文件库的账户的 AWS 账户 ID。您可以指定一个 AWS 账户 ID，也可以选择指定一个 '`-`'（连字符），在这种情况下，Amazon Glacier 使用与用于签署请求的凭证关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
此操作不使用请求参数。
### 请求标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
### 请求正文
此操作没有请求正文。
## 响应
### 语法
```
HTTP/1.1 200 OK
x-amzn-RequestId: x-amzn-RequestId
Date: Date
Content-Type: application/json
Content-Length: length
{
"Events": [
String,
...
],
"SNSTopic": String
}
```
### 响应标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 响应正文
响应正文包含以下 JSON 字段。
**Events**
Amazon Glacier（Amazon Glacier）将向指定 Amazon SNS 主题发送通知的一个或多个事件的列表。有关您可以为其配置文件库以发布通知的文件库事件的信息，请参阅[设置文件库通知配置（PUT notification-configuration）](api-vault-notifications-put.md)。
*类型*：数组
**SNSTopic**
Amazon Simple Notification Service（Amazon SNS）主题的 Amazon 资源名称（ARN）。有关更多信息，请参阅《Amazon Simple Notification Service 入门指南**》中的 [Amazon SNS 入门](https://docs.aws.amazon.com/sns/latest/gsg/Welcome.html)。
*类型*：字符串
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
以下示例展示了如何检索文件库的通知配置。
### 请求示例
在此示例中，`GET` 请求会发送到文件库的 `notification-configuration` 子资源。
```
1. GET /-/vaults/examplevault/notification-configuration 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
```
### 响应示例
成功的响应会在响应正文中以 JSON 格式显示审核记录配置文档。在此示例中，该配置显示了两个事件（`ArchiveRetrievalCompleted` 和 `InventoryRetrievalCompleted`）的通知会发送到 Amazon SNS 主题 `arn:aws:sns:us-west-2:012345678901:mytopic`。
```
1. HTTP/1.1 200 OK
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:00:00 GMT
4. Content-Type: application/json
5. Content-Length: 150
6.
7. {
8. "Events": [
9. "ArchiveRetrievalCompleted",
10. "InventoryRetrievalCompleted"
11. ],
12. "SNSTopic": "arn:aws:sns:us-west-2:012345678901:mytopic"
13. }
```
## 相关部分
+ [删除文件库通知（DELETE notification-configuration）](api-vault-notifications-delete.md)
+ [设置文件库通知配置（PUT notification-configuration）](api-vault-notifications-put.md)
+ [适用于 Amazon Glacier 的 Identity and Access Management](security-iam.md)
## 另请参阅
有关在特定语言的 Amazon 中使用此 API 的更多信息 SDKs，请参阅以下内容：
+ [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/reference/glacier/get-vault-notifications.html)
# 启动文件库锁定（POST lock-policy）
启动文件库锁定
## 描述
此操作通过执行以下操作启动文件库锁定过程：
+ 在指定文件库上安装文件库锁定策略。
+ 将文件库锁定的锁定状态设置为 `InProgress`。
+ 返回一个用于完成文件库锁定过程的锁定 ID。
您可为每个文件库设置一个文件库锁定策略，而且此策略大小最多为 20 KB。有关文件库锁定策略的更多信息，请参阅[文件库锁定策略](vault-lock-policy.md)。
您必须在文件库锁定进入 `InProgress` 状态后的 24 个小时内完成文件库锁定过程。在 24 个小时的窗口结束之后，锁定 ID 将会到期，文件库将自动退出 `InProgress` 状态，并将从文件库中删除文件库锁定策略。您可调用[完成文件库锁定（POST lockId）](api-CompleteVaultLock.md)，通过将文件库锁定的状态设置为 `Locked` 来完成文件库锁定过程。
**注意**
在文件库锁定处于 `Locked` 状态后，您不能为文件库启动新的文件库锁定。
您可通过调用[中止文件库锁定（DELETE lock-policy）](api-AbortVaultLock.md)，停止文件库锁定过程。您可通过调用[获取文件库锁定（GET lock-policy）](api-GetVaultLock.md)，获取文件库锁定的状态。有关文件库锁定过程的更多信息，请参阅 [Amazon Glacier 文件库锁定](vault-lock.md)。
如果在文件库锁定处于 `InProgress` 状态时调用此操作，则此操作会返回 `AccessDeniedException` 错误。当文件库锁定处于 `InProgress` 状态时，您必须先调用[中止文件库锁定（DELETE lock-policy）](api-AbortVaultLock.md)，然后才可以启动新的文件库锁定策略。
## 请求
要启动文件库锁定过程，请向文件库的 `POST` 子资源的 URI 发送 HTTP `lock-policy` 请求，如以下语法示例中所示。
### 语法
```
1. POST /AccountId/vaults/vaultName/lock-policy HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. Content-Length: Length
6. x-amz-glacier-version: 2012-06-01
7.
8. {
9. "Policy": "string"
10. }
```
**注意**
`AccountId` 值为 AWS 账户 ID。此值必须与用来对请求进行签名的凭证相关联的 AWS 账户 ID 相匹配。您可以指定 AWS 账户 ID，也可以选择指定“`-`”（连字符），在这种情况下，Amazon Glacier 使用与用来对请求进行签名的凭证相关联的 AWS 账户 ID。如果您指定账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
此操作不使用请求参数。
### 请求标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
### 请求正文
请求正文中包含以下 JSON 字段。
**Policy**
以 JSON 字符串形式表示的文件库锁定策略（使用“\$1”作为转义符）。
类型：字符串
是否必需：是
## 响应
如果该策略被接受，Amazon Glacier（Amazon Glacier）将返回 `HTTP 201 Created` 响应。
### 语法
```
HTTP/1.1 201 Created
x-amzn-RequestId: x-amzn-RequestId
Date: Date
x-amz-lock-id: lockId
```
### 响应标头
除了所有操作通用的响应标头外，成功的响应中还包括以下响应标头。有关通用响应标头的更多信息，请参阅[通用响应标头](api-common-response-headers.md)。
| 名称 | 描述 |
| --- | --- |
| x-amz-lock-id | 用于完成文件库锁定过程的锁定 ID。 类型：字符串 |
### 响应正文
此操作不返回响应正文。
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
### 请求示例
以下示例将向文件库的 `PUT` 子资源的 URI 发送 HTTP `lock-policy` 请求。`Policy` JSON 字符串使用“\$1”作为转义符。
```
1. PUT /-/vaults/examplevault/lock-policy HTTP/1.1
2. Host: glacier.us-west-2.amazonaws.com
3. x-amz-Date: 20170210T120000Z
4. Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20141123/us-west-2/glacier/aws4_request,SignedHeaders=host;x-amz-date;x-amz-glacier-version,Signature=9257c16da6b25a715ce900a5b45b03da0447acf430195dcb540091b12966f2a2
5. Content-Length: length
6. x-amz-glacier-version: 2012-06-01
7.
8. {"Policy":"{\"Version\":\"2012-10-17\", \"Statement\":[{\"Sid\":\"Define-vault-lock\",\"Effect\":\"Deny\",\"Principal\":{\"AWS\":\"arn:aws:iam::999999999999:root\"},\"Action\":\"glacier:DeleteArchive\",\"Resource\":\"arn:aws:glacier:us-west-2:999999999999:vaults/examplevault\",\"Condition\":{\"NumericLessThanEquals\":{\"glacier:ArchiveAgeinDays\":\"365\"}}}]}"}
```
### 响应示例
如果请求成功，则 Amazon Glacier 会返回 `HTTP 201 Created` 响应，如以下示例中所示。
```
1. HTTP/1.1 201 Created
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:02:00 GMT
4. x-amz-lock-id: AE863rKkWZU53SLW5be4DUcW
```
## 相关部分
+ [中止文件库锁定（DELETE lock-policy）](api-AbortVaultLock.md)
+ [完成文件库锁定（POST lockId）](api-CompleteVaultLock.md)
+ [获取文件库锁定（GET lock-policy）](api-GetVaultLock.md)
## 另请参阅
有关在特定语言的 Amazon SDK 中使用此 API 的更多信息，请参阅以下内容：
+ [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/reference/glacier/initiate-vault-lock.html)
# 列出文件库的标签（GET tags）
列出文件库的标签
此操作会列出已添加到文件库的所有标签。如果没有标签，则此操作会返回空映射。有关标签的更多信息，请参阅[标记 Amazon Glacier 资源](tagging.md)。
## 请求语法
要列出文件库的标签，请将 HTTP GET 请求发送到标签 URI，如以下语法示例中所示。
```
1. GET /AccountId/vaults/vaultName/tags HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. x-amz-glacier-version: 2012-06-01
```
**注意**
`AccountId` 值为 AWS 账户 ID。此值必须与用来对请求进行签名的凭证相关联的 AWS 账户 ID 相匹配。您可以指定 AWS 账户 ID，也可以选择指定“`-`”（连字符），在这种情况下，Amazon Glacier 使用与用来对请求进行签名的凭证相关联的 AWS 账户 ID。如果您指定账户 ID，请勿在 ID 中包含任何连字符（-）。
## 请求参数
此操作不使用请求参数。
## 请求标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
## 请求正文
此操作没有请求正文。
## 响应
如果此操作成功，则该服务将会发送回 HTTP `200 OK` 响应。
### 响应语法
```
HTTP/1.1 200 OK
x-amzn-RequestId: x-amzn-RequestId
Date: Date
Content-Type: application/json
Content-Length: Length
{
"Tags":
{
"string" : "string",
"string" : "string"
}
}
```
### 响应标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 响应正文
响应正文包含以下 JSON 字段。
**Tags**
已添加到文件库的标签。每个标签由一个键和一个值组成。
*类型*：字符串到字符串映射
*是否必需*：是
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
### 示例：列出文件库的标签
以下示例列出了文件库的标签。
#### 请求示例
在此示例中，将发送一个 GET 请求以从指定文件库中检索标签的列表。
```
1. GET /-/vaults/examplevault/tags 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
```
#### 响应示例
如果请求成功，则 Amazon Glacier（Amazon Glacier）会返回带有一个标签列表的 `HTTP 200 OK`，如以下示例中所示。
```
1. HTTP/1.1 200 OK
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:02:00 GMT
4. Content-Type: application/json
5. Content-Length: length
6.
7. {
8. "Tags",
9. {
10. "examplekey1": "examplevalue1",
11. "examplekey2": "examplevalue2"
12. }
13. }
```
## 相关部分
+ [向文件库添加标签（POST tags add）](api-AddTagsToVault.md)
+ [从文件库删除标签（POST tags remove）](api-RemoveTagsFromVault.md)
## 另请参阅
有关在特定语言的 Amazon SDK 中使用此 API 的更多信息，请参阅以下内容：
+ [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/reference/glacier/list-tags-for-vault.html)
# 列出文件库（GET vaults）
列出文件库
## 描述
此操作会列出调用用户的账户拥有的所有文件库。响应中返回的列表按文件库名称的 ASCII 顺序排序。
默认情况下，每次请求时此操作最多返回 10 个项目。如果有更多文件库要列出，则响应正文中的 `marker` 字段会包含文件库的 Amazon 资源名称（ARN），新的列出文件库请求会从该名称处继续列表；否则，`marker` 字段为 `null`。在下一个列出文件库请求中，您可以将 `marker` 参数设置为 Amazon Glacier（Amazon Glacier）为上一个列出文件库请求所回复的值。您也可以通过在请求中指定 `limit` 参数来限制响应中返回的文件库数。
## 请求
要获取文件库列表，您需要向 *vaults* 资源发送 `GET` 请求。
### 语法
```
1. GET /AccountId/vaults HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. x-amz-glacier-version: 2012-06-01
```
**注意**
`AccountId` 值为 AWS 账户 ID。此值必须与用来对请求进行签名的凭证相关联的 AWS 账户 ID 相匹配。您可以指定 AWS 账户 ID，也可以选择指定“`-`”（连字符），在这种情况下，Amazon Glacier 使用与用来对请求进行签名的凭证相关联的 AWS 账户 ID。如果您指定账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
此操作接受以下请求参数。
| 名称 | 描述 | 是否必需 |
| --- | --- | --- |
| limit | 指定要返回的文件库最大数目。默认限制为 10。返回的文件库数可能少于指定的限制值，但永远不会超过限制值。 类型：字符串 约束：最小整数值为 1。最大整数值为 10。 | 否 |
| marker | 用于分页的字符串。`marker` 指定应从其开始列出文件库的文件库 ARN。（`marker` 指定的文件库不包括在返回的列表中。） 从之前的列出文件库响应获取 `marker` 值。只有在您要继续对之前的列出文件库请求中开始的结果进行分页，您才需要包括 `marker`。如果为标记指定空值（""），则系统会返回从第一个文件库开始的文件库列表。 类型：字符串 约束：无 | 否 |
### 请求标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
### 请求正文
此操作没有请求正文。
## 响应
### 语法
```
HTTP/1.1 200 OK
x-amzn-RequestId: x-amzn-RequestId
Date: Date
Content-Type: application/json
Content-Length: Length
{
"Marker": String
"VaultList": [
{
"CreationDate": String,
"LastInventoryDate": String,
"NumberOfArchives": Number,
"SizeInBytes": Number,
"VaultARN": String,
"VaultName": String
},
...
]
}
```
### 响应标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 响应正文
响应正文包含以下 JSON 字段。
**CreationDate**
以协调世界时（UTC）来表示的文件库创建日期。
*类型*：字符串。以 ISO 8601 日期格式表示的字符串，例如 `2013-03-20T17:03:43.221Z`。
**LastInventoryDate**
以协调世界时（UTC）来表示的上次文件库库存盘点日期。如果文件库中尚未运行清单操作（例如，您刚刚创建了文件库），则此字段可能为空。有关启动文件库清单的信息，请参阅[启动任务（POST jobs）](api-initiate-job-post.md)。
*类型*：以 ISO 8601 日期格式表示的字符串，例如 `2013-03-20T17:03:43.221Z`。
**Marker**
表示从何处继续对结果进行分页的 `vaultARN`。您可以在另一个列出文件库请求中使用 `marker` 来获取列表中的更多文件库。如果没有更多文件库，则此值为 `null`。
*类型*：字符串
**NumberOfArchives**
截止到上次编制清单日期，文件库中的档案数。
*类型*：数字
**SizeInBytes**
截止到上次编制清单日期，文件库中所有档案的总大小（以字节为单位），包括每个档案所具有的任何开销。
*类型*：数字
**VaultARN**
文件库的 Amazon 资源名称（ARN）。
*类型*：字符串
**VaultList**
数据元数组，其中的每个数据元均提供了文件库描述。
*类型*：数组
**VaultName**
文件库名称。
*类型*：字符串
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
### 示例：列出所有文件库
以下示例列出了文件库。由于请求中没有指定 `marker` 和 `limit` 参数，因此，系统最多会返回 10 个文件库。
#### 请求示例
```
1. GET /-/vaults 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
```
#### 响应示例
`Marker` 为 `null`，表示没有更多文件库要列出。
```
1. HTTP/1.1 200 OK
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:02:00 GMT
4. Content-Type: application/json
5. Content-Length: 497
6.
7. {
8. "Marker": null,
9. "VaultList": [
10. {
11. "CreationDate": "2012-03-16T22:22:47.214Z",
12. "LastInventoryDate": "2012-03-21T22:06:51.218Z",
13. "NumberOfArchives": 2,
14. "SizeInBytes": 12334,
15. "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault1",
16. "VaultName": "examplevault1"
17. },
18. {
19. "CreationDate": "2012-03-19T22:06:51.218Z",
20. "LastInventoryDate": "2012-03-21T22:06:51.218Z",
21. "NumberOfArchives": 0,
22. "SizeInBytes": 0,
23. "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault2",
24. "VaultName": "examplevault2"
25. },
26. {
27. "CreationDate": "2012-03-19T22:06:51.218Z",
28. "LastInventoryDate": "2012-03-25T12:14:31.121Z",
29. "NumberOfArchives": 0,
30. "SizeInBytes": 0,
31. "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault3",
32. "VaultName": "examplevault3"
33. }
34. ]
35. }
```
### 示例：文件库的部分列表
以下示例会返回从 `marker` 指定的文件库开始的两个文件库。
#### 请求示例
```
1. GET /-/vaults?limit=2&marker=arn:aws:glacier:us-west-2:012345678901:vaults/examplevault1 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
```
#### 响应示例
列表中返回了两个文件库。`Marker` 包含文件库 ARN，以便在另一个列出文件库请求中继续分页。
```
1. HTTP/1.1 200 OK
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:02:00 GMT
4. Content-Type: application/json
5. Content-Length: 497
6.
7. {
8. "Marker": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault3",
9. "VaultList": [
10. {
11. "CreationDate": "2012-03-16T22:22:47.214Z",
12. "LastInventoryDate": "2012-03-21T22:06:51.218Z",
13. "NumberOfArchives": 2,
14. "SizeInBytes": 12334,
15. "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault1",
16. "VaultName": "examplevault1"
17. },
18. {
19. "CreationDate": "2012-03-19T22:06:51.218Z",
20. "LastInventoryDate": "2012-03-21T22:06:51.218Z",
21. "NumberOfArchives": 0,
22. "SizeInBytes": 0,
23. "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault2",
24. "VaultName": "examplevault2"
25. }
26. ]
27. }
```
## 相关部分
+ [创建文件库（PUT vault）](api-vault-put.md)
+ [删除文件库（DELETE vault）](api-vault-delete.md)
+ [启动任务（POST jobs）](api-initiate-job-post.md)
+ [适用于 Amazon Glacier 的 Identity and Access Management](security-iam.md)
## 另请参阅
有关在特定语言的 Amazon SDK 中使用此 API 的更多信息，请参阅以下内容：
+ [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/reference/glacier/list-vaults.html)
# 从文件库删除标签（POST tags remove）
从文件库删除标签
此操作会从已附加到文件库的标签集中删除一个或多个标签。有关标签的更多信息，请参阅[标记 Amazon Glacier 资源](tagging.md)。
此操作是幂等的。即使没有已附加到文件库的标签，此操作也将会成功。
## 请求语法
要从文件库中删除标签，请将 HTTP POST 请求发送到标签 URI，如以下语法示例中所示。
```
POST /AccountId/vaults/vaultName/tags?operation=remove HTTP/1.1
Host: glacier.Region.amazonaws.com
Date: Date
Authorization: SignatureValue
Content-Length: Length
x-amz-glacier-version: 2012-06-01
{
"TagKeys": [
"string",
"string"
]
}
```
**注意**
`AccountId` 值为 AWS 账户 ID。此值必须与用来对请求进行签名的凭证相关联的 AWS 账户 ID 相匹配。您可以指定 AWS 账户 ID，也可以选择指定“`-`”（连字符），在这种情况下，Amazon Glacier 使用与用来对请求进行签名的凭证相关联的 AWS 账户 ID。如果您指定账户 ID，请勿在 ID 中包含任何连字符（-）。
## 请求参数
| 名称 | 描述 | 是否必需 |
| --- | --- | --- |
| operation=remove | 带有 `operation` 值的单个查询字符串参数 `remove`，用于与 [向文件库添加标签（POST tags add）](api-AddTagsToVault.md) 进行区分。 | 是 |
### 请求标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
### 请求正文
请求正文中包含以下 JSON 字段。
**TagKeys**
标签键的列表。从文件库中删除每个对应的标签。
*类型：*字符串的数组
*长度约束：*列表中最少 1 个项。列表中最多 10 个项。
*是否必需*：是
## 响应
如果此操作成功，则该服务会发送回带有空 HTTP 正文的 HTTP `204 No Content` 响应。
### 语法
```
HTTP/1.1 204 No Content
x-amzn-RequestId: x-amzn-RequestId
Date: Date
```
### 响应标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 响应正文
此操作不返回响应正文。
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
### 请求示例
以下示例发送一个 HTTP POST 请求以删除指定的标签。
```
1. POST /-/vaults/examplevault/tags?operation=remove HTTP/1.1
2. Host: glacier.us-west-2.amazonaws.com
3. x-amz-Date: 20170210T120000Z
4. Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20141123/us-west-2/glacier/aws4_request,SignedHeaders=host;x-amz-date;x-amz-glacier-version,Signature=9257c16da6b25a715ce900a5b45b03da0447acf430195dcb540091b12966f2a2
5. Content-Length: length
6. x-amz-glacier-version: 2012-06-01
7.
8. {
9. "TagsKeys": [
10. "examplekey1",
11. "examplekey2"
12. ]
13. }
```
### 响应示例
如果请求成功，Amazon Glacier（Amazon Glacier）会返回 `HTTP 204 No Content`，如以下示例中所示。
```
1. HTTP/1.1 204 No Content
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:02:00 GMT
```
## 相关部分
+ [向文件库添加标签（POST tags add）](api-AddTagsToVault.md)
+ [列出文件库的标签（GET tags）](api-ListTagsForVault.md)
## 另请参阅
有关在特定语言的 Amazon SDK 中使用此 API 的更多信息，请参阅以下内容：
+ [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/reference/glacier/remove-tags-from-vault.html)
# 设置文件库访问策略（PUT access-policy）
设置文件库访问策略
## 说明
此操作会为文件库配置一个访问策略并覆盖现有策略。要配置文件库访问策略，请向文件库的 `PUT` 子资源发送 `access-policy` 请求。您可以为每个文件库设置一个访问策略，该策略的大小最多为 20 KB。有关文件库访问策略的更多信息，请参阅[文件库访问策略](vault-access-policy.md)。
## 请求
### 语法
要设置文件库访问策略，请向文件库的 `access-policy` 子资源的 URI 发送 HTTP `PUT` 请求，如以下语法示例所示。
```
1. PUT /AccountId/vaults/vaultName/access-policy HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. Content-Length: Length
6. x-amz-glacier-version: 2012-06-01
7.
8. {
9. "Policy": "string"
10. }
```
**注意**
该`AccountId`值是拥有文件库的账户的 AWS 账户 ID。您可以指定一个 AWS 账户 ID，也可以选择指定一个 '`-`'（连字符），在这种情况下，Amazon Glacier 使用与用于签署请求的凭证关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
此操作不使用请求参数。
### 请求标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
### 请求正文
请求正文中包含以下 JSON 字段。
**Policy**
以 JSON 字符串形式表示的文件库访问策略（使用“\$1”作为转义符）。
类型：字符串
是否必需：是
## 响应
作为响应，Amazon Glacier 会返回 `204 No Content`（如果接受了策略）。
### 语法
```
HTTP/1.1 204 No Content
x-amzn-RequestId: x-amzn-RequestId
Date: Date
```
### 响应标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 响应正文
此操作不返回响应正文。
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
### 请求示例
以下示例将向文件库的 `PUT` 子资源的 URI 发送 HTTP `access-policy` 请求。`Policy` JSON 字符串使用“\$1”作为转义符。
```
1. PUT /-/vaults/examplevault/access-policy HTTP/1.1
2. Host: glacier.us-west-2.amazonaws.com
3. x-amz-Date: 20170210T120000Z
4. Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20141123/us-west-2/glacier/aws4_request,SignedHeaders=host;x-amz-date;x-amz-glacier-version,Signature=9257c16da6b25a715ce900a5b45b03da0447acf430195dcb540091b12966f2a2
5. Content-Length: length
6. x-amz-glacier-version: 2012-06-01
7.
8. {"Policy":"{\"Version\":\"2012-10-17\", \"Statement\":[{\"Sid\":\"Define-owner-access-rights\",\"Effect\":\"Allow\",\"Principal\":{\"AWS\":\"arn:aws:iam::999999999999:root\"},\"Action\":\"glacier:DeleteArchive\",\"Resource\":\"arn:aws:glacier:us-west-2:999999999999:vaults/examplevault\"}]}"}
```
### 响应示例
如果请求成功，Amazon Glacier（Amazon Glacier）会返回 `HTTP 204 No Content`，如以下示例中所示。
```
1. HTTP/1.1 204 No Content
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:02:00 GMT
```
## 相关部分
+ [删除文件库访问策略（DELETE access-policy）](api-DeleteVaultAccessPolicy.md)
+ [获取文件库访问策略（GET access-policy）](api-GetVaultAccessPolicy.md)
## 另请参阅
有关在特定语言的 Amazon 中使用此 API 的更多信息 SDKs，请参阅以下内容：
+ [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/reference/glacier/set-vault-access-policy.html)
# 设置文件库通知配置（PUT notification-configuration）
设置文件库通知配置
## 说明
在 Amazon Glacier（Amazon Glacier）中，检索档案和文件库清单是异步操作，您必须首先为这些操作启动任务，等到任务完成后，您才能下载任务输出。您可以将文件库配置为在这些任务完成时向 Amazon Simple Notification Service（Amazon SNS）主题发布消息。您可以使用此操作来设置文件库中的通知配置。有关更多信息，请参阅[在 Amazon Glacier 中配置文件库通知](configuring-notifications.md)。
要配置文件库通知，请向文件库的 `notification-configuration` 子资源发送设置请求。通知配置是特定于文件库的；因此，它也称为文件库子资源。请求应包括提供 Amazon Simple Notification Service（Amazon SNS）主题的 JSON 文档，以及要求 Amazon Glacier 向该主题发送通知的事件。
您可以配置文件库为以下文件库事件发布通知：
+ **`ArchiveRetrievalCompleted`** – 为档案检索启动的任务完成（[启动任务（POST jobs）](api-initiate-job-post.md)）时，会发生此事件。已完成任务的状态可能为 `Succeeded` 或 `Failed`。发送到 SNS 主题的通知是与从[描述任务（GET JobID）](api-describe-job-get.md)返回的输出相同的输出。
+ **`InventoryRetrievalCompleted`** – 为清单检索启动的任务完成（[启动任务（POST jobs）](api-initiate-job-post.md)）时，会发生此事件。已完成任务的状态可能为 `Succeeded` 或 `Failed`。发送到 SNS 主题的通知是与从[描述任务（GET JobID）](api-describe-job-get.md)返回的输出相同的输出。
Amazon SNS 主题必须向文件库授予允许向该主题发布通知的权限。
## 请求
要设置您文件库中的通知配置，请向文件库的 `notification-configuration` 子资源的 URI 发送设置请求。您可以在请求正文中指定配置。配置包括 Amazon SNS 主题名称以及向每个主题触发通知操作的一系列事件。
### 语法
```
1. PUT /AccountId/vaults/VaultName/notification-configuration 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. "SNSTopic": String,
9. "Events":[String, ...]
10. }
```
**注意**
该`AccountId`值是拥有文件库的账户的 AWS 账户 ID。您可以指定一个 AWS 账户 ID，也可以选择指定一个 '`-`'（连字符），在这种情况下，Amazon Glacier 使用与用于签署请求的凭证关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
此操作不使用请求参数。
### 请求标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
### 请求正文
请求正文中的 JSON 包含以下字段。
**Events**
要求 Amazon Glacier 发送通知的一个或多个事件。
*有效值*：`ArchiveRetrievalCompleted` \$1 `InventoryRetrievalCompleted`
*是否必需*：是
*类型*：数组
**SNSTopic**
Amazon SNS 主题 ARN。有关更多信息，请参阅《Amazon Simple Notification Service 入门指南》**中的 [Amazon SNS 入门](https://docs.aws.amazon.com/sns/latest/gsg/Welcome.html)。
*是否必需*：是
*类型*：字符串
## 响应
作为响应，Amazon Glacier（Amazon Glacier）返回 `204 No Content`（如果接受了通知配置）。
### 语法
```
HTTP/1.1 204 No Content
x-amzn-RequestId: x-amzn-RequestId
Date: Date
```
### 响应标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
### 响应正文
此操作不返回响应正文。
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
以下示例展示了如何配置文件库通知。
### 请求示例
以下请求设置了 `examplevault` 通知配置，以便将两个事件（`ArchiveRetrievalCompleted` 和 `InventoryRetrievalCompleted`）发送到 Amazon SNS 主题 `arn:aws:sns:us-west-2:012345678901:mytopic`。
```
1. PUT /-/vaults/examplevault/notification-policy 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. "Events": ["ArchiveRetrievalCompleted", "InventoryRetrievalCompleted"],
9. "SNSTopic": "arn:aws:sns:us-west-2:012345678901:mytopic"
10. }
```
### 响应示例
成功的响应会返回 `204 No Content`。
```
1. HTTP/1.1 204 No Content
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:00:00 GMT
```
## 相关部分
+ [获取文件库通知（GET notification-configuration）](api-vault-notifications-get.md)
+ [删除文件库通知（DELETE notification-configuration）](api-vault-notifications-delete.md)
+ [适用于 Amazon Glacier 的 Identity and Access Management](security-iam.md)
## 另请参阅
有关在特定语言的 Amazon 中使用此 API 的更多信息 SDKs，请参阅以下内容：
+ [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/reference/glacier/set-vault-notifications.html)
# 档案操作
以下是可供在 Amazon Glacier 中使用的档案操作。
**Topics**
+ [
# 删除档案（DELETE archive）
](api-archive-delete.md)
+ [
# 上传档案（POST archive）
](api-archive-post.md)
# 删除档案（DELETE archive）
删除档案
## 描述
此操作会从文件库中删除档案。您可以从文件库一次删除一个档案。要删除档案，您必须在删除请求中提供档案 ID。您可以通过下载包含下载档案的文件库的文件库清单来获取档案 ID。有关下载文件库清单的更多信息，请参阅[在 Amazon Glacier 中下载文件库清单](vault-inventory.md)。
在删除档案后，您仍可能成功请求启动对已删除档案的检索任务，但档案检索任务会失败。
在您删除档案时，对相应档案 ID 正在进行的档案检索可能成功，也可能不成功，具体取决于下面的场景：
+ 如果 Amazon Glacier（Amazon Glacier）收到删除档案请求时，档案检索任务正在积极地为下载准备数据，则档案检索操作可能会失败。
+ 如果 Amazon Glacier 收到删除档案请求时，档案检索任务已成功地为下载准备好档案，则您将能够下载输出。
有关档案检索的更多信息，请参阅[在 Amazon Glacier 中下载档案](downloading-an-archive.md)。
此操作是幂等的。尝试删除已删除的档案不会导致错误。
## 请求
要删除档案，您需要向档案资源 URI 发送 `DELETE` 请求。
### 语法
```
1. DELETE /AccountId/vaults/VaultName/archives/ArchiveID HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. x-amz-Date: Date
4. Authorization: SignatureValue
5. x-amz-glacier-version: 2012-06-01
```
**注意**
`AccountId` 值是拥有文件库的账户的 AWS 账户 ID。您可以指定 AWS 账户 ID，也可以选择指定“`-`”（连字符），在这种情况下，Amazon Glacier 使用与用来对请求进行签名的凭证相关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
此操作不使用请求参数。
### 请求标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
### 请求正文
此操作没有请求正文。
## 响应
### 语法
```
HTTP/1.1 204 No Content
x-amzn-RequestId: x-amzn-RequestId
Date: Date
```
### 响应标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 响应正文
此操作不返回响应正文。
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
以下示例展示了如何从名为 `examplevault` 的文件库删除档案。
### 请求示例
要删除的档案的 ID 被指定为 `archives` 的子资源。
```
1. DELETE /-/vaults/examplevault/archives/NkbByEejwEggmBz2fTHgJrg0XBoDfjP4q6iu87-TjhqG6eGoOY9Z8i1_AUyUsuhPAdTqLHy8pTl5nfCFJmDl2yEZONi5L26Omw12vcs01MNGntHEQL8MBfGlqrEXAMPLEArchiveId 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
```
### 响应示例
如果请求成功，则 Amazon Glacier 会做出 `204 No Content` 的响应，以表示已删除档案。
```
1. HTTP/1.1 204 No Content
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:00:00 GMT
```
## 相关部分
+ [启动分段上传（POST multipart-uploads）](api-multipart-initiate-upload.md)
+ [上传档案（POST archive）](api-archive-post.md)
+ [适用于 Amazon Glacier 的 Identity and Access Management](security-iam.md)
# 上传档案（POST archive）
上传档案
## 描述
此操作会向文件库添加档案。对于成功的上传，您的数据会持久保留。作为响应，Amazon Glacier（Amazon Glacier）在响应的 `x-amz-archive-id` 标头中返回档案 ID。您应保存返回的档案 ID，以便在以后访问档案。
您必须提供您要上传的数据的 SHA256 树形哈希。有关计算 SHA256 树形哈希的信息，请参阅[计算校验和](checksum-calculations.md)。
**注意**
只有使用 API 执行上传档案（POST archive）操作才需要 SHA256 树形哈希。使用 AWS CLI 时不需要。
上传档案时，您可以选择指定最多包含 1024 个可打印 ASCII 字符的档案描述。检索档案或获取文件库清单时，Amazon Glacier 会返回档案描述。Amazon Glacier 不会以任何方式解读描述。档案描述不需要是唯一的。您不能使用描述来检索档案列表或者对档案列表进行排序。
除了可选的档案描述以外，Amazon Glacier 不支持档案的任何附加元数据。档案 ID 是字符的不透明序列，您无法从其推断有关档案的任何含意。因此，您可能会在客户端维护有关档案的元数据。有关更多信息，请参阅[在 Amazon Glacier 中处理档案](working-with-archives.md)。
档案是不可变的。上传档案后，您无法编辑档案或其描述。
## 请求
要上传档案，您可以使用 HTTP `POST` 方法，并将请求纳入到您要在其中保存档案的文件库的 `archives` 子资源。请求必须包括档案有效载荷大小和校验和（SHA256 树形哈希），并且可以选择性地包括档案的描述。
### 语法
```
1. POST /AccountId/vaults/VaultName/archives
2. Host: glacier.Region.amazonaws.com
3. x-amz-glacier-version: 2012-06-01
4. Date: Date
5. Authorization: SignatureValue
6. x-amz-archive-description: Description
7. x-amz-sha256-tree-hash: SHA256 tree hash
8. x-amz-content-sha256: SHA256 linear hash
9. Content-Length: Length
10.
11.
```
**注意**
`AccountId` 值是拥有文件库的账户的 AWS 账户 ID。您可以指定 AWS 账户 ID，也可以选择指定“`-`”（连字符），在这种情况下，Amazon Glacier 使用与用来对请求进行签名的凭证相关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
此操作的实施不使用请求参数。
### 请求标头
除了所有操作通用的请求标头外，此操作还使用以下请求标头。有关通用请求标头的更多信息，请参阅[通用请求标头](api-common-request-headers.md)。
| 名称 | 描述 | 是否必需 |
| --- | --- | --- |
| Content-Length | 数据元的大小（以字节为单位）。有关更多信息，请转到 [http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html\$1sec14.13](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.13)。 类型：数字 默认值：无 约束：无 | 是 |
| x-amz-archive-description | 您要上传的档案的可选描述。它可以为明语描述或者您选择来分配的某个标识符。描述不需要在所有档案中是唯一的。当您检索文件库清单（请参阅[启动任务（POST jobs）](api-initiate-job-post.md)）时，它会包括因做出响应而返回的每个档案的此描述。 类型：字符串 默认值：无 约束：描述的长度必须小于或等于 1024 个字符。允许的字符为不含控制代码的 7 位 ASCII 字符，明确说来就是 ASCII 值为 32-126（十进制）或 0x20-0x7E（十六进制）的字符。 | 否 |
| x-amz-content-sha256 | 有效载荷的 SHA256 校验和（线性哈希）。这不是您在 `x-amz-sha256-tree-hash` 标头中指定的相同值。 类型：字符串 默认值：无 约束：无 | 是 |
| x-amz-sha256-tree-hash | 用户计算的有效载荷的校验和（SHA256 树形哈希）。有关计算 SHA256 树形哈希的信息，请参阅[计算校验和](checksum-calculations.md)。如果 Amazon Glacier 对有效载荷进行计算得出不同的有效载荷校验和，则会拒绝请求。 类型：字符串 默认值：无 约束：无 | 是 |
### 请求正文
请求正文包含要上传的数据。
## 响应
作为响应，Amazon Glacier 持久地存储档案，并返回档案 ID 的 URI 路径。
### 语法
```
1. HTTP/1.1 201 Created
2. x-amzn-RequestId: x-amzn-RequestId
3. Date: Date
4. x-amz-sha256-tree-hash: ChecksumComputedByAmazonGlacier
5. Location: Location
6. x-amz-archive-id: ArchiveId
```
### 响应标头
除了所有操作通用的响应标头外，成功的响应中还包括以下响应标头。有关通用响应标头的更多信息，请参阅[通用响应标头](api-common-response-headers.md)。
| 名称 | 描述 |
| --- | --- |
| Location | 新添加的档案资源的相对 URI 路径。 类型：字符串 |
| x-amz-archive-id | 档案的 ID。此值也包括在 `Location` 标头中，作为该标头的一部分。 类型：字符串 |
| x-amz-sha256-tree-hash | Amazon Glacier 计算出的档案校验和。 类型：字符串 |
### 响应正文
此操作不返回响应正文。
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
### 请求示例
以下示例显示了上传档案的请求。
```
1. POST /-/vaults/examplevault/archives HTTP/1.1
2. Host: glacier.us-west-2.amazonaws.com
3. x-amz-Date: 20170210T120000Z
4. x-amz-sha256-tree-hash: beb0fe31a1c7ca8c6c04d574ea906e3f97b31fdca7571defb5b44dca89b5af60
5. x-amz-content-sha256: 7f2fe580edb35154041fa3d4b41dd6d3adaef0c85d2ff6309f1d4b520eeecda3
6. Content-Length: 2097152
7. x-amz-glacier-version: 2012-06-01
8. Authorization: Authorization=AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20141123/us-west-2/glacier/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date;x-amz-glacier-version,Signature=16b9a9e220a37e32f2e7be196b4ebb87120ca7974038210199ac5982e792cace
9.
10.
```
### 响应示例
以下成功响应具有 `Location` 标头，您可以从中获取 Amazon Glacier 分配给档案的 ID。
```
1. HTTP/1.1 201 Created
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:00:00 GMT
4. x-amz-sha256-tree-hash: beb0fe31a1c7ca8c6c04d574ea906e3f97b31fdca7571defb5b44dca89b5af60
5. Location: /111122223333/vaults/examplevault/archives/NkbByEejwEggmBz2fTHgJrg0XBoDfjP4q6iu87-TjhqG6eGoOY9Z8i1_AUyUsuhPAdTqLHy8pTl5nfCFJmDl2yEZONi5L26Omw12vcs01MNGntHEQL8MBfGlqrEXAMPLEArchiveId
6. x-amz-archive-id: NkbByEejwEggmBz2fTHgJrg0XBoDfjP4q6iu87-TjhqG6eGoOY9Z8i1_AUyUsuhPAdTqLHy8pTl5nfCFJmDl2yEZONi5L26Omw12vcs01MNGntHEQL8MBfGlqrEXAMPLEArchiveId
```
## 相关部分
+ [在 Amazon Glacier 中处理档案](working-with-archives.md)
+ [分段上传大型档案（分段上传）](uploading-archive-mpu.md)
+ [删除档案（DELETE archive）](api-archive-delete.md)
+ [适用于 Amazon Glacier 的 Identity and Access Management](security-iam.md)
# 分段上传操作
以下是可供在 Amazon Glacier 中使用的分段上传操作。
**Topics**
+ [
# 中止分段上传（DELETE uploadID）
](api-multipart-abort-upload.md)
+ [
# 完成分段上传（POST uploadID）
](api-multipart-complete-upload.md)
+ [
# 启动分段上传（POST multipart-uploads）
](api-multipart-initiate-upload.md)
+ [
# 列出段（GET uploadID）
](api-multipart-list-parts.md)
+ [
# 列出分段上传（GET multipart-uploads）
](api-multipart-list-uploads.md)
+ [
# 上传段（PUT uploadID）
](api-upload-part.md)
# 中止分段上传（DELETE uploadID）
中止分段上传
## 说明
此分段上传操作命令可以停止上传 ID 标识的分段上传。
中止分段上传请求成功后，您无法使用上传 ID 上传其他任何段或执行其他任何操作。停止已完成的分段上传失败。但是，在短时间内，停止已中止的上传将成功。
此操作是幂等的。
有关分段上传的信息，请参阅[分段上传大型档案（分段上传）](uploading-archive-mpu.md)。
## 请求
要停止分段上传，请将 HTTP `DELETE` 请求发送到文件库的 `multipart-uploads` 子资源的 URI，并将特定分段上传 ID 标识为该 URI 的一部分。
### 语法
```
1. DELETE /AccountId/vaults/VaultName/multipart-uploads/uploadID HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. x-amz-glacier-version: 2012-06-01
```
**注意**
该`AccountId`值是拥有文件库的账户的 AWS 账户 ID。您可以指定一个 AWS 账户 ID，也可以选择指定一个 '`-`'（连字符），在这种情况下，Amazon Glacier 使用与用于签署请求的凭证关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
此操作不使用请求参数。
### 请求标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
### 请求正文
此操作没有请求正文。
## 响应
### 语法
```
HTTP/1.1 204 No Content
x-amzn-RequestId: x-amzn-RequestId
Date: Date
```
### 响应标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 响应正文
此操作不返回响应正文。
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
### 请求示例
在以下示例中，`DELETE` 请求被发送到分段上传 ID 资源的 URI。
```
1. DELETE /-/vaults/examplevault/multipart-uploads/OW2fM5iVylEpFEMM9_HpKowRapC3vn5sSL39_396UW9zLFUWVrnRHaPjUJddQ5OxSHVXjYtrN47NBZ-khxOjyEXAMPLE 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
```
### 响应示例
```
1. HTTP/1.1 204 No Content
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:00:00 GMT
```
## 相关部分
+ [启动分段上传（POST multipart-uploads）](api-multipart-initiate-upload.md)
+ [上传段（PUT uploadID）](api-upload-part.md)
+ [完成分段上传（POST uploadID）](api-multipart-complete-upload.md)
+ [列出分段上传（GET multipart-uploads）](api-multipart-list-uploads.md)
+ [列出段（GET uploadID）](api-multipart-list-parts.md)
+ [分段上传大型档案（分段上传）](uploading-archive-mpu.md)
+ [适用于 Amazon Glacier 的 Identity and Access Management](security-iam.md)
# 完成分段上传（POST uploadID）
完成分段上传
## 描述
您可以调用此分段上传操作来通知 Amazon Glacier（Amazon Glacier）所有档案段已上传，使 Amazon Glacier 能够用上传的段来组装档案。
有关分段上传的信息，请参阅[分段上传大型档案（分段上传）](uploading-archive-mpu.md)。
组装档案并将其保存到文件库后，Amazon Glacier 会返回新创建的档案资源的档案 ID。上传档案后，您应保存返回的档案 ID，以便在以后检索该档案。
在请求中，您必须包括对您上传的整个档案进行计算得出的 SHA256 树形哈希。有关计算 SHA256 树形哈希的信息，请参阅[计算校验和](checksum-calculations.md)。在服务器端，Amazon Glacier 还会构造所组装档案的 SHA256 树形哈希。如果值匹配，则 Amazon Glacier 会将档案保存到文件库；否则，它返回错误，并且操作会失败。[列出段（GET uploadID）](api-multipart-list-parts.md)操作可以返回特定分段上传已上传的段的列表。它包括每个已上传段的校验和信息，可以用于解决错误的校验和问题。
此外，Amazon Glacier 还会检查是否有任何缺失的内容范围。上传段时，您可以指定范围值，用于标识每一段在最终档案组装中的位置。组装最终档案时，Amazon Glacier 会检查是否有任何缺失的内容范围；如果有任何缺失的内容范围，则 Amazon Glacier 返回错误，并且完成分段上传操作会失败。
完成分段上传是一种幂等的操作。第一次成功完成分段上传后，如果您在短时间内再次调用该操作，则该操作将成功并返回相同的档案 ID。这在您遇到网络问题或收到 500 服务器错误时很有用，在这种情况下，您可以重复您的完成分段上传请求并获取相同的档案 ID，而无需创建重复的档案。但是，请注意，在分段上传完成后，您不能调用列出段操作，并且分段上传将不会出现在列出分段上传响应中，即使可能幂等完成也是如此。
## 请求
要完成分段上传，您需要将 HTTP POST 请求发送到 Amazon Glacier 因响应您的启动分段上传请求而创建的上传 ID 的 URI。这是您在上传段时使用的相同 URI。除了通用的必需标头以外，您还必须包括整个档案的 SHA256 树形哈希的结果以及该档案的总大小（以字节为单位）。
### 语法
```
1. POST /AccountId/vaults/VaultName/multipart-uploads/uploadID
2. Host: glacier.Region.amazonaws.com
3. Date: date
4. Authorization: SignatureValue
5. x-amz-sha256-tree-hash: SHA256 tree hash of the archive
6. x-amz-archive-size: ArchiveSize in bytes
7. x-amz-glacier-version: 2012-06-01
```
**注意**
`AccountId` 值是拥有文件库的账户的 AWS 账户 ID。您可以指定 AWS 账户 ID，也可以选择指定“`-`”（连字符），在这种情况下，Amazon Glacier 使用与用来对请求进行签名的凭证相关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
此操作不使用请求参数。
### 请求标头
除了所有操作通用的请求标头外，此操作还使用以下请求标头。有关通用请求标头的更多信息，请参阅[通用请求标头](api-common-request-headers.md)。
| 名称 | 描述 | 是否必需 |
| --- | --- | --- |
| x-amz-archive-size | 整个档案的总大小（以字节为单位）。此值应为您上传的各段的所有大小之和。 类型：字符串 默认值：无 约束：无 | 是 |
| x-amz-sha256-tree-hash | 整个档案的 SHA256 树形哈希。它是各段的 SHA256 树形哈希的树形哈希。如果您在请求中指定的值与 Amazon Glacier 对最终组装的档案进行计算得出的 SHA256 树形哈希不匹配，则 Amazon Glacier 返回错误，并且请求会失败。 类型：字符串 默认值：无 约束：无 | 是 |
### 请求元素
此操作不使用请求元素。
## 响应
Amazon Glacier（Amazon Glacier）会创建整个档案的 SHA256 树形哈希。如果值与您在请求中指定的整个档案的 SHA256 树形哈希相匹配，Amazon Glacier 会将该档案添加到文件库。作为响应，它会返回 HTTP `Location` 标头，其中包括新添加的档案资源的 URL 路径。如果您在请求中发送的档案大小或 SHA256 不匹配，Amazon Glacier 将返回错误，并且上传操作会保持未完成状态。稍后可以使用正确值重试完成分段上传操作，此时，您可以成功创建档案。如果分段上传未完成，则 Amazon Glacier 最终会收回上传 ID。
### 语法
```
HTTP/1.1 201 Created
x-amzn-RequestId: x-amzn-RequestId
Date: Date
Location: Location
x-amz-archive-id: ArchiveId
```
### 响应标头
除了所有操作通用的响应标头外，成功的响应中还包括以下响应标头。有关通用响应标头的更多信息，请参阅[通用响应标头](api-common-response-headers.md)。
| 名称 | 描述 |
| --- | --- |
| Location | 新创建档案的相对 URI 路径。此 URL 包括 Amazon Glacier 生成的档案 ID。 类型：字符串 |
| x-amz-archive-id | 档案的 ID。此值也包括在 `Location` 标头中，作为该标头的一部分。 类型：字符串 |
### 响应字段
此操作不返回响应正文。
## 示例
### 请求示例
在此示例中，HTTP POST 请求会发送到启动分段上传请求返回的 URI。该请求指定了整个档案的 SHA256 树形哈希和档案总大小。
```
1. POST /-/vaults/examplevault/multipart-uploads/OW2fM5iVylEpFEMM9_HpKowRapC3vn5sSL39_396UW9zLFUWVrnRHaPjUJddQ5OxSHVXjYtrN47NBZ-khxOjyEXAMPLE HTTP/1.1
2. Host: glacier.us-west-2.amazonaws.com
3. z-amz-Date: 20170210T120000Z
4. x-amz-sha256-tree-hash:1ffc0f54dd5fdd66b62da70d25edacd0
5. x-amz-archive-size:8388608
6. x-amz-glacier-version: 2012-06-01
7. Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20141123/us-west-2/glacier/aws4_request,SignedHeaders=host;x-amz-date;x-amz-glacier-version,Signature=9257c16da6b25a715ce900a5b45b03da0447acf430195dcb540091b12966f2a2
```
### 响应示例
以下响应示例显示 Amazon Glacier 从您上传的段成功创建了档案。该响应包括具有完整路径的档案 ID。
```
1. HTTP/1.1 201 Created
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:00:00 GMT
4. Location: /111122223333/vaults/examplevault/archives/NkbByEejwEggmBz2fTHgJrg0XBoDfjP4q6iu87-TjhqG6eGoOY9Z8i1_AUyUsuhPAdTqLHy8pTl5nfCFJmDl2yEZONi5L26Omw12vcs01MNGntHEQL8MBfGlqrEXAMPLEArchiveId
5. x-amz-archive-id: NkbByEejwEggmBz2fTHgJrg0XBoDfjP4q6iu87-TjhqG6eGoOY9Z8i1_AUyUsuhPAdTqLHy8pTl5nfCFJmDl2yEZONi5L26Omw12vcs01MNGntHEQL8MBfGlqrEXAMPLEArchiveId
```
您现在可以向新添加的资源/档案的 URI 发送 HTTP 请求。例如，您可以发送 GET 请求，以检索档案。
## 相关部分
+ [启动分段上传（POST multipart-uploads）](api-multipart-initiate-upload.md)
+ [上传段（PUT uploadID）](api-upload-part.md)
+ [中止分段上传（DELETE uploadID）](api-multipart-abort-upload.md)
+ [列出分段上传（GET multipart-uploads）](api-multipart-list-uploads.md)
+ [列出段（GET uploadID）](api-multipart-list-parts.md)
+ [分段上传大型档案（分段上传）](uploading-archive-mpu.md)
+ [删除档案（DELETE archive）](api-archive-delete.md)
+ [适用于 Amazon Glacier 的 Identity and Access Management](security-iam.md)
# 启动分段上传（POST multipart-uploads）
开始分段上传
## 说明
此操作启动分段上传（请参阅[分段上传大型档案（分段上传）](uploading-archive-mpu.md)）。Amazon Glacier（Amazon Glacier）创建了分段上传资源并在响应中返回其 ID。在后续的分段上传操作中，您可以使用此上传 ID。
启动分段上传时，您可以指定段大小（以字节数为单位）。分段大小必须为兆字节（MiB）（1024 千字节 [KiB]）乘以 2 的幂，例如 1048576（1 MiB）、2097152（2 MiB）、4194304（4 MiB）、8388608（8 MiB），以此类推。允许的最小段大小为 1 MiB，最大为 4 GiB。
除了最后一段以外，您使用此上传 ID 上传的每一段都必须具有相同的大小。最后一段可以为相同的大小或较小的大小。例如，假设您要上传一个 16.2 MiB 的文件。如果您以 4 MiB 的段大小启动分段上传，则您将首先上传四段（每段 4 MiB），最后再上传一段（0.2 MiB）。
**注意**
启动分段上传时，您不需要知道档案的大小，因为 Amazon Glacier 不要求您指定整个档案大小。
完成分段上传后，Amazon Glacier 会删除 ID 引用的分段上传资源。如果取消分段上传，Amazon Glacier 还将删除分段上传资源；或者，如果在 24 小时内没有执行任何活动，分段上传资源也会被删除。24 小时后，该 ID 可能仍然可用，但是应用程序不应期望此行为。
## 请求
要启动分段上传，您可以将 HTTP `POST` 请求发送到要在其中保存档案的文件库的 `multipart-uploads` 子资源 URI。请求必须包括段大小，并且可以选择性地包括档案的描述。
### 语法
```
1. POST /AccountId/vaults/VaultName/multipart-uploads
2. Host: glacier.us-west-2.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. x-amz-glacier-version: 2012-06-01
6. x-amz-archive-description: ArchiveDescription
7. x-amz-part-size: PartSize
```
**注意**
该`AccountId`值是拥有文件库的账户的 AWS 账户 ID。您可以指定一个 AWS 账户 ID，也可以选择指定一个 '`-`'（连字符），在这种情况下，Amazon Glacier 使用与用于签署请求的凭证关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
此操作不使用请求参数。
### 请求标头
除了所有操作通用的请求标头外，此操作还使用以下请求标头。有关通用请求标头的更多信息，请参阅[通用请求标头](api-common-request-headers.md)。
| Name | 说明 | 必填 |
| --- | --- | --- |
| x-amz-part-size | 除了最后一段以外的每一段的大小（以字节为单位）。最后一段可以小于此段大小。 类型：字符串 默认值：无 约束：分段大小必须为兆字节（1024 KiB）乘以 2 的幂，例如 1048576（1 MiB）、2097152（2 MiB）、4194304（4 MiB）、8388608（8 MiB），以此类推。允许的最小段大小为 1 MB，最大为 4 GiB（4096 MiB）。 | 是 |
| x-amz-archive-description | 您正在分段上传的档案描述。它可以为明语描述或者您选择来分配的某个唯一的标识符。当您检索文件库清单（请参阅[启动任务（POST jobs）](api-initiate-job-post.md)）时，清单会包括因做出响应而返回的每个档案的此描述。档案描述中的前导空白会被删除。 类型：字符串 默认值：无 约束：描述必须小于或等于 1024 字节。允许的字符为不含控制代码的 7 位 ASCII 字符，明确说来就是 ASCII 值为 32-126（十进制）或 0x20-0x7E（十六进制）的字符。 | 否 |
### 请求正文
此操作没有请求正文。
## 响应
在响应中，Amazon Glacier 会创建由 ID 标识的分段上传资源，并返回分段上传 ID 的相对 URI 路径。
### 语法
```
1. HTTP/1.1 201 Created
2. x-amzn-RequestId: x-amzn-RequestId
3. Date: Date
4. Location: Location
5. x-amz-multipart-upload-id: multiPartUploadId
```
### 响应标头
除了所有操作通用的响应标头外，成功的响应中还包括以下响应标头。有关通用响应标头的更多信息，请参阅[通用响应标头](api-common-response-headers.md)。
| Name | 说明 |
| --- | --- |
| Location | Amazon Glacier 创建的分段上传 ID 的相对 URI 路径。您可以使用此 URI 路径来纳入您的请求以上传段，以及完成分段上传。 类型：字符串 |
| x-amz-multipart-upload-id | 分段上传的 ID。此值也包括在 `Location` 标头中，作为该标头的一部分。 类型：字符串 |
### 响应正文
此操作不返回响应正文。
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
### 请求示例
以下示例通过向名为 `POST` 的文件库的 `multipart-uploads` 子资源 URI 发送 HTTP `examplevault` 请求来启动分段上传。该请求包括标头，以指定段大小 4 MiB（4194304 字节）和可选的档案描述。
```
1. POST /-/vaults/examplevault/multipart-uploads
2. Host: glacier.us-west-2.amazonaws.com
3. x-amz-Date: 20170210T120000Z
4. x-amz-archive-description: MyArchive-101
5. x-amz-part-size: 4194304
6. x-amz-glacier-version: 2012-06-01
7. Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20141123/us-west-2/glacier/aws4_request,SignedHeaders=host;x-amz-date;x-amz-glacier-version,Signature=9257c16da6b25a715ce900a5b45b03da0447acf430195dcb540091b12966f2a2
```
### 响应示例
Amazon Glacier 会创建分段上传资源，并将它添加到文件库的 `multipart-uploads` 子资源。`Location` 响应标头包括分段上传 ID 的相对 URI 路径。
```
1. HTTP/1.1 201 Created
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:00:00 GMT
4. Location: /111122223333/vaults/examplevault/multipart-uploads/OW2fM5iVylEpFEMM9_HpKowRapC3vn5sSL39_396UW9zLFUWVrnRHaPjUJddQ5OxSHVXjYtrN47NBZ-khxOjyEXAMPLE
5. x-amz-multipart-upload-id: OW2fM5iVylEpFEMM9_HpKowRapC3vn5sSL39_396UW9zLFUWVrnRHaPjUJddQ5OxSHVXjYtrN47NBZ-khxOjyEXAMPLE
```
有关上传各段的信息，请参阅[上传段（PUT uploadID）](api-upload-part.md)。
## 相关部分
+ [上传段（PUT uploadID）](api-upload-part.md)
+ [完成分段上传（POST uploadID）](api-multipart-complete-upload.md)
+ [中止分段上传（DELETE uploadID）](api-multipart-abort-upload.md)
+ [列出分段上传（GET multipart-uploads）](api-multipart-list-uploads.md)
+ [列出段（GET uploadID）](api-multipart-list-parts.md)
+ [删除档案（DELETE archive）](api-archive-delete.md)
+ [分段上传大型档案（分段上传）](uploading-archive-mpu.md)
+ [适用于 Amazon Glacier 的 Identity and Access Management](security-iam.md)
# 列出段（GET uploadID）
列出段
## 说明
此分段上传操作会列出上传 ID 标识的特定分段上传中已上传的档案的段。有关分段上传的信息，请参阅[分段上传大型档案（分段上传）](uploading-archive-mpu.md)。
在完成分段上传前，您可以在正在进行的分段上传过程中随时发送此请求。Amazon Glacier 会返回段列表，该列表按您在每一段上传中指定的范围排序。如果您在完成分段上传后发送列出段请求，则 Amazon Glacier（Amazon Glacier）返回错误。
列出段操作支持分页。您应始终检查响应正文中的 `Marker` 字段，以查看是否有继续该列表的标记；如果没有更多项目，则 `marker` 字段为 `null`。如果 `marker` 不为 null，则为了获取下一组段，您可以发送另一个列出段请求，并将 `marker` 请求参数设置为 Amazon Glacier 为响应您之前的列出段请求而返回的标记值。
您还可以通过在请求中指定 `limit` 参数来限制响应中返回的段数。
## 请求
### 语法
要列出正在进行的分段上传的段，您可以向分段上传 ID 资源的 URI 发送 `GET` 请求。当您启动分段上传（[启动分段上传（POST multipart-uploads）](api-multipart-initiate-upload.md)）时，系统会返回分段上传 ID。您可以选择性地指定 `marker` 和 `limit` 参数。
```
1. GET /AccountId/vaults/VaultName/multipart-uploads/uploadID HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. x-amz-glacier-version: 2012-06-01
```
**注意**
该`AccountId`值是拥有文件库的账户的 AWS 账户 ID。您可以指定一个 AWS 账户 ID，也可以选择指定一个 '`-`'（连字符），在这种情况下，Amazon Glacier 使用与用于签署请求的凭证关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
| Name | 说明 | 必填 |
| --- | --- | --- |
| limit | 要返回的部分最大数目。默认限制为 50。返回的部分数可能少于指定的限制值，但永远不会超过限制值。 类型：字符串 约束：最小整数值为 `1`。最大整数值为 `50`。 | 否 |
| marker | 用于分页的不透明字符串。`marker` 指定应从其开始列出段的段。从之前的列出段响应获取 `marker` 值。只有在您要继续对之前的列出段请求中开始的结果进行分页，您才需要包括 `marker`。 类型：字符串 约束：无 | 否 |
### 请求标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 请求正文
此操作没有请求正文。
## 响应
### 语法
```
1. HTTP/1.1 200 OK
2. x-amzn-RequestId: x-amzn-RequestId
3. Date: Date
4. Content-Type: application/json
5. Content-Length: Length
6.
7. {
8. "ArchiveDescription" : String,
9. "CreationDate" : String,
10. "Marker": String,
11. "MultipartUploadId" : String,
12. "PartSizeInBytes" : Number,
13. "Parts" :
14. [ {
15. "RangeInBytes" : String,
16. "SHA256TreeHash" : String
17. },
18. ...
19. ],
20. "VaultARN" : String
21. }
```
### 响应标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 响应正文
响应正文包含以下 JSON 字段。
**ArchiveDescription**
在启动分段上传请求中指定的档案描述。如果在启动分段上传操作中没有指定档案描述，则此字段为 `null`。
*类型*：字符串
**CreationDate**
分段上传启动的 UTC 时间。
*类型*：字符串。以 ISO 8601 日期格式表示的字符串，例如 `2013-03-20T17:03:43.221Z`。
**Marker**
表示从何处继续对结果进行分页的不透明字符串。您可以在新的列出段请求中使用 `marker` 来获取列表中的更多段。如果没有更多段，则此值为 `null`。
*类型*：字符串
**MultipartUploadId**
段与其相关联的上传的 ID。
*类型*：字符串
**PartSizeInBytes**
段大小（以字节为单位）。这是您在启动分段上传请求中指定的相同值。
*类型*：数字
**部分**
分段上传的段大小的列表。数组中的每个数据元均包含 `RangeBytes` 和 `sha256-tree-hash` 名称/值对。
*类型*：数组
**RangeInBytes**
段的字节范围，包括范围的上限值。
*类型*：字符串
**SHA256TreeHash**
Amazon Glacier 为该部分计算的 SHA256 树形哈希值。此字段绝不为 `null`。
*类型*：字符串
**VaultARN**
向其启动分段上传的文件库的 Amazon 资源名称（ARN）。
*类型*：字符串
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
### 示例：列出分段上传的段
以下示例列出了上传的所有段。该示例向正在进行的分段上传的特定分段上传 ID URI 发送 HTTP `GET` 请求，并且最多返回 1000 段。
#### 请求示例
```
1. GET /-/vaults/examplevault/multipart-uploads/OW2fM5iVylEpFEMM9_HpKowRapC3vn5sSL39_396UW9zLFUWVrnRHaPjUJddQ5OxSHVXjYtrN47NBZ-khxOjyEXAMPLE 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
```
#### 响应示例
在响应中，Amazon Glacier 返回与指定分段上传 ID 相关联的上传段的列表。在此示例中，只有两段。返回的 `Marker` 字段为 `null`，表示没有更多分段上传的段。
```
1. HTTP/1.1 200 OK
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:00:00 GMT
4. Content-Type: application/json
5. Content-Length: 412
6.
7. {
8. "ArchiveDescription" : "archive description",
9. "CreationDate" : "2012-03-20T17:03:43.221Z",
10. "Marker": null,
11. "MultipartUploadId" : "OW2fM5iVylEpFEMM9_HpKowRapC3vn5sSL39_396UW9zLFUWVrnRHaPjUJddQ5OxSHVXjYtrN47NBZ-khxOjyEXAMPLE",
12. "PartSizeInBytes" : 4194304,
13. "Parts" :
14. [ {
15. "RangeInBytes" : "0-4194303",
16. "SHA256TreeHash" : "01d34dabf7be316472c93b1ef80721f5d4"
17. },
18. {
19. "RangeInBytes" : "4194304-8388607",
20. "SHA256TreeHash" : "0195875365afda349fc21c84c099987164"
21. }],
22. "VaultARN" : "arn:aws:glacier:us-west-2:012345678901:vaults/demo1-vault"
23. }
```
### 示例：列出分段上传的段（指定标记和限制请求参数）
以下示例展示了如何使用分页来获取有限数量的结果。该示例向正在进行的分段上传的特定分段上传 ID URI 发送 HTTP `GET` 请求，以返回一段。开始 `marker` 参数指定从哪段开始段列表。您可以从之前的段列表请求的响应获取 `marker` 值。此外，在此示例中，`limit` 参数设置为 1，并且返回一段。请注意，`Marker` 字段不为 `null`，表示至少还有另一段要获取。
#### 请求示例
```
1. GET /-/vaults/examplevault/multipart-uploads/OW2fM5iVylEpFEMM9_HpKowRapC3vn5sSL39_396UW9zLFUWVrnRHaPjUJddQ5OxSHVXjYtrN47NBZ-khxOjyEXAMPLE?marker=1001&limit=1 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
```
#### 响应示例
在响应中，Amazon Glacier 返回与正在进行的指定分段上传 ID 相关联的上传段的列表。
```
1. HTTP/1.1 200 OK
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:00:00 GMT
4. Content-Type: text/json
5. Content-Length: 412
6.
7. {
8. "ArchiveDescription" : "archive description 1",
9. "CreationDate" : "2012-03-20T17:03:43.221Z",
10. "Marker": "MfgsKHVjbQ6EldVl72bn3_n5h2TaGZQUO-Qb3B9j3TITf7WajQ",
11. "MultipartUploadId" : "OW2fM5iVylEpFEMM9_HpKowRapC3vn5sSL39_396UW9zLFUWVrnRHaPjUJddQ5OxSHVXjYtrN47NBZ-khxOjyEXAMPLE",
12. "PartSizeInBytes" : 4194304,
13. "Parts" :
14. [ {
15. "RangeInBytes" : "4194304-8388607",
16. "SHA256TreeHash" : "01d34dabf7be316472c93b1ef80721f5d4"
17. }],
18. "VaultARN" : "arn:aws:glacier:us-west-2:012345678901:vaults/demo1-vault"
19. }
```
## 相关部分
+ [启动分段上传（POST multipart-uploads）](api-multipart-initiate-upload.md)
+ [上传段（PUT uploadID）](api-upload-part.md)
+ [完成分段上传（POST uploadID）](api-multipart-complete-upload.md)
+ [中止分段上传（DELETE uploadID）](api-multipart-abort-upload.md)
+ [列出分段上传（GET multipart-uploads）](api-multipart-list-uploads.md)
+ [分段上传大型档案（分段上传）](uploading-archive-mpu.md)
+ [适用于 Amazon Glacier 的 Identity and Access Management](security-iam.md)
# 列出分段上传（GET multipart-uploads）
列出分段上传
## 说明
此分段上传操作会列出指定文件库中正在进行的分段上传。正在进行的分段上传是[启动分段上传（POST multipart-uploads）](api-multipart-initiate-upload.md)请求启动但尚未完成或停止的分段上传。在列出分段上传响应中返回的列表没有固定的顺序。
列出分段上传操作支持分页。默认情况下，此操作最多会在响应中返回 50 个分段上传。您应始终检查响应正文中的 `marker` 字段，以查看是否有继续该列表的标记；如果没有更多项目，则 `marker` 字段为 `null`。
如果 `marker` 不为 null，则为了获取下一组分段上传，您可以再发送一个列出分段上传请求，并将 `marker` 请求参数设置为 Amazon Glacier（Amazon Glacier）对上一次列出分段上传请求所回复的标记值。
请注意此操作与[列出段（GET uploadID）](api-multipart-list-parts.md)操作之间的区别。列出分段上传操作会列出文件库的所有分段上传。列出段操作会返回上传 ID 标识的特定分段上传的段。
有关分段上传的信息，请参阅[分段上传大型档案（分段上传）](uploading-archive-mpu.md)。
## 请求
### 语法
要列出分段上传，请向文件库的 `GET` 子资源的 URI 发送 `multipart-uploads` 请求。您可以选择性地指定 `marker` 和 `limit` 参数。
```
1. GET /AccountId/vaults/VaultName/multipart-uploads HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. x-amz-glacier-version: 2012-06-01
```
**注意**
该`AccountId`值是拥有文件库的账户的 AWS 账户 ID。您可以指定一个 AWS 账户 ID，也可以选择指定一个 '`-`'（连字符），在这种情况下，Amazon Glacier 使用与用于签署请求的凭证关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
| Name | 说明 | 必填 |
| --- | --- | --- |
| limit | 指定响应正文中返回的最大上传数。如果未指定，则列出上传操作最多会返回 50 个上传。 类型：字符串 约束：最小整数值为 `1`。最大整数值为 `50`。 | 否 |
| marker | 用于分页的不透明字符串。`marker` 指定应从其开始列出上传的上传。从之前的列出上传响应获取 `marker` 值。只有在您要继续对之前的列出上传请求中开始的结果进行分页，您才需要包括 `marker`。 类型：字符串 约束：无 | 否 |
### 请求标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 请求正文
此操作没有请求正文。
## 响应
### 语法
```
1. HTTP/1.1 200 OK
2. x-amzn-RequestId: x-amzn-RequestId
3. Date: Date
4. Content-Type: application/json
5. Content-Length: Length
6.
7. {
8. "Marker": String,
9. "UploadsList" : [
10. {
11. "ArchiveDescription": String,
12. "CreationDate": String,
13. "MultipartUploadId": String,
14. "PartSizeInBytes": Number,
15. "VaultARN": String
16. },
17. ...
18. ]
19. }
```
### 响应标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 响应正文
响应正文包含以下 JSON 字段。
**ArchiveDescription**
在启动分段上传请求中指定的档案描述。如果在启动分段上传操作中没有指定档案描述，则此字段为 `null`。
*类型*：字符串
**CreationDate**
分段上传启动的 UTC 时间。
*类型*：字符串。以 ISO 8601 日期格式表示的字符串，例如 `2013-03-20T17:03:43.221Z`。
**Marker**
表示从何处继续对结果进行分页的不透明字符串。您可以在新的列出分段上传请求中使用 `marker` 来获取列表中的更多上传。如果没有更多上传，则此值为 `null`。
*类型*：字符串
**PartSizeInBytes**
在[启动分段上传（POST multipart-uploads）](api-multipart-initiate-upload.md)请求中指定的段大小。这是上传中除了最后一段以外的所有段的大小，最后一段可能小于此大小。
*类型*：数字
**MultipartUploadId**
分段上传的 ID。
*类型*：字符串
**UploadsList**
有关分段上传数据元的元数据的列表。列表中的每个项目均包含相应上传的一组名称-值对，包括 `ArchiveDescription`、`CreationDate`、`MultipartUploadId`、`PartSizeInBytes` 和 `VaultARN`。
*类型*：数组
**VaultARN**
包含档案的文件库的 Amazon 资源名称（ARN）。
*类型*：字符串
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
### 示例：列出所有分段上传
以下示例列出了文件库的正在进行的所有分段上传。该示例显示了发送到指定文件库的 `GET` 子资源 URI 的 HTTP `multipart-uploads` 请求。由于请求中没有指定 `marker` 和 `limit` 参数，因此，系统最多会返回 1000 个正在进行的分段上传。
#### 请求示例
```
1. GET /-/vaults/examplevault/multipart-uploads 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
```
#### 响应示例
在响应中，Amazon Glacier 返回指定文件库所有正在进行的分段上传的列表。`marker` 字段为 `null`，表示没有更多上传要列出。
```
1. HTTP/1.1 200 OK
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:00:00 GMT
4. Content-Type: application/json
5. Content-Length: 1054
6.
7. {
8. "Marker": null,
9. "UploadsList": [
10. {
11. "ArchiveDescription": "archive 1",
12. "CreationDate": "2012-03-19T23:20:59.130Z",
13. "MultipartUploadId": "xsQdFIRsfJr20CW2AbZBKpRZAFTZSJIMtL2hYf8mvp8dM0m4RUzlaqoEye6g3h3ecqB_zqwB7zLDMeSWhwo65re4C4Ev",
14. "PartSizeInBytes": 4194304,
15. "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault"
16. },
17. {
18. "ArchiveDescription": "archive 2",
19. "CreationDate": "2012-04-01T15:00:00.000Z",
20. "MultipartUploadId": "nPyGOnyFcx67qqX7E-0tSGiRi88hHMOwOxR-_jNyM6RjVMFfV29lFqZ3rNsSaWBugg6OP92pRtufeHdQH7ClIpSF6uJc",
21. "PartSizeInBytes": 4194304,
22. "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault"
23. },
24. {
25. "ArchiveDescription": "archive 3",
26. "CreationDate": "2012-03-20T17:03:43.221Z",
27. "MultipartUploadId": "qt-RBst_7yO8gVIonIBsAxr2t-db0pE4s8MNeGjKjGdNpuU-cdSAcqG62guwV9r5jh5mLyFPzFEitTpNE7iQfHiu1XoV",
28. "PartSizeInBytes": 4194304,
29. "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault"
30. }
31. ]
32. }
```
### 示例：分段上传的部分列表
以下示例展示了如何使用分页来获取有限数量的结果。该示例显示了发送到指定文件库的 `GET` 子资源 URI 的 HTTP `multipart-uploads` 请求。在此示例中，`limit` 参数设置为 1，这意味着只在列表中返回一个上传，而 `marker` 参数则表示返回的列表从其开始的分段上传 ID。
#### 请求示例
```
1. GET /-/vaults/examplevault/multipart-uploads?limit=1&marker=xsQdFIRsfJr20CW2AbZBKpRZAFTZSJIMtL2hYf8mvp8dM0m4RUzlaqoEye6g3h3ecqB_zqwB7zLDMeSWhwo65re4C4Ev 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
```
#### 响应示例
在响应中，Amazon Glacier（Amazon Glacier）只返回指定文件库的最多两个正在进行的分段上传，从指定的标记开始返回两个结果。
```
1. HTTP/1.1 200 OK
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:00:00 GMT
4. Content-Type: application/json
5. Content-Length: 470
6.
7. {
8. "Marker": "qt-RBst_7yO8gVIonIBsAxr2t-db0pE4s8MNeGjKjGdNpuU-cdSAcqG62guwV9r5jh5mLyFPzFEitTpNE7iQfHiu1XoV",
9. "UploadsList" : [
10. {
11. "ArchiveDescription": "archive 2",
12. "CreationDate": "2012-04-01T15:00:00.000Z",
13. "MultipartUploadId": "nPyGOnyFcx67qqX7E-0tSGiRi88hHMOwOxR-_jNyM6RjVMFfV29lFqZ3rNsSaWBugg6OP92pRtufeHdQH7ClIpSF6uJc",
14. "PartSizeInBytes": 4194304,
15. "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault"
16. }
17. ]
18. }
```
## 相关部分
+ [启动分段上传（POST multipart-uploads）](api-multipart-initiate-upload.md)
+ [上传段（PUT uploadID）](api-upload-part.md)
+ [完成分段上传（POST uploadID）](api-multipart-complete-upload.md)
+ [中止分段上传（DELETE uploadID）](api-multipart-abort-upload.md)
+ [列出段（GET uploadID）](api-multipart-list-parts.md)
+ [分段上传大型档案（分段上传）](uploading-archive-mpu.md)
+ [适用于 Amazon Glacier 的 Identity and Access Management](security-iam.md)
# 上传段（PUT uploadID）
上传段
## 描述
此分段上传操作会上传档案的一段。您可以按任何顺序上传档案段，因为在您的上传段请求中，您会指定将在此段中上传的所组装档案的字节范围。此外，您还可以并行上传这些段。您可以为一个分段上传最多上传 10000 段。
有关分段上传的信息，请参阅[分段上传大型档案（分段上传）](uploading-archive-mpu.md)。
如果以下任何条件成立，则 Amazon Glacier（Amazon Glacier）会拒绝您的上传段请求：
+ **SHA256 树形哈希不匹配** – 为了确保段数据在传输中不会损坏，您可以计算段的 SHA256 树形哈希，并将它包括在您的请求中。收到段数据后，Amazon Glacier 也会计算 SHA256 树形哈希。如果这两个哈希值不匹配，则操作会失败。有关计算 SHA256 树形哈希的信息，请参阅[计算校验和](checksum-calculations.md)。
+ **SHA256 线性哈希不匹配** – 由于授权需要，请计算整个上传的有效载荷的 SHA256 线性哈希，并将其包括在您的请求中。有关计算 SHA256 线性哈希的信息，请参阅[计算校验和](checksum-calculations.md)。
+ **段大小不匹配** – 除了最后一段以外，每一段的大小必须与相应的[启动分段上传（POST multipart-uploads）](api-multipart-initiate-upload.md)请求中指定的大小相匹配。最后一段的大小必须是与指定大小相同的大小或者小于指定大小。
**注意**
如果您上传一段，其大小小于您在启动分段上传请求中指定的段大小，并且该段不是最后一段，则上传段请求会成功。但是，后续的完成分段上传请求会失败。
+ **范围未对齐** – 请求中的字节范围值未与相应启动请求中指定的段大小对齐。例如，如果您指定 4194304 字节 (4 MB) 的段大小，则 0 到 4194303 字节 (4 MB —1) 以及 4194304 (4 MB) 到 8388607 (8 MB —1) 为有效的段范围。但是，如果您将范围值设置为 2 MB 到 6 MB，则范围与段大小未对齐，上传将失败。
此操作是幂等的。如果您多次上传相同的段，则包括在最近请求中的数据会覆盖之前上传的数据。
## 请求
您将该 HTTP `PUT` 请求发送到启动分段上传请求返回的上传 ID 的 URI。Amazon Glacier 使用上传 ID 将段上传与特定的分段上传关联起来。请求必须包括段数据的 SHA256 树形哈希（`x-amz-SHA256-tree-hash` 标头）、整个有效载荷的 SHA256 线性哈希（`x-amz-content-sha256` 标头）、字节范围（`Content-Range` 标头）以及段的字节长度（`Content-Length` 标头）。
### 语法
```
1. PUT /AccountId/vaults/VaultName/multipart-uploads/uploadID HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. Content-Range: ContentRange
6. Content-Length: PayloadSize
7. Content-Type: application/octet-stream
8. x-amz-sha256-tree-hash: Checksum of the part
9. x-amz-content-sha256: Checksum of the entire payload
10. x-amz-glacier-version: 2012-06-01
```
**注意**
`AccountId` 值是拥有文件库的账户的 AWS 账户 ID。您可以指定 AWS 账户 ID，也可以选择指定“`-`”（连字符），在这种情况下，Amazon Glacier 使用与用来对请求进行签名的凭证相关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
此操作不使用请求参数。
### 请求标头
除了所有操作通用的请求标头外，此操作还使用以下请求标头。有关通用请求标头的更多信息，请参阅[通用请求标头](api-common-request-headers.md)。
| 名称 | 描述 | 是否必需 |
| --- | --- | --- |
| Content-Length | 标识段的长度（以字节为单位）。 类型：字符串 默认值：无 约束：无 | 否 |
| Content-Range | 标识将在此段中上传的所组装档案中的字节范围。Amazon Glacier 使用此信息按正确的顺序组装档案。此标头的格式遵循 [RFC 2616](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.16)。标头示例为 `Content-Range:bytes 0-4194303/*`。 类型：字符串 默认值：无 约束：范围不能大于您在启动分段上传时指定的段大小。 | 是 |
| x-amz-content-sha256 | 上传的有效载荷的 SHA256 校验和（线性哈希）。这不是您在 `x-amz-sha256-tree-hash` 标头中指定的相同值。 类型：字符串 默认值：无 约束：无 | 是 |
| x-amz-sha256-tree-hash | 指定要上传的数据的 SHA256 树形哈希。有关计算 SHA256 树形哈希的信息，请参阅[计算校验和](checksum-calculations.md)。 类型：字符串 默认值：无 约束：无 | 是 |
### 请求正文
请求正文包含要上传的数据。
## 响应
成功上传段后，Amazon Glacier 返回 `204 No Content` 响应。
### 语法
```
1. HTTP/1.1 204 No Content
2. x-amzn-RequestId: x-amzn-RequestId
3. Date: Date
4. x-amz-sha256-tree-hash: ChecksumComputedByAmazonGlacier
```
### 响应标头
除了所有操作通用的响应标头外，成功的响应中还包括以下响应标头。有关通用响应标头的更多信息，请参阅[通用响应标头](api-common-response-headers.md)。
| 名称 | 描述 |
| --- | --- |
| x-amz-sha256-tree-hash | Amazon Glacier 为上传的段计算的 SHA256 树形哈希。 类型：字符串 |
### 响应正文
此操作不返回响应正文。
## 示例
以下请求会上传一个 4 MB 的段。请求设置了字节范围，使它作为档案中的第一段。
### 请求示例
示例发送 HTTP `PUT` 请求，以上传一个 4 MB 的段。该请求会发送到启动分段上传请求返回的上传 ID 的 URI。`Content-Range` 标头将该段标识为档案的第一个 4 MB 数据段。
```
1. PUT /-/vaults/examplevault/multipart-uploads/OW2fM5iVylEpFEMM9_HpKowRapC3vn5sSL39_396UW9zLFUWVrnRHaPjUJddQ5OxSHVXjYtrN47NBZ-khxOjyEXAMPLE HTTP/1.1
2. Host: glacier.us-west-2.amazonaws.com
3. Date: Wed, 10 Feb 2017 12:00:00 GMT
4. Content-Range:bytes 0-4194303/*
5. x-amz-sha256-tree-hash:c06f7cd4baacb087002a99a5f48bf953
6. x-amz-content-sha256:726e392cb4d09924dbad1cc0ba3b00c3643d03d14cb4b823e2f041cff612a628
7. Content-Length: 4194304
8. Authorization: Authorization=AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20141123/us-west-2/glacier/aws4_request,SignedHeaders=host;x-amz-content-sha256;x-amz-date;x-amz-glacier-version,Signature=16b9a9e220a37e32f2e7be196b4ebb87120ca7974038210199ac5982e792cace
```
上传下一段的步骤相同；但是，您必须计算您要上传的段的新 SHA256 树形哈希，并且还必须指定新的字节范围以指示该段在最终汇编中的位置。以下请求会使用相同的上传 ID 来上传另一段。该请求会指定之前请求后档案的下一个 4 MB 以及 4 MB 的段大小。
```
1. PUT /-/vaults/examplevault/multipart-uploads/OW2fM5iVylEpFEMM9_HpKowRapC3vn5sSL39_396UW9zLFUWVrnRHaPjUJddQ5OxSHVXjYtrN47NBZ-khxOjyEXAMPLE HTTP/1.1
2. Host: glacier.us-west-2.amazonaws.com
3. Date: Wed, 10 Feb 2017 12:00:00 GMT
4. Content-Range:bytes 4194304-8388607/*
5. Content-Length: 4194304
6. x-amz-sha256-tree-hash:f10e02544d651e2c3ce90a4307427493
7. x-amz-content-sha256:726e392cb4d09924dbad1cc0ba3b00c3643d03d14cb4b823e2f041cff612a628
8. x-amz-glacier-version: 2012-06-01
9. Authorization: Authorization=AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20120525/us-west-2/glacier/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date;x-amz-glacier-version, Signature=16b9a9e220a37e32f2e7be196b4ebb87120ca7974038210199ac5982e792cace
```
可以按任何顺序上传段。Amazon Glacier 会使用每一段的范围说明来确定组装这些段的顺序。
### 响应示例
```
1. HTTP/1.1 204 No Content
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. x-amz-sha256-tree-hash: c06f7cd4baacb087002a99a5f48bf953
4. Date: Wed, 10 Feb 2017 12:00:00 GMT
```
## 相关部分
+ [启动分段上传（POST multipart-uploads）](api-multipart-initiate-upload.md)
+ [上传段（PUT uploadID）](#api-upload-part)
+ [完成分段上传（POST uploadID）](api-multipart-complete-upload.md)
+ [中止分段上传（DELETE uploadID）](api-multipart-abort-upload.md)
+ [列出分段上传（GET multipart-uploads）](api-multipart-list-uploads.md)
+ [列出段（GET uploadID）](api-multipart-list-parts.md)
+ [分段上传大型档案（分段上传）](uploading-archive-mpu.md)
+ [适用于 Amazon Glacier 的 Identity and Access Management](security-iam.md)
# 任务操作
以下是可供在 Amazon Glacier 中使用的任务操作。
**Topics**
+ [
# 描述任务（GET JobID）
](api-describe-job-get.md)
+ [
# 获取任务输出（GET output）
](api-job-output-get.md)
+ [
# 启动任务（POST jobs）
](api-initiate-job-post.md)
+ [
# 列出任务（GET jobs）
](api-jobs-get.md)
# 描述任务（GET JobID）
描述任务
## 说明
此操作返回有关您之前启动的任务的信息，包括任务启动日期、启动任务的用户、任务状态代码/消息，以及要在 Amazon Glacier（Amazon Glacier）完成任务后通知的 Amazon Simple Notification Service（Amazon SNS）主题。有关启动任务的更多信息，请参阅[启动任务（POST jobs）](api-initiate-job-post.md)。
**注意**
此操作可让您检查您的任务的状态。但是，我们强烈建议您设置 Amazon SNS 主题并在您的启动任务请求中指定它，这样，Amazon Glacier 可以在完成任务后通知该主题。
Amazon Glacier 完成任务后，任务 ID 至少在 24 小时内都不会过期。
## 请求
### 语法
要获取有关任务的信息，您可以使用 HTTP `GET` 方法，并将请求纳入到特定任务中。请注意，相对 URI 路径是您在启动任务时 Amazon Glacier 返回给您的同一路径。
```
1. GET /AccountID/vaults/VaultName/jobs/JobID HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: date
4. Authorization: signatureValue
5. x-amz-glacier-version: 2012-06-01
```
**注意**
该`AccountId`值是拥有文件库的账户的 AWS 账户 ID。您可以指定一个 AWS 账户 ID，也可以选择指定一个 '`-`'（连字符），在这种情况下，Amazon Glacier 使用与用于签署请求的凭证关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符（-）。
**注意**
在该请求中，如果您省略 `JobID`，则响应会返回指定文件库中所有有效任务的列表。有关列出任务的更多信息，请参阅[列出任务（GET jobs）](api-jobs-get.md)。
### 请求参数
此操作不使用请求参数。
### 请求标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
### 请求正文
此操作没有请求正文。
## 响应
### 语法
```
HTTP/1.1 201 Created
x-amzn-RequestId: x-amzn-RequestId
Date: Date
Content-Type: application/json
Content-Length: Length
{
"Action": "string",
"ArchiveId": "string",
"ArchiveSHA256TreeHash": "string",
"ArchiveSizeInBytes": number,
"Completed": boolean,
"CompletionDate": "string",
"CreationDate": "string",
"InventoryRetrievalParameters": {
"EndDate": "string",
"Format": "string",
"Limit": "string",
"Marker": "string",
"StartDate": "string"
},
"InventorySizeInBytes": number,
"JobDescription": "string",
"JobId": "string",
"JobOutputPath": "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"
}
}
},
"SHA256TreeHash": "string",
"SNSTopic": "string",
"StatusCode": "string",
"StatusMessage": "string",
"Tier": "string",
"VaultARN": "string"
}
```
### 响应标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 响应正文
响应正文包含以下 JSON 字段。
**Action**
任务类型。它为 `ArchiveRetrieval`、`InventoryRetrieval` 或 `Select`。
*类型*：字符串
**ArchiveId**
为选择任务或档案检索任务请求的档案 ID。否则，此字段为 `null`。
*类型*：字符串
**存档SHA256TreeHash**
档案检索任务的整个档案的 SHA256 树形哈希。对于清单检索任务，此字段为 `null`。
*类型*：字符串
**ArchiveSizeInBytes**
对于 `ArchiveRetrieval` 任务，这是正在请求下载的档案的大小（以字节为单位）。对于 `InventoryRetrieval` 任务，该值为 `null`。
*类型*：数字
**Completed**
任务状态。当档案或清单检索任务完成后，您将使用[获取任务输出（GET output）](api-job-output-get.md)来获取任务的输出。
*类型*：布尔值
**CompletionDate**
任务请求完成时的通用协调时间（UTC）时间。当任务正在进行时，该值将为空。
*类型*：字符串
**CreationDate**
创建任务的 UTC 时间。
*类型*：以 ISO 8601 日期格式表示的字符串，例如 `2013-03-20T17:03:43.221Z`。
**InventoryRetrievalParameters**
用于范围清单检索的输入参数。
*类型*：[InventoryRetrievalJobInput](api-InventoryRetrievalJobInput.md) 对象
**InventorySizeInBytes**
对于 `InventoryRetrieval` 任务，这是请求下载的清单的大小（以字节为单位）。对于 `ArchiveRetrieval` 或 `Select` 任务，该值为 `null`。
*类型*：数字
**JobDescription**
您在启动任务时提供的任务描述。
*类型*：字符串
**JobId**
标识 Amazon Glacier 中的任务的 ID。
*类型*：字符串
**JobOutputPath**
包含任务输出位置。
*类型*：字符串
**OutputLocation**
一个对象，其中包含有关选择任务结果和错误的存储位置的信息。
*类型*：[OutputLocation](api-OutputLocation.md) 对象
**RetrievalByteRange**
档案检索任务的检索字节范围，格式为 “*StartByteValue*-*EndByteValue*。” 如果您未在档案检索中指定范围，则会检索整个档案；也*StartByteValue*等于 0，*EndByteValue*等于档案大小减去 1。对于清单检索任务或选择任务，此字段为 `null`。
*类型*：字符串
**SelectParameters**
一个对象，其中包含有关用于选择任务的参数的信息。
*类型*：[SelectParameters](api-SelectParameters.md) 对象
**SHA256TreeHash**
档案请求范围的 SHA256 树形哈希值。如果档案的[启动任务（POST jobs）](api-initiate-job-post.md)请求指定了以树形哈希对齐的范围，则此字段会返回值。有关档案范围检索的树形哈希对齐的更多信息，请参阅[下载数据时接收校验和](checksum-calculations-range.md)。
对于检索整个档案时的特定情况，此值与 `ArchiveSHA256TreeHash` 值相同。
在以下情况中，此字段为 `null`：
+ 指定未以树形哈希对齐的范围的档案检索任务。
+ 指定等于整个档案的范围并且任务状态为 `InProgress` 的档案任务。
+ 清单任务。
+ 选择任务。
*类型*：字符串
**SNSTopic**
接收通知的 Amazon SNS 主题。
*类型*：字符串
**StatusCode**
指示任务状态的代码。
*有效值*：`InProgress` \$1 `Succeeded` \$1 `Failed`
*类型*：字符串
**StatusMessage**
描述任务状态的友好消息。
*类型*：字符串
**Tier**
用于选择任务或档案检索任务的数据访问套餐。
*有效值*：`Bulk` \$1`Expedited` \$1`Standard`
*类型*：字符串
**VaultARN**
任务为其子资源的文件库的 Amazon 资源名称（ARN）。
*类型*：字符串
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
以下示例显示了检索档案的任务的请求。
### 请求示例：获取任务描述
```
1. GET /-/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID 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
```
### 响应示例
响应正文包括描述指定任务的 JSON。请注意，对于清单检索和档案检索任务，JSON 字段相同。但是，当字段不适用于任务类型时，其值为 `null`。以下是档案检索任务的响应示例。注意以下几点：
+ `Action` 字段值为 `ArchiveRetrieval`。
+ `ArchiveSizeInBytes` 字段显示了档案检索任务中请求的档案的大小。
+ 该`ArchiveSHA256TreeHash`字段显示整个档案的 SHA256 树形哈希。
+ `RetrievalByteRange` 字段显示了启动任务请求中请求的范围。在此示例中，请求了整个档案。
+ 该`SHA256TreeHash`字段显示了 Initiate Job 请求中请求的范围的 SHA256 树形哈希。在此示例中，它与 `ArchiveSHA256TreeHash` 字段相同，这意味着请求了整个档案。
+ `InventorySizeInBytes` 字段值为 `null`，因为它不适用于档案检索任务。
```
1. HTTP/1.1 200 OK
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:00:00 GMT
4. Content-Type: application/json
5. Content-Length: 419
6. {
7. "Action": "ArchiveRetrieval",
8. "ArchiveId": "NkbByEejwEggmBz2fTHgJrg0XBoDfjP4q6iu87-TjhqG6eGoOY9Z8i1_AUyUsuhPAdTqLHy8pTl5nfCFJmDl2yEZONi5L26Omw12vcs01MNGntHEQL8MBfGlqrEXAMPLEArchiveId",
9. "ArchiveSizeInBytes": 16777216,
10. "ArchiveSHA256TreeHash": "beb0fe31a1c7ca8c6c04d574ea906e3f97b31fdca7571defb5b44dca89b5af60",
11. "Completed": false,
12. "CompletionDate": null,
13. "CreationDate": "2012-05-15T17:21:39.339Z",
14. "InventorySizeInBytes": null,
15. "JobDescription": "My ArchiveRetrieval Job",
16. "JobId": "HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID",
17. "RetrievalByteRange": "0-16777215",
18. "SHA256TreeHash": "beb0fe31a1c7ca8c6c04d574ea906e3f97b31fdca7571defb5b44dca89b5af60",
19. "SNSTopic": "arn:aws:sns:us-west-2:012345678901:mytopic",
20. "StatusCode": "InProgress",
21. "StatusMessage": "Operation in progress.",
22. "Tier": "Bulk",
23. "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault"
24. }
```
以下是清单检索任务的响应示例。注意以下几点：
+ `Action` 字段值为 `InventoryRetrieval`。
+ `ArchiveSizeInBytes`、`ArchiveSHA256TreeHash` 和 `RetrievalByteRange` 字段值为空，因为这些字段不适用于清单检索任务。
+ `InventorySizeInBytes` 字段值为 `null`，因为任务仍在进行，尚未为下载完全准备好清单。如果任务在您的描述任务请求前已完成，则此字段将为您提供输出的大小。
```
{
"Action": "InventoryRetrieval",
"ArchiveId": null,
"ArchiveSizeInBytes": null,
"ArchiveSHA256TreeHash": null,
"Completed": false,
"CompletionDate": null,
"CreationDate": "2012-05-15T23:18:13.224Z",
"InventorySizeInBytes": null,
"JobDescription": "Inventory Description",
"JobId": "HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID",
"RetrievalByteRange": null,
"SHA256TreeHash": null,
"SNSTopic": "arn:aws:sns:us-west-2:012345678901:mytopic",
"StatusCode": "InProgress",
"StatusMessage": "Operation in progress.",
"VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault"
}
```
以下例举了一个针对已完成清单检索任务的响应，该任务包含用于继续文件库清单检索分页的标记。
```
{
"Action": "InventoryRetrieval",
"ArchiveId": null,
"ArchiveSHA256TreeHash": null,
"ArchiveSizeInBytes": null,
"Completed": true,
"CompletionDate": "2013-12-05T21:51:13.591Z",
"CreationDate": "2013-12-05T21:51:12.281Z",
"InventorySizeInBytes": 777062,
"JobDescription": null,
"JobId": "sCC2RZNBF2nildYD_roe0J9bHRdPQUbDRkmTdg-mXi2u3lc49uW6TcEhDF2D9pB2phx-BN30JaBru7PMyOlfXHdStzu8",
"NextInventoryRetrievalMarker": null,
"RetrievalByteRange": null,
"SHA256TreeHash": null,
"SNSTopic": null,
"StatusCode": "Succeeded",
"StatusMessage": "Succeeded",
"Tier": "Bulk",
"VaultARN": "arn:aws:glacier-devo:us-west-2:836579025725:vaults/inventory-icecube-2",
"InventoryRetrievalParameters": {
"StartDate": "2013-11-12T13:43:12Z",
"EndDate": "2013-11-20T08:12:45Z",
"Limit": "120000",
"Format": "JSON",
"Marker": "vyS0t2jHQe5qbcDggIeD50chS1SXwYMrkVKo0KHiTUjEYxBGCqRLKaiySzdN7QXGVVV5XZpNVG67pCZ_uykQXFMLaxOSu2hO_-5C0AtWMDrfo7LgVOyfnveDRuOSecUo3Ueq7K0"
},
}
```
## 相关部分
+ [获取任务输出（GET output）](api-job-output-get.md)
+ [适用于 Amazon Glacier 的 Identity and Access Management](security-iam.md)
# 获取任务输出（GET output）
获取任务输出
## 说明
此操作会下载您使用[启动任务（POST jobs）](api-initiate-job-post.md)启动的任务的输出。根据您在启动任务时指定的任务类型，输出将为档案的内容或文件库清单。
您可以下载所有任务输出，也可以通过指定字节范围下载输出的一部分。对于档案和清单检索任务，您应针对在 **Get Job Output** 响应的标头中返回的大小对下载大小进行验证。
对于档案检索任务，还应验证大小是否与预期相符。如果下载部分输出，则预期大小基于您指定的字节范围。例如，如果指定 `bytes=0-1048575` 范围，则需要验证下载大小为 1048576 字节。如果下载整个档案，则预期大小是您上传到 Amazon Glacier（Amazon Glacier）的档案的大小。**Get Job Output** 响应的标头中也会返回预期大小。
对于档案检索任务的情况，根据您指定的字节范围，Amazon Glacier 返回该部分数据的校验和。要确保您下载的部分是正确的数据，请在客户端计算校验和，验证值是否匹配，并且验证大小是否和预期一致。
Amazon Glacier 完成任务后，任务 ID 至少在 24 小时内都不会过期。也就是说，您可以在 Amazon Glacier 完成任务后的 24 小时期限内下载任务输出。
## 请求
### 语法
要检索任务输出，您可以向特定任务的 `GET` 的 URI 发送 HTTP `output` 请求。
```
1. GET /AccountId/vaults/VaultName/jobs/JobID/output HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. Range: ByteRangeToRetrieve
6. x-amz-glacier-version: 2012-06-01
```
**注意**
该`AccountId`值是拥有文件库的账户的 AWS 账户 ID。您可以指定一个 AWS 账户 ID，也可以选择指定一个 '`-`'（连字符），在这种情况下，Amazon Glacier 使用与用于签署请求的凭证关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
此操作不使用请求参数。
### 请求标头
除了所有操作通用的请求标头外，此操作还使用以下请求标头。有关通用请求标头的更多信息，请参阅[通用请求标头](api-common-request-headers.md)。
| Name | 说明 | 必填 |
| --- | --- | --- |
| Range | 要从输出检索的字节范围。例如，如果您要下载前 1048576 字节，请指定范围 `bytes=0-1048575`。有关更多信息，请转到[范围标头字段定义](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35)。该范围与启动任务请求中指定的任何范围是相对而言的。默认情况下，此操作会下载整个输出。 如果任务输出很大，则您可以使用 `Range` 请求标头来检索输出的一部分。这样，您能够以较小的字节区块下载整个输出。例如，假设您有 1 GB 任务输出需要下载，您决定一次下载 128 MB 数据区块，则总共有八个获取任务输出请求。您将使用以下流程下载任务输出： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/amazonglacier/latest/dev/api-job-output-get.html) 类型：字符串 默认值：无 约束：无 | 否 |
### 请求正文
此操作没有请求正文。
## 响应
### 语法
对于返回所有任务数据的检索请求，任务输出响应会返回 `200 OK` 响应代码。当请求部分内容（例如，如果您在请求中指定了 `Range` 标头）时，则会返回响应代码 `206 Partial Content`。
```
1. HTTP/1.1 200 OK
2. x-amzn-RequestId: x-amzn-RequestId
3. Date: Date
4. Content-Type: ContentType
5. Content-Length: Length
6. x-amz-sha256-tree-hash: ChecksumComputedByAmazonGlacier
7.
8. [Body containing job output.]
```
### 响应标头
| 标题 | 说明 |
| --- | --- |
| Content-Range | Amazon Glacier 返回的字节范围。如果只下载部分输出，则响应会提供 Amazon Glacier 返回的字节范围。 例如，`bytes 0-1048575/8388608` 会从 8 MB 返回前 1 MB。 有关 `Content-Range` 标头的更多信息，请转到[内容范围标头字段定义](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.16)。 类型：字符串 |
| Content-Type | 内容类型取决于任务输出是档案还是文件库清单。 [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/amazonglacier/latest/dev/api-job-output-get.html) 类型：字符串 |
| x-amz-sha256-tree-hash | 响应中的数据的校验和。只有在检索档案检索任务的输出时，才会返回此标头。此外，如果启动任务请求中请求的检索数据范围以树形哈希对齐，并且获取任务输出中要下载的范围也以树形哈希对齐，则此标头会显示。有关以树形哈希对齐的范围的更多信息，请参阅[下载数据时接收校验和](checksum-calculations-range.md)。 例如，如果您在您的启动任务请求中指定了要检索的以树形哈希对齐的范围（包括整个档案），则您将收到您在以下条件下下载的数据的校验和： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/amazonglacier/latest/dev/api-job-output-get.html) 类型：字符串 |
### 响应正文
Amazon Glacier 会在响应正文中返回任务输出。根据任务类型，输出可以为档案内容或文件库库存。如果为文件库清单，则默认情况下，清单列表会作为以下 JSON 正文返回。
```
1. {
2. "VaultARN": String,
3. "InventoryDate": String,
4. "ArchiveList": [
5. {"ArchiveId": String,
6. "ArchiveDescription": String,
7. "CreationDate": String,
8. "Size": Number,
9. "SHA256TreeHash": String
10. },
11. ...
12. ]
13. }
```
如果您在启动文件库清单任务时请求了 CSV 格式，则文件库清单会以 CSV 格式返回在正文中。CSV 格式有五列 ArchiveId “”、“”、ArchiveDescription “”、CreationDate “大小” 和 “”，其定义与相应的 JSON 字段相同。SHA256 TreeHash
**注意**
在返回的 CSV 格式中，返回的字段可能整个字段用双引号括起来。包含逗号或双引号的字段在返回时始终用双引号括起来。例如，`my archive description,1` 返回为 `"my archive description,1"`。用双引号括起来的返回字段中的双引号字符通过在前面附加反斜杠字符来*转义*。例如，`my archive description,1"2` 返回为 `"my archive description,1\"2"`，`my archive description,1\"2` 返回为 `"my archive description,1\\"2"`。反斜杠字符不进行转义。
JSON 响应正文包含以下 JSON 字段。
**ArchiveDescription**
档案的描述。
*类型*：字符串
**ArchiveId**
档案的 ID。
*类型*：字符串
**ArchiveList**
档案元数据数组。数组中的每个数据元均表示文件库中包含的一个档案的元数据。
*类型*：数组
**CreationDate**
创建档案的 UTC 日期和时间。
*类型*：以 ISO 8601 日期格式表示的字符串，例如 `2013-03-20T17:03:43.221Z`。
**InventoryDate**
对文件库进行更改后完成文件库上次库存盘点的 UTC 日期和时间。即使 Amazon Glacier 每天准备一次文件库清单，清单日期也不会随时更新；只有在上次清单盘点后对文件库执行过添加或删除档案的操作时，清单日期才会更新。
*类型*：以 ISO 8601 日期格式表示的字符串，例如 `2013-03-20T17:03:43.221Z`。
**SHA256TreeHash**
档案的树形哈希。
*类型*：字符串
**Size**
档案的大小（以字节为单位）。
*类型*：数字
**VaultARN**
从中请求档案检索的 Amazon 资源名称（ARN）资源。
*类型*：字符串
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
以下示例显示了检索档案的任务的请求。
### 示例 1：下载输出
此示例会检索 Amazon Glacier 因响应您的启动档案检索任务请求而准备的数据。
#### 请求示例
```
1. GET /-/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID/output 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
```
#### 响应示例
以下是档案检索任务的响应示例。请注意，`Content-Type` 标头为 `application/octet-stream`，并且 `x-amz-sha256-tree-hash` 标头包括在响应中，这意味着返回所有任务数据。
```
1. HTTP/1.1 200 OK
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. x-amz-sha256-tree-hash: beb0fe31a1c7ca8c6c04d574ea906e3f97b31fdca7571defb5b44dca89b5af60
4. Date: Wed, 10 Feb 2017 12:00:00 GMT
5. Content-Type: application/octet-stream
6. Content-Length: 1048576
7.
8. [Archive data.]
```
以下是清单检索任务的响应示例。请注意，`Content-Type` 标头为 `application/json`。另请注意，响应不包括 `x-amz-sha256-tree-hash` 标头。
```
1. HTTP/1.1 200 OK
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:00:00 GMT
4. Content-Type: application/json
5. Content-Length: 906
6.
7. {
8. "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault",
9. "InventoryDate": "2011-12-12T14:19:01Z",
10. "ArchiveList": [
11. {
12. "ArchiveId": "DMTmICA2n5Tdqq5BV2z7og-A20xnpAPKt3UXwWxdWsn_D6auTUrW6kwy5Qyj9xd1MCE1mBYvMQ63LWaT8yTMzMaCxB_9VBWrW4Jw4zsvg5kehAPDVKcppUD1X7b24JukOr4mMAq-oA",
13. "ArchiveDescription": "my archive1",
14. "CreationDate": "2012-05-15T17:19:46.700Z",
15. "Size": 2140123,
16. "SHA256TreeHash": "6b9d4cf8697bd3af6aa1b590a0b27b337da5b18988dbcc619a3e608a554a1e62"
17. },
18. {
19. "ArchiveId": "2lHzwhKhgF2JHyvCS-ZRuF08IQLuyB4265Hs3AXj9MoAIhz7tbXAvcFeHusgU_hViO1WeCBe0N5lsYYHRyZ7rrmRkNRuYrXUs_sjl2K8ume_7mKO_0i7C-uHE1oHqaW9d37pabXrSA",
20. "ArchiveDescription": "my archive2",
21. "CreationDate": "2012-05-15T17:21:39.339Z",
22. "Size": 2140123,
23. "SHA256TreeHash": "7f2fe580edb35154041fa3d4b41dd6d3adaef0c85d2ff6309f1d4b520eeecda3"
24. }
25. ]
26. }
```
### 示例 2：只下载部分输出
此示例只检索 Amazon Glacier 因响应您的启动档案检索任务请求而准备的档案的一部分。该请求使用了可选的 `Range` 标头，以便只检索前 1024 字节。
#### 请求示例
```
1. GET /-/vaults/examplevault/jobs/HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID/output HTTP/1.1
2. Host: glacier.us-west-2.amazonaws.com
3. x-amz-Date: 20170210T120000Z
4. Range: bytes=0-1023
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
```
#### 响应示例
以下成功的响应显示了 `206 Partial Content` 响应。在此案例中，响应还包括 `Content-Range` 标头，该标头指定了 Amazon Glacier 返回的字节范围。
```
1. HTTP/1.1 206 Partial Content
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:00:00 GMT
4. Content-Range: bytes 0-1023/8388608
5. Content-Type: application/octet-stream
6. Content-Length: 1024
7.
8. [Archive data.]
```
## 相关部分
+ [描述任务（GET JobID）](api-describe-job-get.md)
+ [启动任务（POST jobs）](api-initiate-job-post.md)
+ [适用于 Amazon Glacier 的 Identity and Access Management](security-iam.md)
# 启动任务（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）之外的所有其他档案，使用加速套餐访问的数据通常在 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`值是拥有文件库的账户的 AWS 账户 ID。您可以指定一个 AWS 账户 ID，也可以选择指定一个 '`-`'（连字符），在这种情况下，Amazon Glacier 使用与用于签署请求的凭证关联的 AWS 账户 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)
# 列出任务（GET jobs）
列出作业
## 说明
此操作会列出文件库的任务，包括正在进行的任务以及最近完成的任务。
**注意**
Amazon Glacier（Amazon Glacier）在删除最近完成的任务前会将这些任务保留一段时间；但是，它最终会删除已完成的任务。您可以检索已完成任务的输出。在任务完成后，通过将完成的任务保留一段时间，您可以在错过任务完成通知或者首次尝试下载失败的情况下获取任务输出。例如，假设您启动档案检索任务以下载档案。任务完成后，您开始下载档案，但是遇到了网络错误。在这种情况下，您可以在任务存在时重试并下载档案。
`List Jobs` 操作支持分页。您应该始终查看响应 `Marker` 字段。如果没有更多列出的任务，则 `Marker` 字段将设置为 `null`。如果还有更多列出的任务，则 `Marker` 字段将设置为非 null 值，您可使用该值继续对列表分页。要返回从特定任务开始的任务列表，请将 `marker` 请求参数设置为您从之前的 `Marker` 请求获取的该任务的 `List Jobs` 值。
您也可以通过在请求中指定 `limit` 参数来设置响应中返回的最大任务数限制值。默认限制为 50。返回的任务数可能少于限制值，但永远不会超过限制值。
此外，您还可以通过指定可选的 `statuscode` 参数和/或 `completed` 参数来筛选返回的任务列表。使用 `statuscode` 参数，您可以指定只返回与 `InProgress`、`Succeeded` 或 `Failed` 状态匹配的任务。使用 `completed` 参数，您可以指定只返回已完成（`true`）的任务或未完成（`false`）的任务。
## 请求
### 语法
要返回所有类型的任务列表，请向文件库的 `GET` 子资源的 URI 发送 `jobs` 请求。
```
1. GET /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
```
**注意**
该`AccountId`值是拥有文件库的账户的 AWS 账户 ID。您可以指定一个 AWS 账户 ID，也可以选择指定一个 '`-`'（连字符），在这种情况下，Amazon Glacier 使用与用于签署请求的凭证关联的 AWS 账户 ID。如果您使用账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
| Name | 说明 | 必填 |
| --- | --- | --- |
| completed | 要返回的任务的状态。您可以指定 `true` 或 `false`。 类型：布尔值 约束：无 | 否 |
| limit | 要返回的任务最大数目。默认限制为 50。返回的任务数可能少于指定的限制值，但永远不会超过限制值。 类型：字符串 约束：最小整数值为 1。最大整数值为 50。 | 否 |
| marker | 用于分页的不透明字符串可指定应从其开始列出任务的任务。您可从之前的 `marker` 响应获取 `List Jobs` 值。只有在您要继续对之前的 `List Jobs` 请求中开始的结果进行分页时，才需要包括 `marker`。 类型：字符串 约束：无 | 否 |
| statuscode | 要返回的任务状态的类型。 类型：字符串 约束：`InProgress`、`Succeeded` 或 `Failed` 这三个值之一。 | 否 |
### 请求标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 请求正文
此操作没有请求正文。
## 响应
### 语法
```
HTTP/1.1 200 OK
x-amzn-RequestId: x-amzn-RequestId
Date: Date
Location: Location
Content-Type: application/json
Content-Length: Length
{
"JobList": [
{
"Action": "string",
"ArchiveId": "string",
"ArchiveSHA256TreeHash": "string",
"ArchiveSizeInBytes": number,
"Completed": boolean,
"CompletionDate": "string",
"CreationDate": "string",
"InventoryRetrievalParameters": {
"EndDate": "string",
"Format": "string",
"Limit": "string",
"Marker": "string",
"StartDate": "string"
},
"InventorySizeInBytes": number,
"JobDescription": "string",
"JobId": "string",
"JobOutputPath": "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"
}
}
},
"SHA256TreeHash": "string",
"SNSTopic": "string",
"StatusCode": "string",
"StatusMessage": "string",
"Tier": "string",
"VaultARN": "string"
}
],
"Marker": "string"
}
```
### 响应标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 响应正文
响应正文包含以下 JSON 字段。
**JobList**
任务对象的列表。每个任务对象包含描述任务的元数据。
*类型*：[GlacierJobDescription](api-GlacierJobDescription.md) 对象数组
**Marker**
表示从何处继续对结果进行分页的不透明字符串。您可以在新的 `marker` 请求中使用 ` List Jobs` 值来获取列表中的更多任务。如果没有列出更多任务，则此值为 `null`。
*类型*：字符串
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
以下示例展示了如何返回有关文件库任务的信息。第一个示例返回两个任务的列表，第二个示例返回各项任务的子集。
### 示例：返回所有任务
#### 请求示例
以下 `GET` 请求可为文件库返回任务。
```
1. GET /-/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
```
#### 响应示例
以下响应包括一个档案检索任务和一个清单检索任务，后者包含用于继续对文件库清单检索分页的标记。响应同时还可显示 `Marker` 字段已设定为 `null`，即表示没有更多列出任务。
```
1. HTTP/1.1 200 OK
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:00:00 GMT
4. Content-Type: application/json
5. Content-Length: 1444
6.
7. {
8. "JobList": [
9. {
10. "Action": "ArchiveRetrieval",
11. "ArchiveId": "BDfaUQul0dVzYwAMr8YSa_6_8abbhZq-i1oT69g8ByClfJyBgAGBkWl2QbF5os851P7Y7KdZDOHWJIn4rh1ZHaOYD3MgFhK_g0oDPesW34uHQoVGwoIqubf6BgUEfQm_wrU4Jlm3cA",
12. "ArchiveSizeInBytes": 1048576,
13. "ArchiveSHA256TreeHash": "25499381569ab2f85e1fd0eb93c5406a178ab77c5933056eb5d6e7d4adda609b",
14. "Completed": true,
15. "CompletionDate": "2012-05-01T00:00:09.304Z",
16. "CreationDate": "2012-05-01T00:00:06.663Z",
17. "InventorySizeInBytes": null,
18. "JobDescription": null,
19. "JobId": "hDe9t9DTHXqFw8sBGpLQQOmIM0-JrGtu1O_YFKLnzQ64548qJc667BRWTwBLZC76Ygy1jHYruqXkdcAhRsh0hYv4eVRU",
20. "RetrievalByteRange": "0-1048575",
21. "SHA256TreeHash": "25499381569ab2f85e1fd0eb93c5406a178ab77c5933056eb5d6e7d4adda609b",
22. "SNSTopic": null,
23. "StatusCode": "Succeeded",
24. "StatusMessage": "Succeeded",
25. "Tier": "Bulk",
26. "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault"
27. },
28. {
29. "Action": "InventoryRetrieval",
30. "ArchiveId": null,
31. "ArchiveSizeInBytes": null,
32. "ArchiveSHA256TreeHash": null,
33. "Completed": true,
34. "CompletionDate": "2013-05-11T00:25:18.831Z",
35. "CreationDate": "2013-05-11T00:25:14.981Z",
36. "InventorySizeInBytes": 1988,
37. "JobDescription": null,
38. "JobId": "2cvVOnBL36btzyP3pobwIceiaJebM1bx9vZOOUtmNAr0KaVZ4WkWgVjiPldJ73VU7imlm0pnZriBVBebnqaAcirZq_C5",
39. "RetrievalByteRange": null,
40. "SHA256TreeHash": null,
41. "SNSTopic": null,
42. "StatusCode": "Succeeded",
43. "StatusMessage": "Succeeded",
44. "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault"
45. "InventoryRetrievalParameters": {
46. "StartDate": "2013-11-12T13:43:12Z",
47. "EndDate": "2013-11-20T08:12:45Z",
48. "Limit": "120000",
49. "Format": "JSON",
50. "Marker": "vyS0t2jHQe5qbcDggIeD50chS1SXwYMrkVKo0KHiTUjEYxBGCqRLKaiySzdN7QXGVVV5XZpNVG67pCZ_uykQXFMLaxOSu2hO_-5C0AtWMDrfo7LgVOyfnveDRuOSecUo3Ueq7K0"
51. }
52. ],
53. "Marker": null
54. }
```
### 示例：返回任务的部分列表
#### 请求示例
以下 `GET` 请求返回 `marker` 参数指定的任务。如果将 `limit` 参数设置为 ，则指定最多返回两个任务。`2`
```
1. GET /-/vaults/examplevault/jobs?marker=HkF9p6o7yjhFx-K3CGl6fuSm6VzW9T7esGQfco8nUXVYwS0jlb5gq1JZ55yHgt5vP54ZShjoQzQVVh7vEXAMPLEjobID&limit=2 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
```
#### 响应示例
以下响应显示了两项返回任务，`Marker` 字段已设置为非 null 值，可用于对任务列表继续分页。
```
1. HTTP/1.1 200 OK
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:00:00 GMT
4. Content-Type: application/json
5. Content-Length: 1744
6.
7. {
8. "JobList": [
9. {
10. "Action": "ArchiveRetrieval",
11. "ArchiveId": "58-3KpZfcMPUznvMZNPaKyJx9wODCsWTnqcjtx2CjKZ6b-XgxEuA8yvZOYTPQfd7gWR4GRm2XR08gcnWbLV4VPV_kDWtZJKi0TFhKKVPzwrZnA4-FXuIBfViYUIVveeiBE51FO4bvg",
12. "ArchiveSizeInBytes": 8388608,
13. "ArchiveSHA256TreeHash": "106086b256ddf0fedf3d9e72f461d5983a2566247ebe7e1949246bc61359b4f4",
14. "Completed": true,
15. "CompletionDate": "2012-05-01T00:25:20.043Z",
16. "CreationDate": "2012-05-01T00:25:16.344Z",
17. "InventorySizeInBytes": null,
18. "JobDescription": "aaabbbccc",
19. "JobId": "s4MvaNHIh6mOa1f8iY4ioG2921SDPihXxh3Kv0FBX-JbNPctpRvE4c2_BifuhdGLqEhGBNGeB6Ub-JMunR9JoVa8y1hQ",
20. "RetrievalByteRange": "0-8388607",
21. "SHA256TreeHash": "106086b256ddf0fedf3d9e72f461d5983a2566247ebe7e1949246bc61359b4f4",
22. "SNSTopic": null,
23. "StatusCode": "Succeeded",
24. "StatusMessage": "Succeeded",
25. "Tier": "Bulk",
26. "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault"
27. },
28. {
29. "Action": "ArchiveRetrieval",
30. "ArchiveId": "2NVGpf83U6qB9M2u-Ihh61yoFLRDEoh7YLZWKBn80A2i1xG8uieBwGjAr4RkzOHA0E07ZjtI267R03Z-6Hxd8pyGQkBdciCSH1-Lw63Kx9qKpZbPCdU0uTW_WAdwF6lR6w8iSyKdvw",
31. "ArchiveSizeInBytes": 1048576,
32. "ArchiveSHA256TreeHash": "3d2ae052b2978727e0c51c0a5e32961c6a56650d1f2e4ceccab6472a5ed4a0",
33. "Completed": true,
34. "CompletionDate": "2012-05-01T16:59:48.444Z",
35. "CreationDate": "2012-05-01T16:59:42.977Z",
36. "InventorySizeInBytes": null,
37. "JobDescription": "aaabbbccc",
38. "JobId": "CQ_tf6fOR4jrJCL61Mfk6VM03oY8lmnWK93KK4gLig1UPAbZiN3UV4G_5nq4AfmJHQ_dOMLOX5k8ItFv0wCPN0oaz5dG",
39. "RetrievalByteRange": "0-1048575",
40. "SHA256TreeHash": "3d2ae052b2978727e0c51c0a5e32961c6a56650d1f2e4ceccab6472a5ed4a0",
41. "SNSTopic": null,
42. "StatusCode": "Succeeded",
43. "StatusMessage": "Succeeded",
44. "Tier": "Standard",
45. "VaultARN": "arn:aws:glacier:us-west-2:012345678901:vaults/examplevault"
46. }
47. ],
48. "Marker": "CQ_tf6fOR4jrJCL61Mfk6VM03oY8lmnWK93KK4gLig1UPAbZiN3UV4G_5nq4AfmJHQ_dOMLOX5k8ItFv0wCPN0oaz5dG"
49. }
```
## 相关部分
+ [描述任务（GET JobID）](api-describe-job-get.md)
+ [适用于 Amazon Glacier 的 Identity and Access Management](security-iam.md)
# 在任务操作中使用的数据类型
以下是在 Amazon Glacier 中和任务操作一起使用的数据类型。
**Topics**
+ [
# CSVInput
](api-CSVInput.md)
+ [
# CSVOutput
](api-CSVOutput.md)
+ [
# 加密
](api-Encryption.md)
+ [
# GlacierJobDescription
](api-GlacierJobDescription.md)
+ [
# 授权
](api-Grant.md)
+ [
# 被授权者
](api-Grantee.md)
+ [
# InputSerialization
](api-InputSerialization.md)
+ [
# InventoryRetrievalJobInput
](api-InventoryRetrievalJobInput.md)
+ [
# jobParameters
](api-jobParameters.md)
+ [
# OutputLocation
](api-OutputLocation.md)
+ [
# OutputSerialization
](api-OutputSerialization.md)
+ [
# S3Location
](api-S3Location.md)
+ [
# SelectParameters
](api-SelectParameters.md)
# CSVInput
有关包含逗号分隔值 (CSV) 文件的信息。
## 目录
**评论**
单个字符，用于指示在行的开头出现该字符时应忽略该行。
*类型*：字符串
*必需*：否
**FieldDelimiter**
单个字符，用于分隔记录中的各个字段。该字符必须是 `\n`、`\r` 或范围 32–126 中的 ASCII 字符。默认值为逗号 (`,`)。
*类型*：字符串
*默认值*：,
*必需*：否
**FileHeaderInfo**
一个值，描述如何处理输入中的第一行。
*类型*：字符串
*有效值*：`Use` \$1`Ignore` \$1`None`
*必需*：否
**QuoteCharacter**
用作转义字符的单个字符，其中字段分隔符是值的一部分。
*类型*：字符串
*必需*：否
**QuoteEscapeCharacter**
单个字符，用于对已转义值内的引号字符进行转义。
*类型*：字符串
*必需*：否
**RecordDelimiter**
单个字符，用于分隔各个记录。
*类型*：字符串
*必需*：否
## 更多信息
+ [启动任务（POST jobs）](api-initiate-job-post.md)
# CSVOutput
包含有关存储作业结果的逗号分隔值 (CSV) 格式的信息。
## 目录
**FieldDelimiter**
单个字符，用于分隔记录中的各个字段。
*类型*：字符串
*必需*：否
**QuoteCharacter**
用作转义字符的单个字符，其中字段分隔符是值的一部分。
*类型*：字符串
*必需*：否
**QuoteEscapeCharacter**
单个字符，用于对已转义值内的引号字符进行转义。
*类型*：字符串
*必需*：否
**QuoteFields**
一个值，指示是否所有输出字段都应包含在引号中。
*有效值*：`ALWAYS` \$1`ASNEEDED`
*类型*：字符串
*必需*：否
**RecordDelimiter**
单个字符，用于分隔各个记录。
*类型*：字符串
*必需*：否
## 更多信息
+ [启动任务（POST jobs）](api-initiate-job-post.md)
# 加密
包含有关用于在 Amazon S3 中存储任务结果的加密的信息。
## 目录
**加密**。
在 Amazon S3 中存储任务结果时使用的服务器端加密算法。默认值为无加密。
*类型*：字符串
*有效值*：`aws:kms` \$1`AES256`
*必需*：否
**KMSContext**
可选。如果加密类型是 `aws:kms,`，您可以使用此值为任务结果指定加密上下文。
*类型*：字符串
*必需*：否
**KMSKeyId**
用于对象加密的 AWS Key Management Service (AWS KMS) 密钥 ID。
*类型*：字符串
*必需*：否
## 更多信息
+ [启动任务（POST jobs）](api-initiate-job-post.md)
# GlacierJobDescription
包含 Amazon Glacier（Amazon Glacier）任务的描述。
## 目录
**Action**
任务类型。它为 `ArchiveRetrieval`、`InventoryRetrieval` 或 `Select`。
*类型*：字符串
**ArchiveId**
为选择任务或档案检索任务请求的档案 ID。否则，此字段为 `null`。
*类型*：字符串
**ArchiveSHA256TreeHash**
档案检索操作的整个档案的 SHA256 树形哈希。对于清单检索任务，此字段为 `null`。
*类型*：字符串
**ArchiveSizeInBytes**
对于 `ArchiveRetrieval` 任务，这是正在请求下载的档案的大小（以字节为单位）。对于 `InventoryRetrieval` 任务，该值为 `null`。
*类型*：数字
**Completed**
如果任务已完成，则为 `true`；否则为 `false`。
*类型*：布尔值
**CompletionDate**
任务完成的日期。
任务请求完成时的通用协调时间（UTC）时间。当任务正在进行时，该值将为空。
*类型*：以 ISO 8601 日期格式表示的字符串，例如 `2013-03-20T17:03:43.221Z`。
**CreationDate**
任务启动时的通用协调时间（UTC）日期。
*类型*：以 ISO 8601 日期格式表示的字符串，例如 `2013-03-20T17:03:43.221Z`。
**InventoryRetrievalParameters**
用于范围清单检索的输入参数。
*类型*：[InventoryRetrievalJobInput](api-InventoryRetrievalJobInput.md) 对象
**InventorySizeInBytes**
对于 `InventoryRetrieval` 任务，这是请求下载的清单的大小（以字节为单位）。对于 `ArchiveRetrieval` 或 `Select` 任务，该值为 `null`。
*类型*：数字
**JobDescription**
您在启动任务时提供的任务描述。
*类型*：字符串
**JobId**
标识 Amazon Glacier 中的任务的 ID。
*类型*：字符串
**JobOutputPath**
包含任务输出位置。
*类型*：字符串
**OutputLocation**
一个对象，其中包含有关选择任务结果和错误的存储位置的信息。
*类型*：[OutputLocation](api-OutputLocation.md) 对象
**RetrievalByteRange**
档案检索任务所检索的字节范围，格式为“*StartByteValue*-*EndByteValue*”。如果没有在档案检索中指定范围，则检索整个档案，并且 *StartByteValue* 等于 0，*EndByteValue* 等于档案大小减去 1。对于清单检索任务，此字段为 `null`。
*类型*：字符串
**SelectParameters**
一个对象，其中包含有关用于选择任务的参数的信息。
*类型*：[SelectParameters](api-SelectParameters.md) 对象
**SHA256TreeHash**
档案请求范围的 SHA256 树形哈希值。如果档案的[启动任务（POST jobs）](api-initiate-job-post.md)请求指定了以树形哈希对齐的范围，则此字段会返回值。有关档案范围检索的树形哈希对齐的更多信息，请参阅[下载数据时接收校验和](checksum-calculations-range.md)。
对于检索整个档案时的特定情况，此值与 `ArchiveSHA256TreeHash` 值相同。
在以下情况中，此字段为 `null`：
+ 指定未以树形哈希对齐的范围的档案检索任务。
+ 指定等于整个档案的范围并且任务状态为 `InProgress` 的档案任务。
+ 清单任务。
+ 选择任务。
*类型*：字符串
**SNSTopic**
表示 Amazon SNS 主题的 Amazon 资源名称（ARN）；如果在任务启动（[启动任务（POST jobs）](api-initiate-job-post.md)）中配置了通知，则系统会向该主题发送任务完成或失败的通知。
*类型*：字符串
**StatusCode**
指示任务状态的代码。
*有效值*：`InProgress` \$1 `Succeeded` \$1 `Failed`
*类型*：字符串
**StatusMessage**
任务状态消息。
*类型*：字符串
**Tier**
用于选择任务或档案检索任务的数据访问套餐。
*有效值*：`Expedited` \$1`Standard` \$1`Bulk`
*类型*：字符串
**VaultARN**
任务为其子资源的文件库的 ARN。
*类型*：字符串
## 更多信息
+ [启动任务（POST jobs）](api-initiate-job-post.md)
# 授权
包含有关授权的信息。
## 目录
**被授权者**
被授权者。
*类型*：[被授权者](api-Grantee.md) 对象
*必需*：否
**权限**
授予被授权者的权限。
*类型*：字符串
*有效值*: `FULL_CONTROL` \$1 `WRITE` \$1 `WRITE_ACP` \$1 `READ` \$1 `READ_ACP`
*必需*：否
## 更多信息
+ [启动任务（POST jobs）](api-initiate-job-post.md)
# 被授权者
包含有关被授权者的信息。
## 目录
**DisplayName**
被授权者的屏幕名称。
*类型*：字符串
*必需*：否
**EmailAddress**
被授权者的电子邮件地址。
*类型*：字符串
*必需*：否
**ID**：
被授权者的规范用户 ID。
*类型*：字符串
*必需*：否
**类型**
被授权者的类型。
*类型*：字符串
*有效值*：`AmazonCustomerByEmail` \$1`CanonicalUser` \$1`Group`
*必需*：否
**URI**
被授权者组的 URI。
*类型*：字符串
*必需*：否
## 更多信息
+ [启动任务（POST jobs）](api-initiate-job-post.md)
# InputSerialization
描述如何序列化档案。
## 目录
**CSV**
一个对象，用于描述 CSV 编码对象的序列化。
*类型*：[CSVInput](api-CSVInput.md) 对象
*必需*：否
## 更多信息
+ [启动任务（POST jobs）](api-initiate-job-post.md)
# InventoryRetrievalJobInput
提供用于指定范围清单检索任务的选项。
## 目录
**EndDate**
文件库清单检索的结束日期 (采用 UTC 时间格式)，在此日期之前创建的存档都包括在检索范围内。
*有效值*：以 ISO 8601 日期格式 (`YYYY-MM-DDThh:mm:ssTZD`) 表示的字符串，以秒为单位，例如 `2013-03-20T17:03:43Z`。
*类型*：字符串。以 ISO 8601 日期格式 (`YYYY-MM-DDThh:mm:ssTZD`) 表示的字符串，以秒为单位，例如 `2013-03-20T17:03:43Z`。
*必需*：否
**格式**。
文件库清单列表的输出格式，在启动任务以检索文件库清单时通过 [启动任务（POST jobs）](api-initiate-job-post.md) 请求进行设置。
*有效值*：`CSV` \$1`JSON`
*必需*：否
*类型*：字符串
**限制**
每个文件库清单检索请求可以返回的最大清单项目数。
*有效值*：大于或等于 1 的整数值。
*类型*：字符串
*必需*：否
**Marker**
表示从何处继续对结果进行分页的不透明字符串。您可以在新 `Initiate Job` 请求中使用此标记获取其他清单项目。如果没有更多清单项目，则此值为 null。
*类型*：字符串
*必需*：否
**StartDate**
文件库清单检索的开始日期 (采用 UTC 时间格式)，包含当日或之后创建的档案。
*有效值*：以 ISO 8601 日期格式 (`YYYY-MM-DDThh:mm:ssTZD`) 表示的字符串，以秒为单位，例如 `2013-03-20T17:03:43Z`。
*类型*：字符串。以 ISO 8601 日期格式 (`YYYY-MM-DDThh:mm:ssTZD`) 表示的字符串，以秒为单位，例如 `2013-03-20T17:03:43Z`。
*必需*：否
## 更多信息
+ [启动任务（POST jobs）](api-initiate-job-post.md)
# jobParameters
提供用于定义任务的选项。
## 目录
**ArchiveId**
您需要的档案的 ID。如果 `Type` 字段设置为 `select` 或 `archive-retrieval`，则此字段是必需的。如果您为清单检索任务请求指定此字段，则会出现错误。
*有效值*：必须为您从之前发送到 Amazon Glacier（Amazon Glacier）的请求获取的有效档案 ID。
*类型*：字符串
*是否必需*：如果 `Type` 设置为 `select` 或 `archive-retrieval`，则是必需的。
**描述**
任务的可选描述。
*有效值*：描述的长度必须小于或等于 1024 字节。允许的字符为不含控制代码的 7 位 ASCII 字符，明确说来就是 ASCII 值为 32-126（十进制）或 0x20-0x7E（十六进制）的字符。
*类型*：字符串
*是否必需*：否
**Format**
（可选）在启动任务以检索文件库清单时的输出格式。如果您要启动清单任务，并且不指定 `Format` 字段，则 JSON 为默认格式。
*有效值*：`CSV` \$1 `JSON`
*类型*：字符串
*是否必需*：否
**InventoryRetrievalParameters**
用于范围清单检索的输入参数。
*类型*：[InventoryRetrievalJobInput](api-InventoryRetrievalJobInput.md) 对象
*是否必需*：否
**OutputLocation**
一个对象，其中包含有关选择任务结果的存储位置的信息。
*类型*：[OutputLocation](api-OutputLocation.md) 对象
*是否必需*：对于 `select` 任务是必需的。
**RetrievalByteRange**
用于检索 `archive-retrieval` 的字节范围，采用格式“*StartByteValue*-*EndByteValue*”。如果不指定此字段，则会检索整个档案。如果指定此字段，则字节范围必须以兆字节（1024\$11024）对齐。兆字节对齐意味着 *StartByteValue* 必须可被 1 MB 整除，而且 *EndByteValue* 加 1 必须可被 1 MB 整除或者是指定为档案字节大小值减去 1 的档案的结尾。如果 **RetrievalByteRange** 没有以兆字节对齐，则此操作会返回 `400` 响应。
如果您为 `inventory-retrieval` 或 `select` 任务请求指定此字段，则会出现错误。
*类型*：字符串
*是否必需*：否
**SelectParameters**
一个对象，其中包含有关用于选择任务的参数的信息。
*类型*：[SelectParameters](api-SelectParameters.md) 对象
*是否必需*：否
**SNSTopic**
任务完成并且输出已准备好供您下载时 Amazon Glacier 向其发送通知的 Amazon SNS 主题的 Amazon 资源名称（ARN）。指定的主题会向其订阅者发布通知。
SNS 主题必须存在。如果不存在，则 Amazon Glacier 不会为您创建该主题。此外，SNS 主题必须拥有允许创建任务的账户向主题发布消息的策略。有关 SNS 主题名称的信息，请参阅《Amazon Simple Notification Service API 参考》****中的 [CreateTopic](https://docs.aws.amazon.com/sns/latest/api/API_CreateTopic.html)。
*类型*：字符串
*是否必需*：否
**Tier**
用于选择任务或档案检索任务的套餐。默认值为 `Standard`。
*有效值*：`Expedited` \$1`Standard` \$1 `Bulk`
*类型*：字符串
*是否必需*：否
**Type**
任务类型。您可以启动任务以对档案执行选择查询、检索档案或获取文件库的清单。
*有效值*：`select` \$1 `archive-retrieval` \$1 `inventory-retrieval`
*类型*：字符串
*是否必需*：是
## 更多信息
+ [启动任务（POST jobs）](api-initiate-job-post.md)
# OutputLocation
包含有关作业结果和错误的存储位置的信息。
## 目录
**S3**
一个对象，描述用于接收还原请求结果的 Amazon S3 位置。
*类型*：[S3Location](api-S3Location.md)
*必需*：是
## 更多信息
+ [启动任务（POST jobs）](api-initiate-job-post.md)
# OutputSerialization
描述如何序列化输出。
## 目录
**CSV**
一个对象，描述逗号分隔值 (CSV) 编码的查询结果的序列化。
*类型*：[CSVOutput](api-CSVOutput.md) 对象
*必需*：否
## 更多信息
+ [启动任务（POST jobs）](api-initiate-job-post.md)
# S3Location
包含有关任务结果在 Amazon S3 中的存储位置的信息。
## 目录
**AccessControlList**
控制对存储结果的访问权限的授权列表。
*类型*：[授权](api-Grant.md) 对象数组
*必需*：否
**BucketName**
存储了任务结果的 Amazon S3 存储桶的名称。该存储桶必须与包含输入档案对象的文件库位于同一个 AWS 区域中。
*类型*：字符串
*必需*：是
**CannedACL**
要应用于任务结果的标准访问控制列表 (ACL)。
*类型*：字符串
*有效值*：`private` \$1`public-read` \$1`public-read-write` \$1`aws-exec-read` \$1`authenticated-read` \$1`bucket-owner-read` \$1`bucket-owner-full-control`
*必需*：否
**加密**。
一个对象，其中包含有关用于在 Amazon S3 中存储任务结果的加密的信息。
*类型*：[加密](api-Encryption.md) 对象
*必需*：否
**Prefix**
在此请求的结果前面添加的前缀。前缀的最大长度是 512 字节。
*类型*：字符串
*必需*：是
**StorageClass**
用于存储任务结果的存储类别。
*类型*：字符串
*有效值*：`STANDARD` \$1`REDUCED_REDUNDANCY` \$1`STANDARD_IA`
*必需*：否
**标记**
应用于任务结果的标签集。
*类型*：字符串到字符串映射
*必需*：否
**UserMetadata**
在 Amazon S3 中与任务结果一起存储的元数据的映射。
*类型*：字符串到字符串映射
*必需*：否
## 更多信息
+ [启动任务（POST jobs）](api-initiate-job-post.md)
# SelectParameters
包含有关用于 select 的参数的信息。
## 目录
**Expression**
用于选择对象的表达式。该表达式不得超过 128,000 个字符的配额。
*类型*：字符串
*必需*：是
**ExpressionType**
所提供表达式的类型，例如 `SQL`。
*有效值*：`SQL`
*类型*：字符串
*必需*：是
**InputSerialization**
描述 select 中对象的序列化格式。
*类型*：[InputSerialization](api-InputSerialization.md) 对象
*必需*：否
**OutputSerialization**
描述如何序列化 select 任务的结果。
*必需*：否
*类型*：[OutputSerialization](api-OutputSerialization.md) 对象
## 更多信息
+ [启动任务（POST jobs）](api-initiate-job-post.md)
# 数据检索操作
以下是 Amazon Glacier 中可用的数据检索相关操作。
**Topics**
+ [
# 获取数据检索策略（GET policy）
](api-GetDataRetrievalPolicy.md)
+ [
# 列出预配置容量（GET provisioned-capacity）
](api-ListProvisionedCapacity.md)
+ [
# 购买预配置容量（POST provisioned-capacity）
](api-PurchaseProvisionedCapacity.md)
+ [
# 设置数据检索策略（PUT policy）
](api-SetDataRetrievalPolicy.md)
# 获取数据检索策略（GET policy）
获取数据检索策略
## 描述
此操作返回 `GET` 请求中指定的 AWS 账户和 AWS 区域的当前数据检索策略。有关数据检索策略的更多信息，请参阅 [Amazon Glacier 数据检索策略](data-retrieval-policy.md)。
## 请求
要返回当前数据检索策略，请如以下语法示例所示，向数据检索策略 URI 发送 HTTP `GET` 请求。
### 语法
```
1. GET /AccountId/policies/data-retrieval HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. x-amz-glacier-version: 2012-06-01
```
**注意**
`AccountId` 值为 AWS 账户 ID。此值必须与用来对请求进行签名的凭证相关联的 AWS 账户 ID 相匹配。您可以指定 AWS 账户 ID，也可以选择指定“`-`”（连字符），在这种情况下，Amazon Glacier 使用与用来对请求进行签名的凭证相关联的 AWS 账户 ID。如果您指定账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
此操作不使用请求参数。
### 请求标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
### 请求正文
此操作没有请求正文。
## 响应
### 语法
```
HTTP/1.1 200 OK
x-amzn-RequestId: x-amzn-RequestId
Date: Date
Content-Type: application/json
Content-Length: length
{
"Policy":
{
"Rules":[
{
"BytesPerHour": Number,
"Strategy": String
}
]
}
}
```
### 响应标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 响应正文
响应正文包含以下 JSON 字段。
**BytesPerHour**
一个小时内可以检索的最大字节数。
仅当 **Strategy** 字段的值为 `BytesPerHour` 时才会显示此字段。
*类型*：数字
**Rules**
策略规则。虽然这是列表类型，但目前只有一个规则，其中包含 Strategy 字段，还可选择包含 BytesPerHour 字段。
*类型*：数组
**Strategy**
数据检索策略的类型。
*类型*：字符串
有效值：`BytesPerHour` \$1 `FreeTier` \$1 `None`。`BytesPerHour` 等同于在控制台中选择**最高检索速率**。`FreeTier` 等同于在控制台中选择**仅免费套餐**。`None` 等同于在控制台中选择**无检索策略**。有关在控制台中选择数据检索策略的更多信息，请参阅 [Amazon Glacier 数据检索策略](data-retrieval-policy.md)。
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
以下示例演示了如何获取数据检索策略。
### 请求示例
此示例将一个 `GET` 请求发送到策略位置的 URI。
```
1. GET /-/policies/data-retrieval 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
```
### 响应示例
成功的响应会以 JSON 格式在响应正文中显示数据检索策略。
```
1. HTTP/1.1 200 OK
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:00:00 GMT
4. Content-Type: application/json
5. Content-Length: 85
6.
7. {
8. "Policy":
9. {
10. "Rules":[
11. {
12. "BytesPerHour":10737418240,
13. "Strategy":"BytesPerHour"
14. }
15. ]
16. }
17. }
```
## 相关部分
+ [设置数据检索策略（PUT policy）](api-SetDataRetrievalPolicy.md)
+ [启动任务（POST jobs）](api-initiate-job-post.md)
# 列出预配置容量（GET provisioned-capacity）
列出预配置容量
此操作列出指定 AWS 账户的预置容量。有关预配置容量的更多信息，请参阅[档案检索选项](downloading-an-archive-two-steps.md#api-downloading-an-archive-two-steps-retrieval-options)。
预配置容量单位将持续一个月，以购买日期和时间作为开始日期。此单位过期的日期为开始日期的整整一个月之后（精确到秒）。
如果开始日期为一个月的第 31 天，过期日期为下个月的最后一天。例如，如果开始日期为 8 月 31 日，则过期日期为 9 月 30 日。如果开始日期为 1 月 31 日，则过期日期为 2 月 28 日。您可以在[响应示例](#api-ListProvisionedCapacity-example1-response)中看到此功能。
## 请求语法
要列出账户的预配置检索容量，请发送 HTTP GET 请求到预配置容量 URI，如以下语法示例中所示。
```
1. GET /AccountId/provisioned-capacity HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. x-amz-glacier-version: 2012-06-01
```
**注意**
其`AccountId`值是 AWS 账户 ID。此值必须与用于签署请求的凭据关联的 AWS 账户 ID 相匹配。您可以指定一个 AWS 账户 ID，也可以选择指定一个 '`-`'（连字符），在这种情况下，Amazon Glacier 使用与用于签署请求的凭证关联的 AWS 账户 ID。如果您指定账户 ID，请勿在 ID 中包含任何连字符（-）。
## 请求参数
此操作不使用请求参数。
## 请求标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
## 请求正文
此操作没有请求正文。
## 响应
如果此操作成功，则该服务将会发送回 HTTP `200 OK` 响应。
### 响应语法
```
HTTP/1.1 200 OK
x-amzn-RequestId: x-amzn-RequestId
Date: Date
Content-Type: application/json
Content-Length: Length
{
"ProvisionedCapacityList":
{
"CapacityId" : "string",
"StartDate" : "string"
"ExpirationDate" : "string"
}
}
```
### 响应标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 响应正文
响应正文包含以下 JSON 字段。
**CapacityId**
用于确定预配置容量单位的 ID。
*类型*：字符串。
**StartDate**
预配置容量单位的购买日期，采用通用协调时间（UTC）。
*类型*：字符串。以 ISO 8601 日期格式表示的字符串，例如 `2013-03-20T17:03:43.221Z`。
**ExpirationDate**
预配置容量单位的到期日期，采用通用协调时间（UTC）。
*类型*：字符串。以 ISO 8601 日期格式表示的字符串，例如 `2013-03-20T17:03:43.221Z`。
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
以下示例列出了账户的预配置容量单位。
### 请求示例
在此示例中，发送 GET 请求来检索指定账户的预配置容量单位列表。
```
1. GET /123456789012/priority-capacity 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
```
### 响应示例
如果请求成功，Amazon Glacier（Amazon Glacier）会返回带有一个账户预配置容量单位列表的 `HTTP 200 OK`，如以下示例中所示。
列出的第一个预配置容量单位示例开始日期为 2017 年 1 月 31 日，过期日期为 2017 年 2 月 28 日。如之前所述，如果开始日期为某个月的第 31 天，过期日期则是下个月的最后一天。
```
1. HTTP/1.1 200 OK
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:02:00 GMT
4. Content-Type: application/json
5. Content-Length: length
6.
7. {
8. "ProvisionedCapacityList",
9. {
10. "CapacityId": "zSaq7NzHFQDANTfQkDen4V7z",
11. "StartDate": "2017-01-31T14:26:33.031Z",
12. "ExpirationDate": "2017-02-28T14:26:33.000Z",
13. },
14. {
15. "CapacityId": "yXaq7NzHFQNADTfQkDen4V7z",
16. "StartDate": "2016-12-13T20:11:51.095Z"",
17. "ExpirationDate": "2017-01-13T20:11:51.000Z" ",
18. },
19. ...
20. }
```
## 相关部分
+ [购买预配置容量（POST provisioned-capacity）](api-PurchaseProvisionedCapacity.md)
# 购买预配置容量（POST provisioned-capacity）
购买预配置容量
此操作为 AWS 账户购买预置容量单位。
预配置容量单位将持续一个月，以购买日期和时间作为开始日期。此单位过期的日期为开始日期的整整一个月之后（精确到秒）。
如果开始日期为一个月的第 31 天，过期日期为下个月的最后一天。例如，如果开始日期为 8 月 31 日，则过期日期为 9 月 30 日。如果开始日期为 1 月 31 日，则过期日期为 2 月 28 日。
预配置容量帮助确保在您需要时，可以使用针对加速检索的检索容量。每个容量单位可确保每五分钟至少可以执行三次快速检索，并提供高达 150 MB/s 的检索吞吐量。有关预配置容量的更多信息，请参阅[档案检索选项](downloading-an-archive-two-steps.md#api-downloading-an-archive-two-steps-retrieval-options)。
**注意**
每个配置的容量单位限制为两个单位。 AWS 账户
## 请求
要购买的预配置容量单位，请向预配置容量 URI AWS 账户 发送 HTTP `POST` 请求。
### 语法
```
1. POST /AccountId/provisioned-capacity HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. Content-Length: Length
6. x-amz-glacier-version: 2012-06-01
```
**注意**
其`AccountId`值是 AWS 账户 ID。此值必须与用于签署请求的凭据关联的 AWS 账户 ID 相匹配。您可以指定一个 AWS 账户 ID，也可以选择指定一个 '`-`'（连字符），在这种情况下，Amazon Glacier 使用与用于签署请求的凭证关联的 AWS 账户 ID。如果您指定账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
#### 请求标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
#### 请求正文
此操作没有请求正文。
## 响应
如果操作请求成功，则该服务会返回 HTTP `201 Created` 响应。
### 语法
```
HTTP/1.1 201 Created
x-amzn-RequestId: x-amzn-RequestId
Date: Date
x-amz-capacity-id: CapacityId
```
### 响应标头
除了所有操作通用的响应标头外，成功的响应中还包括以下响应标头。有关通用响应标头的更多信息，请参阅[通用响应标头](api-common-response-headers.md)。
| Name | 说明 |
| --- | --- |
| `x-amz-capacity-id` | 用于确定预配置容量单位的 ID。 类型：字符串 |
### 响应正文
此操作不返回响应正文。
### 错误
除了所有 Amazon Glacier 操作中常见的可能错误外，此操作还包括以下一个或多个错误。有关 Amazon Glacier 错误的信息以及错误代码列表，请参阅[错误响应](api-error-responses.md)。
| 代码 | 说明 | HTTP 状态代码 | 类型 |
| --- | --- | --- | --- |
| LimitExceededException | 如果指定请求将超出账户的预配置容量单位限制，则返回此代码。 | 400 Bad Request | 客户端 |
## 示例
以下示例为账户购买预配置容量。
### 请求示例
以下示例发送 HTTP POST 请求以购买预配置容量单位。
```
1. POST /123456789012/provisioned-capacity HTTP/1.1
2. Host: glacier.us-west-2.amazonaws.com
3. x-amz-Date: 20170210T120000Z
4. Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20141123/us-west-2/glacier/aws4_request,SignedHeaders=host;x-amz-date;x-amz-glacier-version,Signature=9257c16da6b25a715ce900a5b45b03da0447acf430195dcb540091b12966f2a2
5. Content-Length: length
6. x-amz-glacier-version: 2012-06-01
```
### 响应示例
如果请求成功，Amazon Glacier（Amazon Glacier）将返回 `HTTP 201 Created` 响应，如以下示例中所示。
```
1. HTTP/1.1 201 Created
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:02:00 GMT
4. x-amz-capacity-id: zSaq7NzHFQDANTfQkDen4V7z
```
## 相关部分
+ [列出预配置容量（GET provisioned-capacity）](api-ListProvisionedCapacity.md)
# 设置数据检索策略（PUT policy）
设置数据检索策略
## 描述
此操作在 `PUT` 请求所指定的 AWS 区域中设置数据检索策略，然后应用该策略。对于 AWS 账户，您可以针对每个 AWS 区域设置一个策略。该策略在 `PUT` 操作成功后数分钟内应用。
在策略应用之前，设置策略的操作并不影响正在进行的检索作业。有关数据检索策略的更多信息，请参阅 [Amazon Glacier 数据检索策略](data-retrieval-policy.md)。
## 请求
### 语法
要设置数据检索策略，请如以下语法示例所示，向数据检索策略 URI 发送 HTTP PUT 请求。
```
1. PUT /AccountId/policies/data-retrieval HTTP/1.1
2. Host: glacier.Region.amazonaws.com
3. Date: Date
4. Authorization: SignatureValue
5. Content-Length: Length
6. x-amz-glacier-version: 2012-06-01
7.
8. {
9. "Policy":
10. {
11. "Rules":[
12. {
13. "Strategy": String,
14. "BytesPerHour": Number
15. }
16. ]
17. }
18. }
```
**注意**
`AccountId` 值为 AWS 账户 ID。此值必须与用来对请求进行签名的凭证相关联的 AWS 账户 ID 相匹配。您可以指定 AWS 账户 ID，也可以选择指定“`-`”（连字符），在这种情况下，Amazon Glacier 使用与用来对请求进行签名的凭证相关联的 AWS 账户 ID。如果您指定账户 ID，请勿在 ID 中包含任何连字符（-）。
### 请求参数
此操作不使用请求参数。
### 请求标头
此操作仅使用所有操作通用的请求标头。有关通用请求标头的信息，请参阅[通用请求标头](api-common-request-headers.md)。
### 请求正文
请求正文中包含以下 JSON 字段。
**BytesPerHour**
一个小时内可以检索的最大字节数。
仅当 Strategy 字段的值为 `BytesPerHour` 时，此字段才是必需字段。若您设置此字段，但 Strategy 字段并未设置为 `BytesPerHour`，则 PUT 操作会被拒绝。
*类型*：数字
*是否必需*：如果 Strategy 字段设置为 `BytesPerHour`，则为必需。否则不是必需。
*有效值*：最小整数值 1。最大整数值 2^63 - 1（含）。
**Rules**
策略规则。虽然这是列表类型，但目前只能有一个规则，其中包含 Strategy 字段，还可选择包含 BytesPerHour 字段。
*类型*：数组
*是否必需*：是
**Strategy**
要设置的数据检索策略的类型。
*类型*：字符串
*是否必需*：是
有效值：`BytesPerHour` \$1 `FreeTier` \$1 `None`。`BytesPerHour` 等同于在控制台中选择**最高检索速率**。`FreeTier` 等同于在控制台中选择**仅免费套餐**。`None` 等同于在控制台中选择**无检索策略**。有关在控制台中选择数据检索策略的更多信息，请参阅 [Amazon Glacier 数据检索策略](data-retrieval-policy.md)。
## 响应
### 语法
```
HTTP/1.1 204 No Content
x-amzn-RequestId: x-amzn-RequestId
Date: Date
```
### 响应标头
此操作仅使用大多数响应通用的响应标头。有关通用响应标头的信息，请参阅[通用响应标头](api-common-response-headers.md)。
### 响应正文
此操作不返回响应正文。
### 错误
有关 Amazon Glacier 异常和错误消息的信息，请参阅[错误响应](api-error-responses.md)。
## 示例
### 请求示例
以下示例发送一个 HTTP PUT 请求，其中 Strategy 字段设置为 `BytesPerHour`。
```
1. PUT /-/policies/data-retrieval 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. "Policy":
9. {
10. "Rules":[
11. {
12. "Strategy":"BytesPerHour",
13. "BytesPerHour":10737418240
14. }
15. ]
16. }
17. }
```
以下示例发送一个 HTTP PUT 请求，其中 Strategy 字段设置为 `FreeTier`。
```
1. PUT /-/policies/data-retrieval 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. "Policy":
9. {
10. "Rules":[
11. {
12. "Strategy":"FreeTier"
13. }
14. ]
15. }
16. }
```
以下示例发送一个 HTTP PUT 请求，其中 Strategy 字段设置为 `None`。
```
1. PUT /-/policies/data-retrieval 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. "Policy":
9. {
10. "Rules":[
11. {
12. "Strategy":"None"
13. }
14. ]
15. }
16. }
```
### 响应示例
如以下示例所示，如果请求成功，Amazon Glacier（Amazon Glacier）会设置策略并返回 `HTTP 204 No Content`。
```
1. HTTP/1.1 204 No Content
2. x-amzn-RequestId: AAABZpJrTyioDC_HsOmHae8EZp_uBSJr6cnGOLKp_XJCl-Q
3. Date: Wed, 10 Feb 2017 12:02:00 GMT
```
## 相关部分
+ [获取数据检索策略（GET policy）](api-GetDataRetrievalPolicy.md)
+ [启动任务（POST jobs）](api-initiate-job-post.md)