Storage Gateway API 参考

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

Storage Gateway 所需的请求标头

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

以下示例显示了ActivateGateway操作中使用的标头。

POST / HTTP/1.1 
Host: storagegateway.us-east-2.amazonaws.com
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

以下是向Storage Gateway 发出的 POST 请求中必须包含的标头。下面显示的以 “x-amz” 开头的标头是Amazon特定的标头。列出的其他所有标头均为 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

签名请求

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

收到请求后，Storage Gateway 会使用您在签名请求时使用的同一哈希函数和输入重新计算签名。如果得出的签名与请求中的签名相匹配，Storage Gateway 会处理请求。否则，请求将被拒绝。

Storage Gateway 支持使用Amazon签名版本 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（或任何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/bPxRfi CYEXAMPLEKEY，则计算出的签名为：

6d4c40b8f2257534dbdca9f326f147a0a7a419b63aff349d9d9c737c9a0f4c81

最终步骤是构造 Authorization 标头。对于演示访问密钥 AKIAIOSFODNN7EXAMPLE，标头（为便于阅读而添加了换行符）为：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

错误响应

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

根据错误的类型，Storage Gateway 可能仅返回异常，也可能返回异常和操作错误代码。错误响应 中显示了误差响应示例。

异常

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

操作错误代码

下表显示的是 Amazon Storage Gateway 操作错误代码和返回这些代码的 API 之间的映射。将返回所有操作错误代码，但有两个一般异常中的一个，InvalidGatewayRequestException如中所述 —InternalServerError 和异常。

错误响应

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

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

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

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

错误响应示例

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

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

如果 Storage Gateway 计算的签名与请求中发送的签名不匹配，则返回以下 JSON 正文。

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

Storage Gateway 中的操作

有关Storage Gateway 操作的列表，请参阅 Amazon Storage GatewayAPI 参考中的操作。