AWS Storage Gateway 的 API 参考

除使用控制台外，您还可以使用 AWS Storage Gateway API，以编程方式配置并管理网关。本部分描述 AWS Storage Gateway 操作、为身份验证进行的请求签名和错误处理。有关可用于 AWS Storage Gateway 的区域和终端节点的信息，请参阅 AWS General Reference 中的 AWS Storage Gateway 终端节点和配额。

AWS Storage Gateway 必需的请求标头

本部分描述您每次向 AWS Storage Gateway 发送 POST 请求时必须使用的标头。您将 HTTP 标头包含在内以识别有关请求的密钥信息，包括您希望调用的操作、请求的日期以及表示您拥有请求发送者授权的信息。标头区分大小写，其次序不重要。

下例展示在 ActivateGateway 操作中使用的标头。

POST / HTTP/1.1 
Host: storagegateway.us-east-2.amazonaws.com.cn
Content-Type: application/x-amz-json-1.1
Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20120425/us-east-2/storagegateway/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=9cd5a3584d1d67d57e61f120f35102d6b3649066abdd4bf4bbcf05bd9f2f8fe2
x-amz-date: 20120912T120000Z
x-amz-target: StorageGateway_20120630.ActivateGateway

以下是必须包含在向 AWS Storage Gateway 发送的 POST 请求中的标头。以下所示标头以“x-amz”为开头，是 AWS 专属的标头。列出的其他所有标头均为 HTTP 事务中使用的普通标头。

Authorization: AWS4-HMAC_SHA456 
Credentials=YourAccessKey/yyymmdd/region/storagegateway/aws4_request, 
SignedHeaders=content-type;host;x-amz-date;x-amz-target, 
Signature=CalculatedSignature

Content-Type: application/x-amz-json-1.1

Host: storagegateway.region.amazonaws.com

x-amz-date: YYYYMMDD'T'HHMMSS'Z'

x-amz-target: StorageGateway_APIversion.operationName

签名请求

AWS Storage Gateway 要求通过对请求进行签名，验证所发送的每个请求的身份。您使用加密哈希函数计算数字签名，从而对请求签名。加密哈西是根据输入内容返回唯一哈希值的函数。对哈希函数的输入内容包括您的请求文本和秘密访问密钥。哈希函数返回哈希值，您将该值包含在请求中，作为签名。该签名是您的请求的 Authorization 标头的一部分。

收到您的请求后，AWS Storage Gateway 使用与您用于对该请求进行签名的相同哈希函数和输入重新计算签名。如果所得签名与该请求中的签名相匹配，则 AWS Storage Gateway 处理该请求。否则，请求将被拒绝。

AWS Storage Gateway 支持使用 AWS 签名版本 4 进行身份验证。计算签名的过程可分为三个任务：

实例签名计算

下例演练为 ListGateways 创建签名的详细步骤。该示例可用作核查您的签名计算方法的参考。其他参考计算方法包含在 Amazon Web Services 词汇表的签名版本 4 测试套件中。

示例假定以下各项：

通用请求语法 (包括 JSON 正文) 为：

POST / HTTP/1.1
Host: storagegateway.us-east-2.amazonaws.com
x-amz-Date: 20120910T000000Z
Authorization: SignatureToBeCalculated
Content-type: application/x-amz-json-1.1
x-amz-target: StorageGateway_20120630.ListGateways
{}

为计算的请求规范格式为：

POST
/

content-type:application/x-amz-json-1.1
host:storagegateway.us-east-2.amazonaws.com
x-amz-date:20120910T000000Z
x-amz-target:StorageGateway_20120630.ListGateways

content-type;host;x-amz-date;x-amz-target
44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a

规范请求的最后一行是请求正文的哈希值。另外，请注意规范请求的第三行是空的。这是因为此 API (或任何 AWS Storage Gateway API) 没有查询参数。

用于的待签字符串是：

AWS4-HMAC-SHA256
20120910T000000Z
20120910/us-east-2/storagegateway/aws4_request
92c0effa6f9224ac752ca179a04cecbede3038b0959666a8160ab452c9e51b3e

用来签名的请求的第一行是算法，第二行是时间戳，第三行是证书范围，最后一行是任务 1 中规范请求的哈希值。

对于 ，派生密钥可表示为：

derived key = HMAC(HMAC(HMAC(HMAC("AWS4" + YourSecretAccessKey,"20120910"),"us-east-2"),"storagegateway"),"aws4_request")

如果使用秘密访问密钥 wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY，则计算出的签名为：

6d4c40b8f2257534dbdca9f326f147a0a7a419b63aff349d9d9c737c9a0f4c81

最终步骤是构造 Authorization 标头。对于示例访问密钥 AKIAIOSFODNN7EXAMPLE，标头 (为便于阅读，添加了换行符) 为：

Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20120910/us-east-2/storagegateway/aws4_request, 
SignedHeaders=content-type;host;x-amz-date;x-amz-target, 
Signature=6d4c40b8f2257534dbdca9f326f147a0a7a419b63aff349d9d9c737c9a0f4c81

错误响应

本部分提供有关 AWS Storage Gateway 错误的引用信息。这些错误以错误例外和操作错误代码表示。例如，如果请求签名存在问题，那么会由任何 API 响应返回错误例外 InvalidSignatureException。但是，仅为 ActivationKeyInvalidActivateGateway API 返回操作错误代码。

根据错误类型的情况，AWS Storage Gateway 可能只返回例外，或者同时返回例外和操作错误代码。错误响应 中显示了误差响应示例。

例外

下表列出了 AWS Storage Gateway API 例外。当 AWS Storage Gateway 操作返回错误响应时，响应正文中会包含这些例外之一。InternalServerError 和 InvalidGatewayRequestException 返回操作错误代码 (提供特定的操作错误代码的 操作错误代码 消息代码) 之一。

操作错误代码

下表显示的是 AWS Storage Gateway 操作错误代码和返回这些代码的 API 之间的映射。所有操作错误代码均与例外中所述的两个常规例外 InternalServerError 和 InvalidGatewayRequestException 中的一个一并返回。

错误响应

当存在错误时，响应头信息会包含：

错误响应的正文会包含有关错误出现的信息。下列错误响应示例显示的是所有错误响应中常见的响应元素的输出语法。

{
    "__type": "String",
    "message": "String",
    "error":
        { "errorCode": "String",
          "errorDetails": "String"
        }
}

下表介绍了前一语法中显示的 JSON 错误响应字段。

错误响应示例

如果您使用 DescribeStorediSCSIVolumes API 并指定不存在的网关 ARN 请求输入，那么会返回以下 JSON 正文。

{
  "__type": "InvalidGatewayRequestException",
  "message": "The specified volume was not found.",
  "error": {
    "errorCode": "VolumeNotFound"
  }
}

如果 AWS Storage Gateway 计算的签名不符合通过请求发送的签名，那么会返回如下 JSON 正文。

{  
  "__type": "InvalidSignatureException",  
  "message": "The request signature we calculated does not match the signature you provided." 
}  

AWS Storage Gateway 中的操作

有关 AWS Storage Gateway 操作的列表，请参阅 AWS Storage Gateway API Reference 中的操作。