AWS Storage Gateway
User Guide (API Version 2013-06-30)
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。请点击 Amazon AWS 入门,可查看中国地区的具体差异

AWS Storage Gateway 的 API 参考

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

注意

利用 AWS Storage Gateway 开发应用程序时,您也可以使用 AWS 开发工具包。适用于 Java、.Net 和 PHP 的 AWS 开发工具包包含底层的 AWS Storage Gateway API,从而简化您的编程任务。有关下载开发工具包库的信息,请参阅示例代码库

AWS Storage Gateway 必需的请求标头

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

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

Copy
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

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

标头 描述
Authorization

授权标头包含有关请求的数种信息,这些信息可以让 AWS Storage Gateway 确定请求是否为请求者的有效操作。该标头的格式如下所示 (为便于阅读,添加了换行符):

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

在前面的语法中,您指定YourAccessKey,年份、月份和日期, (yyyymmdd)、区域CalculatedSignature。授权标头的格式由 AWS V4 签名过程的要求规定。签名的详细信息在主题 签名请求 中进行讨论。

Content-Type

application/x-amz-json-1.1 用作所有发往 AWS Storage Gateway 的请求的内容类型。

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

使用主机标头指定向其发送请求的 AWS Storage Gateway 网关终端节点。例如,storagegateway.us-east-2.amazonaws.com 是 美国东部(俄亥俄州) 区域的终端节点。有关 AWS Storage Gateway 可用终端节点的更多信息,请参阅区域和终端节点

Copy
Host: storagegateway.region.amazonaws.com
x-amz-date

您必须在 HTTP Date 标头或 AWS x-amz-date 标头中提供时间戳。(部分 HTTP 客户端库文件不允许您设置Date标头。)当x-amz-date存在时,AWS Storage Gateway 会在请求验证期间忽略任何Date标头。x-amz-date 格式必须为 YYYYMMDD'T'HHMMSS'Z' 格式的 ISO8601 Basic。如果同时使用了Datex-amz-date标头,日期标头的格式就不必是 ISO8601。

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

该标头指定 API 的版本以及您要请求的操作。目标标头值通过结合 API 版本和 API 名称而形成,其格式如下。

Copy
x-amz-target: StorageGateway_APIversion.operationName

operationName值 (例如“ActivateGateway”) 可从 API 列表AWS Storage Gateway 的 API 参考中找到。

签名请求

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

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

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

  • 任务 1:创建规范请求

    将您的 HTTP 请求重新排列为规范格式。必须使用规范格式,因为 AWS Storage Gateway 在重新计算签名以与您发送的签名进行比较时使用同一规范格式。

  • 任务 2:创建待签字符串

    创建一个字符串,将该字符串用作您的加密哈希函数输入值中的一项。该字符串称为“待签字符串”,是哈希算法名称、请求日期、凭证范围字符串以及来自上一任务的规范化请求的结合。证书范围字符串本身是日期、区域和服务信息的结合。

  • 任务 3:创建签名

    使用加密哈希函数为您的请求创建签名,该函数接受两种输入字符串:待签字符串派生密钥派生密钥的计算方法是,以您的秘密访问密钥为开始并使用凭证范围字符串来创建基于哈西的消息验证码 (HMAC)。

实例签名计算

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

示例假定以下各项:

  • 请求的时间戳为“Mon, 10 Sep 2012 00:00:00”GMT。

  • 终端节点为 美国东部(俄亥俄州) 区域。

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

Copy
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 {}

计算的请求规范格式为:

Copy
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) 没有查询参数。

用于待签字符串是:

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

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

对于 派生密钥可表示为:

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

如果使用秘密访问密钥 wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY,那么计算出的签名就是:

Copy
6d4c40b8f2257534dbdca9f326f147a0a7a419b63aff349d9d9c737c9a0f4c81

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

Copy
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 操作返回错误响应时,响应正文中会包含这些例外之一。InternalServerErrorInvalidGatewayRequestException 返回操作错误代码 (提供特定的操作错误代码的 操作错误代码 消息代码) 之一。

例外 消息 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 无法导出指定的快照。

CreateCachediSCSIVolume

CreateStorediSCSIVolume

InitiatorNotFound 找不到指定的启动程序。 DeleteChapCredentials
DiskAlreadyAllocated 指定的磁盘已分配。

AddCache

AddUploadBuffer

AddWorkingStorage

CreateStorediSCSIVolume

DiskDoesNotExist 指定的磁盘不存在。

AddCache

AddUploadBuffer

AddWorkingStorage

CreateStorediSCSIVolume

DiskSizeNotGigAligned 指定的磁盘没有以 GB 为整单位。

CreateStorediSCSIVolume

DiskSizeGreaterThanVolumeMaxSize 指定的磁盘大小超过最高卷大小。 CreateStorediSCSIVolume
DiskSizeLessThanVolumeSize 指定的磁盘大小低于最高卷大小。 CreateStorediSCSIVolume
DuplicateCertificateInfo 指定的证书信息是副本。 ActivateGateway
GatewayInternalError 出现网关内部错误。

AddCache

AddUploadBuffer

AddWorkingStorage

CreateCachediSCSIVolume

CreateSnapshot

CreateStorediSCSIVolume

CreateSnapshotFromVolumeRecoveryPoint

DeleteBandwidthRateLimit

DeleteChapCredentials

DeleteVolume

DescribeBandwidthRateLimit

DescribeCache

DescribeCachediSCSIVolumes

DescribeChapCredentials

DescribeGatewayInformation

DescribeMaintenanceStartTime

DescribeSnapshotSchedule

DescribeStorediSCSIVolumes

DescribeWorkingStorage

ListLocalDisks

ListVolumes

ListVolumeRecoveryPoints

ShutdownGateway

StartGateway

UpdateBandwidthRateLimit

UpdateChapCredentials

UpdateMaintenanceStartTime

UpdateGatewaySoftwareNow

UpdateSnapshotSchedule

GatewayNotConnected 没有连接指定的网关。

AddCache

AddUploadBuffer

AddWorkingStorage

CreateCachediSCSIVolume

CreateSnapshot

CreateStorediSCSIVolume

CreateSnapshotFromVolumeRecoveryPoint

DeleteBandwidthRateLimit

DeleteChapCredentials

DeleteVolume

DescribeBandwidthRateLimit

DescribeCache

DescribeCachediSCSIVolumes

DescribeChapCredentials

DescribeGatewayInformation

DescribeMaintenanceStartTime

DescribeSnapshotSchedule

DescribeStorediSCSIVolumes

DescribeWorkingStorage

ListLocalDisks

ListVolumes

ListVolumeRecoveryPoints

ShutdownGateway

StartGateway

UpdateBandwidthRateLimit

UpdateChapCredentials

UpdateMaintenanceStartTime

UpdateGatewaySoftwareNow

UpdateSnapshotSchedule

GatewayNotFound 找不到指定的网关。

AddCache

AddUploadBuffer

AddWorkingStorage

CreateCachediSCSIVolume

CreateSnapshot

CreateSnapshotFromVolumeRecoveryPoint

CreateStorediSCSIVolume

DeleteBandwidthRateLimit

DeleteChapCredentials

DeleteGateway

DeleteVolume

DescribeBandwidthRateLimit

DescribeCache

DescribeCachediSCSIVolumes

DescribeChapCredentials

DescribeGatewayInformation

DescribeMaintenanceStartTime

DescribeSnapshotSchedule

DescribeStorediSCSIVolumes

DescribeWorkingStorage

ListLocalDisks

ListVolumes

ListVolumeRecoveryPoints

ShutdownGateway

StartGateway

UpdateBandwidthRateLimit

UpdateChapCredentials

UpdateMaintenanceStartTime

UpdateGatewaySoftwareNow

UpdateSnapshotSchedule

GatewayProxyNetworkConnectionBusy 指定的网关代理网络连接忙。

AddCache

AddUploadBuffer

AddWorkingStorage

CreateCachediSCSIVolume

CreateSnapshot

CreateSnapshotFromVolumeRecoveryPoint

CreateStorediSCSIVolume

DeleteBandwidthRateLimit

DeleteChapCredentials

DeleteVolume

DescribeBandwidthRateLimit

DescribeCache

DescribeCachediSCSIVolumes

DescribeChapCredentials

DescribeGatewayInformation

DescribeMaintenanceStartTime

DescribeSnapshotSchedule

DescribeStorediSCSIVolumes

DescribeWorkingStorage

ListLocalDisks

ListVolumes

ListVolumeRecoveryPoints

ShutdownGateway

StartGateway

UpdateBandwidthRateLimit

UpdateChapCredentials

UpdateMaintenanceStartTime

UpdateGatewaySoftwareNow

UpdateSnapshotSchedule

InternalError 出现内部错误。

ActivateGateway

AddCache

AddUploadBuffer

AddWorkingStorage

CreateCachediSCSIVolume

CreateSnapshot

CreateSnapshotFromVolumeRecoveryPoint

CreateStorediSCSIVolume

DeleteBandwidthRateLimit

DeleteChapCredentials

DeleteGateway

DeleteVolume

DescribeBandwidthRateLimit

DescribeCache

DescribeCachediSCSIVolumes

DescribeChapCredentials

DescribeGatewayInformation

DescribeMaintenanceStartTime

DescribeSnapshotSchedule

DescribeStorediSCSIVolumes

DescribeWorkingStorage

ListLocalDisks

ListGateways

ListVolumes

ListVolumeRecoveryPoints

ShutdownGateway

StartGateway

UpdateBandwidthRateLimit

UpdateChapCredentials

UpdateMaintenanceStartTime

UpdateGatewayInformation

UpdateGatewaySoftwareNow

UpdateSnapshotSchedule

InvalidParameters 指定的请求中包含无效参数。

ActivateGateway

AddCache

AddUploadBuffer

AddWorkingStorage

CreateCachediSCSIVolume

CreateSnapshot

CreateSnapshotFromVolumeRecoveryPoint

CreateStorediSCSIVolume

DeleteBandwidthRateLimit

DeleteChapCredentials

DeleteGateway

DeleteVolume

DescribeBandwidthRateLimit

DescribeCache

DescribeCachediSCSIVolumes

DescribeChapCredentials

DescribeGatewayInformation

DescribeMaintenanceStartTime

DescribeSnapshotSchedule

DescribeStorediSCSIVolumes

DescribeWorkingStorage

ListLocalDisks

ListGateways

ListVolumes

ListVolumeRecoveryPoints

ShutdownGateway

StartGateway

UpdateBandwidthRateLimit

UpdateChapCredentials

UpdateMaintenanceStartTime

UpdateGatewayInformation

UpdateGatewaySoftwareNow

UpdateSnapshotSchedule

LocalStorageLimitExceeded 已超过本地存储限制。

AddCache

AddUploadBuffer

AddWorkingStorage

LunInvalid 指定的 LUN 无效。 CreateStorediSCSIVolume
MaximumVolumeCountExceeded 已超过最大卷计数。

CreateCachediSCSIVolume

CreateStorediSCSIVolume

DescribeCachediSCSIVolumes

DescribeStorediSCSIVolumes

NetworkConfigurationChanged 已更改网关网络配置。

CreateCachediSCSIVolume

CreateStorediSCSIVolume

NotSupported 不支持指定的操作。

ActivateGateway

AddCache

AddUploadBuffer

AddWorkingStorage

CreateCachediSCSIVolume

CreateSnapshot

CreateSnapshotFromVolumeRecoveryPoint

CreateStorediSCSIVolume

DeleteBandwidthRateLimit

DeleteChapCredentials

DeleteGateway

DeleteVolume

DescribeBandwidthRateLimit

DescribeCache

DescribeCachediSCSIVolumes

DescribeChapCredentials

DescribeGatewayInformation

DescribeMaintenanceStartTime

DescribeSnapshotSchedule

DescribeStorediSCSIVolumes

DescribeWorkingStorage

ListLocalDisks

ListGateways

ListVolumes

ListVolumeRecoveryPoints

ShutdownGateway

StartGateway

UpdateBandwidthRateLimit

UpdateChapCredentials

UpdateMaintenanceStartTime

UpdateGatewayInformation

UpdateGatewaySoftwareNow

UpdateSnapshotSchedule

OutdatedGateway 指定的网关已过时。 ActivateGateway
SnapshotInProgressException 指定的快照在进行中。 DeleteVolume
SnapshotIdInvalid 指定的快照无效。

CreateCachediSCSIVolume

CreateStorediSCSIVolume

StagingAreaFull 暂存区域已满。

CreateCachediSCSIVolume

CreateStorediSCSIVolume

TargetAlreadyExists 已存在指定的目标。

CreateCachediSCSIVolume

CreateStorediSCSIVolume

TargetInvalid 指定的目标无效。

CreateCachediSCSIVolume

CreateStorediSCSIVolume

DeleteChapCredentials

DescribeChapCredentials

UpdateChapCredentials

TargetNotFound 找不到指定的目标。

CreateCachediSCSIVolume

CreateStorediSCSIVolume

DeleteChapCredentials

DescribeChapCredentials

DeleteVolume

UpdateChapCredentials

UnsupportedOperationForGatewayType 对于这类网关,指定的操作无效。

AddCache

AddWorkingStorage

CreateCachediSCSIVolume

CreateSnapshotFromVolumeRecoveryPoint

CreateStorediSCSIVolume

DeleteSnapshotSchedule

DescribeCache

DescribeCachediSCSIVolumes

DescribeStorediSCSIVolumes

DescribeUploadBuffer

DescribeWorkingStorage

ListVolumeRecoveryPoints

VolumeAlreadyExists 已存在指定的卷。

CreateCachediSCSIVolume

CreateStorediSCSIVolume

VolumeIdInvalid 指定的卷无效。 DeleteVolume
VolumeInUse 指定的卷已在使用中。 DeleteVolume
VolumeNotFound 找不到指定的卷。

CreateSnapshot

CreateSnapshotFromVolumeRecoveryPoint

DeleteVolume

DescribeCachediSCSIVolumes

DescribeSnapshotSchedule

DescribeStorediSCSIVolumes

UpdateSnapshotSchedule

VolumeNotReady 指定的卷没有准备好。

CreateSnapshot

CreateSnapshotFromVolumeRecoveryPoint

错误响应

当存在错误时,响应头信息会包含:

  • 内容类型:application/x-amz-json-1.1

  • 适当的 4xx5xx HTTP 状态码

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

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

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

__类型

例外 中的例外之一。

类型:字符串

错误

包含特定于 API 的错误详细信息。在常规的 (即不特定于任何 API 的) 错误中,不显示这个误差信息。

类型:集合

errorCode

一个操作错误代码 .

类型:字符串

errorDetails

此字段不在 API 的当前版本中使用。

类型:字符串

消息

一个操作错误代码消息.

类型:字符串

错误响应示例

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

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

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

Copy
{   "__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 中的操作