Storage Gateway 的 API 参考

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

Storage Gateway 必需的请求标头

本部分描述您每次向 Storage Gateway 发送 POST 请求时必须使用的标头。您将 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 APIs）没有查询参数。

的待签字符串是：

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

错误响应

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

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

异常

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

操作错误代码

下表显示了 Amazon Storage Gateway 操作错误代码和可以返回代码 APIs 的错误代码之间的映射。返回所有操作错误代码，包含异常中所述的两个一般异常（InternalServerError 和 InvalidGatewayRequestException）之一。

错误响应

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

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

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

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

错误响应示例

如果您使用 DescribeStoredi SCSIVolumes 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 Gateway API 参考》中的操作。