本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
Storage Gateway 的 API 参考
除了使用控制台外,您还可以使用 Amazon Storage Gateway API 以编程方式配置和管理您的网关。本节介绍 Amazon Storage Gateway 操作、身份验证请求签名和错误处理。有关 Storage Gateway 可用的区域和端点的信息,请参阅《Amazon Web Services 一般参考》中的 Amazon Storage Gateway 端点和配额。
注意
在开发应用程序 Amazon SDKs 时,也可以使用 Amazon Storage Gateway。 Amazon SDKs 适用于 Java、.NET 和 PHP 的 API 封装了底层 Amazon Storage Gateway API,从而简化了您的编程任务。有关下载开发工具包库的信息,请参阅示例代码库
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 |
授权标头包含有关请求的数种信息,这些信息可以让 Storage Gateway 确定请求是否为请求者的有效操作。该标头的格式如下所示 (为便于阅读,添加了换行符):
在前面的语法中,您可以指定YourAccessKey年、月和日 (yyyymmdd)、区域和。CalculatedSignature授权标头的格式由 Amazon V4 签名过程的要求决定。签名的详细信息在主题 对请求进行签名 中进行讨论。 |
Content-Type |
将
|
Host |
使用主机标头指定向其发送请求的 Storage Gateway 网关端点。例如,
|
x-amz-date |
您必须在 HTTP
|
x-amz-target |
该标头指定 API 的版本以及您要请求的操作。目标标头值通过结合 API 版本和 API 名称而形成,其格式如下。
操作名称值(例如 ActivateGateway “”)可以从 API 列表中找到。Storage Gateway 的 API 参考 |
对请求进行签名
Storage Gateway 要求通过对请求进行签名,验证所发送的每个请求的身份。您使用加密哈希函数计算数字签名,从而对请求签名。加密哈西是根据输入内容返回唯一哈希值的函数。对哈希函数的输入内容包括您的请求文本和秘密访问密钥。哈希函数返回哈希值,您将该值包含在请求中,作为签名。该签名是您的请求的 Authorization
标头的一部分。
在收到您的请求后,Storage Gateway 将使用您用于对该请求进行签名的同一哈希函数和输入重新计算签名。如果所得签名与该请求中的签名相匹配,则 Storage Gateway 处理该请求。否则,请求将被拒绝。
Storage Gateway 支持使用 Amazon 签名版本 4 进行身份验证。计算签名的过程可分为三个任务:
-
将您的 HTTP 请求重新排列为规范格式。必须使用规范格式,因为 Storage Gateway 在重新计算签名以与您发送的签名进行比较时使用同一规范格式。
-
创建一个字符串,将该字符串用作您的加密哈希函数输入值中的一项。该字符串称为待签字符串,是哈希算法名称、请求日期、凭证范围字符串以及来自上一任务的规范化请求的结合。凭证范围字符串本身是日期、区域和服务信息的结合。
-
使用加密哈希函数为您的请求创建签名,该函数接受两种输入字符串:待签字符串和派生密钥。派生密钥的计算方法是从您的私有访问密钥开始,然后使用凭证范围字符串创建一系列基于哈希的消息身份验证码 () HMACs。
实例签名计算
以下示例引导您了解为 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(或任何 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
返回操作错误代码 (提供特定的操作错误代码的 操作错误代码 消息代码) 之一。
例外 | 消息 | HTTP 状态代码 |
---|---|---|
IncompleteSignatureException |
指定的签名不完全。 | 400 错误请求 |
InternalFailure |
由于某些未知错误、异常或故障导致请求处理失败。 | 500 内部服务器错误 |
InternalServerError |
一个操作错误代码消息操作错误代码。 | 500 内部服务器错误 |
InvalidAction |
请求的操作无效。 | 400 错误请求 |
InvalidClientTokenId |
我们的记录中不存在提供的 X.509 证书或 Amazon 访问密钥 ID。 | 403 禁止访问 |
InvalidGatewayRequestException |
操作错误代码 中的操作错误代码消息之一。 | 400 错误请求 |
InvalidSignatureException |
我们计算出的请求签名与您提供的签名不匹配。检查您的 Amazon 访问密钥和签名方法。 | 400 错误请求 |
MissingAction |
请求中遗漏了一个操作或运行参数。 | 400 错误请求 |
MissingAuthenticationToken |
请求必须包含有效(已注册的) Amazon 访问密钥 ID 或 X.509 证书。 | 403 禁止访问 |
RequestExpired |
请求超过有效期或请求时间 (或用 15 分钟填补),或将来发送请求的时间超过 15 分钟。 | 400 错误请求 |
SerializationException |
序列化期间出现错误。查看您的 JSON 负载结构是否良好。 | 400 错误请求 |
ServiceUnavailable |
由于服务器发生临时故障而导致请求失败。 | 503 服务不可用 |
SubscriptionRequiredException |
Amazon 访问密钥 ID 需要订阅该服务。 | 400 错误请求 |
ThrottlingException |
费率已超。 | 400 错误请求 |
TooManyRequests |
过多请求。 | 429 请求过多 |
UnknownOperationException |
指定了未知操作。Storage Gateway 中的操作 中列出了有效操作。 | 400 错误请求 |
UnrecognizedClientException |
请求中包含的安全令牌无效。 | 400 错误请求 |
ValidationException |
输入参数的值不正确或者超出范围。 | 400 错误请求 |
操作错误代码
下表显示了 Amazon Storage Gateway 操作错误代码和可以返回代码 APIs 的错误代码之间的映射。返回所有操作错误代码,包含异常中所述的两个一般异常(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 |
指定的卷没有准备好。 |
错误响应
当存在错误时,响应头信息会包含:
-
内容类型:应用程序/ -1.1 x-amz-json
-
适当的
4xx
或5xx
HTTP 状态码
错误响应的正文会包含有关错误出现的信息。下列错误响应示例显示的是所有错误响应中常见的响应元素的输出语法。
{ "__type": "String", "message": "String", "error": { "errorCode": "String", "errorDetails": "String" } }
下表介绍了前一语法中显示的 JSON 错误响应字段。
- __type
-
异常 中的例外之一。
类型:字符串
- error
-
包含特定于 API 的错误详细信息。在常规的 (即不特定于任何 API 的) 错误中,不显示这个误差信息。
类型:集合
- errorCode
-
其中一个操作错误代码。
类型:字符串
- errorDetails
-
此字段不在 API 的当前版本中使用。
类型:字符串
- message
-
一个操作错误代码消息。
类型:字符串
错误响应示例
如果您使用 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 参考》中的操作。