本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
AWS Storage Gateway 的 API 参考
除使用控制台外,您还可以使用 AWS Storage Gateway API,以编程方式配置并管理网关。本部分描述 AWS Storage Gateway 操作、为身份验证进行的请求签名和错误处理。有关可用于 AWS Storage Gateway 的区域和终端节点的信息,请参阅 AWS General Reference 中的 AWS Storage Gateway 终端节点和配额。
利用 AWS Storage Gateway 开发应用程序时,您也可以使用 AWS 开发工具包。适用于 Java、.Net 和 PHP 的 AWS 开发工具包包含底层的
AWS Storage Gateway API,从而简化您的编程任务。有关下载开发工具包库的信息,请参阅示例代码库
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 |
授权标头包含有关请求的数种信息,这些信息可以让 AWS Storage Gateway 确定请求是否为请求者的有效操作。该标头的格式如下所示 (为便于阅读,添加了换行符):
在前面的语法中,您指定YourAccessKey,年份、月份和日期, (yyyymmdd)、区域 和 CalculatedSignature。授权标头的格式由 AWS V4 签名过程的要求规定。签名的详细信息在主题 签名请求 中进行讨论。 |
Content-Type |
将
|
Host |
使用主机标头指定向其发送请求的 AWS Storage Gateway 网关终端节点。例如,
|
x-amz-date |
您必须在 HTTP
|
x-amz-target |
该标头指定 API 的版本以及您要请求的操作。目标标头值通过结合 API 版本和 API 名称而形成,其格式如下。
operationName 值(如“ActivateGateway”)可从以下 API 列表中找到:AWS Storage Gateway 的 API 参考。 |
签名请求
AWS Storage Gateway 要求通过对请求进行签名,验证所发送的每个请求的身份。您使用加密哈希函数计算数字签名,从而对请求签名。加密哈西是根据输入内容返回唯一哈希值的函数。对哈希函数的输入内容包括您的请求文本和秘密访问密钥。哈希函数返回哈希值,您将该值包含在请求中,作为签名。该签名是您的请求的
Authorization
标头的一部分。
收到您的请求后,AWS Storage Gateway 使用与您用于对该请求进行签名的相同哈希函数和输入重新计算签名。如果所得签名与该请求中的签名相匹配,则 AWS Storage Gateway 处理该请求。否则,请求将被拒绝。
AWS Storage Gateway 支持使用 AWS 签名版本 4 进行身份验证。计算签名的过程可分为三个任务:
-
将您的 HTTP 请求重新排列为规范格式。必须使用规范格式,因为 AWS Storage Gateway 在重新计算签名以与您发送的签名进行比较时使用同一规范格式。
-
创建一个字符串,将该字符串用作您的加密哈希函数输入值中的一项。该字符串称为“待签字符串”,是哈希算法名称、请求日期、凭证范围字符串以及来自上一任务的规范化请求的结合。证书范围字符串本身是日期、区域和服务信息的结合。
-
使用加密哈希函数为您的请求创建签名,该函数接受两种输入字符串:待签字符串和派生密钥。派生密钥的计算方法是,以您的秘密访问密钥为开始并使用凭证范围字符串来创建基于哈西的消息验证码 (HMAC)。
实例签名计算
下例演练为 ListGateways 创建签名的详细步骤。该示例可用作核查您的签名计算方法的参考。其他参考计算方法包含在 Amazon Web Services 词汇表的签名版本 4 测试套件中。
示例假定以下各项:
-
请求的时间戳为“Mon, 10 Sep 2012 00:00:00”GMT。
-
终端节点为 美国东部(俄亥俄州) 区域。
通用请求语法 (包括 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
。但是,仅为 ActivationKeyInvalid
ActivateGateway API 返回操作错误代码。
根据错误类型的情况,AWS Storage Gateway 可能只返回例外,或者同时返回例外和操作错误代码。错误响应 中显示了误差响应示例。
例外
下表列出了 AWS Storage Gateway API 例外。当 AWS Storage Gateway 操作返回错误响应时,响应正文中会包含这些例外之一。InternalServerError
和 InvalidGatewayRequestException
返回操作错误代码 (提供特定的操作错误代码的 操作错误代码 消息代码) 之一。
例外 | 消息 | HTTP 状态代码 |
---|---|---|
IncompleteSignatureException |
指定的签名不完全。 | 400 错误请求 |
InternalFailure |
由于某些未知错误、异常或故障导致请求处理失败。 | 500 内部服务器错误 |
InternalServerError |
一个操作错误代码消息操作错误代码。 | 500 内部服务器错误 |
InvalidAction |
所请求的操作或操作无效。 | 400 错误请求 |
InvalidClientTokenId |
在我们的记录中没有所提供的 X.509 证书或 AWS 访问密钥 ID。 | 403 禁止访问 |
InvalidGatewayRequestException |
操作错误代码 中的操作错误代码消息之一。 | 400 错误请求 |
InvalidSignatureException |
我们计算出的请求签名与您提供的签名不匹配。请检查您的 AWS 秘密访问密钥和签名方法。 | 400 错误请求 |
MissingAction |
请求中遗漏了一个操作或运行参数。 | 400 错误请求 |
MissingAuthenticationToken |
请求中必须包含有效的 (已注册的) AWS 访问密钥 ID 或 X.509 证书。 | 403 禁止访问 |
RequestExpired |
请求超过有效期或请求时间 (或用 15 分钟填补),或将来发送请求的时间超过 15 分钟。 | 400 错误请求 |
SerializationException |
序列化期间出现错误。查看您的 JSON 负载结构是否良好。 | 400 错误请求 |
ServiceUnavailable |
由于服务器发生临时故障而导致请求失败。 | 503 服务不可用 |
SubscriptionRequiredException |
AWS 访问密钥 Id 需要订阅产品。 | 400 错误请求 |
ThrottlingException |
费率已超。 | 400 错误请求 |
UnknownOperationException |
指定了未知操作。AWS Storage Gateway 中的操作 中列出了有效操作。 | 400 错误请求 |
UnrecognizedClientException |
请求中包含的安全令牌无效。 | 400 错误请求 |
ValidationException |
输入参数的值不正确或者超出范围。 | 400 错误请求 |
操作错误代码
下表显示的是 AWS Storage Gateway 操作错误代码和返回这些代码的 API 之间的映射。所有操作错误代码均与例外中所述的两个常规例外 InternalServerError
和 InvalidGatewayRequestException
中的一个一并返回。
操作错误代码 | 消息 | 返回此错误代码的操作 |
---|---|---|
ActivationKeyExpired |
指定的激活密钥已过期。 | ActivateGateway |
ActivationKeyInvalid |
指定的激活密钥无效。 | ActivateGateway |
ActivationKeyNotFound |
找不到指定的激活密钥。 | ActivateGateway |
BandwidthThrottleScheduleNotFound |
找不到指定的带宽限制。 | DeleteBandwidthRateLimit |
CannotExportSnapshot |
无法导出指定的快照。 | |
InitiatorNotFound |
找不到指定的启动程序。 | DeleteChapCredentials |
DiskAlreadyAllocated |
指定的磁盘已分配。 | |
DiskDoesNotExist |
指定的磁盘不存在。 | |
DiskSizeNotGigAligned |
指定的磁盘没有以 GB 为整单位。 | |
DiskSizeGreaterThanVolumeMaxSize |
指定的磁盘大小超过最高卷大小。 | CreateStorediSCSIVolume |
DiskSizeLessThanVolumeSize |
指定的磁盘大小低于最高卷大小。 | CreateStorediSCSIVolume |
DuplicateCertificateInfo |
指定的证书信息是副本。 | ActivateGateway |
GatewayInternalError |
出现网关内部错误。 | |
GatewayNotConnected |
没有连接指定的网关。 | |
GatewayNotFound |
找不到指定的网关。 | |
GatewayProxyNetworkConnectionBusy |
指定的网关代理网络连接忙。 | |
InternalError |
出现内部错误。 | |
InvalidParameters |
指定的请求中包含无效参数。 | |
LocalStorageLimitExceeded |
已超过本地存储限制。 | |
LunInvalid |
指定的 LUN 无效。 | CreateStorediSCSIVolume |
MaximumVolumeCountExceeded |
已超过最大卷计数。 | |
NetworkConfigurationChanged |
已更改网关网络配置。 | |
NotSupported |
不支持指定的操作。 | |
OutdatedGateway |
指定的网关已过时。 | ActivateGateway |
SnapshotInProgressException |
指定的快照在进行中。 | DeleteVolume |
SnapshotIdInvalid |
指定的快照无效。 | |
StagingAreaFull |
暂存区域已满。 | |
TargetAlreadyExists |
已存在指定的目标。 | |
TargetInvalid |
指定的目标无效。 | |
TargetNotFound |
找不到指定的目标。 | |
UnsupportedOperationForGatewayType |
对于这类网关,指定的操作无效。 | |
VolumeAlreadyExists |
已存在指定的卷。 | |
VolumeIdInvalid |
指定的卷无效。 | DeleteVolume |
VolumeInUse |
指定的卷已在使用中。 | DeleteVolume |
VolumeNotFound |
找不到指定的卷。 | |
VolumeNotReady |
指定的卷没有准备好。 |
错误响应
当存在错误时,响应头信息会包含:
-
内容类型:application/x-amz-json-1.1
-
适当的
4xx
或5xx
HTTP 状态码
错误响应的正文会包含有关错误出现的信息。下列错误响应示例显示的是所有错误响应中常见的响应元素的输出语法。
{ "__type": "String", "message": "String", "error": { "errorCode": "String", "errorDetails": "String" } }
下表介绍了前一语法中显示的 JSON 错误响应字段。
- __type
-
例外 中的例外之一。
类型:字符串
- error
-
包含特定于 API 的错误详细信息。在常规的 (即不特定于任何 API 的) 错误中,不显示这个误差信息。
类型:集合
- errorCode
-
其中一个操作错误代码。
类型:字符串
- errorDetails
-
此字段不在 API 的当前版本中使用。
类型:字符串
- message
-
一个操作错误代码消息。
类型:字符串
错误响应示例
如果您使用 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 中的操作。