API Reference for Storage Gateway - Amazon Storage Gateway
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon FSx File Gateway is no longer available to new customers. Existing customers of FSx File Gateway can continue to use the service normally. For capabilities similar to FSx File Gateway, visit this blog post.

API Reference for Storage Gateway

In addition to using the console, you can use the Amazon Storage Gateway API to programmatically configure and manage your gateways. This section describes the Amazon Storage Gateway operations, request signing for authentication and the error handling. For information about the regions and endpoints available for Storage Gateway, see Amazon Storage Gateway Endpoints and Quotas in the Amazon Web Services General Reference.

Note

You can also use the Amazon SDKs when developing applications with Storage Gateway. The Amazon SDKs for Java, .NET, and PHP wrap the underlying Storage Gateway API, simplifying your programming tasks. For information about downloading the SDK libraries, see Sample Code Libraries.

Amazon Storage Gateway Required Request Headers

This section describes the required headers that you must send with every POST request to Amazon Storage Gateway. You include HTTP headers to identify key information about the request including the operation you want to invoke, the date of the request, and information that indicates the authorization of you as the sender of the request. Headers are case insensitive and the order of the headers is not important.

The following example shows headers that are used in the ActivateGateway operation.

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

The following are the headers that must include with your POST requests to Amazon Storage Gateway. Headers shown below that begin with "x-amz" are Amazon-specific headers. All other headers listed are common header used in HTTP transactions.

Header Description
Authorization

The authorization header contains several of pieces of information about the request that allow Amazon Storage Gateway to determine if the request is a valid action for the requester. The format of this header is as follows (line breaks added for readability):

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

In the preceding syntax, you specify YourAccessKey, the year, month, and day (yyyymmdd), the region, and the CalculatedSignature. The format of the authorization header is dictated by the requirements of the Amazon V4 Signing process. The details of signing are discussed in the topic Signing Requests.

Content-Type

Use application/x-amz-json-1.1 as the content type for all requests to Amazon Storage Gateway.

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

Use the host header to specify the Amazon Storage Gateway endpoint where you send your request. For example, storagegateway.us-east-2.amazonaws.com is the endpoint for the US East (Ohio) region. For more information about the endpoints available for Amazon Storage Gateway, see Amazon Storage Gateway Endpoints and Quotas in the Amazon Web Services General Reference.

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

You must provide the time stamp in either the HTTP Date header or the AWS x-amz-date header. (Some HTTP client libraries don't let you set the Date header.) When an x-amz-date header is present, the Amazon Storage Gateway ignores any Date header during the request authentication. The x-amz-date format must be ISO8601 Basic in the YYYYMMDD'T'HHMMSS'Z' format. If both the Date and x-amz-date header are used, the format of the Date header does not have to be ISO8601.

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

This header specifies the version of the API and the operation that you are requesting. The target header values are formed by concatenating the API version with the API name and are in the following format.

x-amz-target: StorageGateway_APIversion.operationName

The operationName value (e.g. "ActivateGateway") can be found from the API list, API Reference for Storage Gateway.

Signing Requests

Storage Gateway requires that you authenticate every request you send by signing the request. To sign a request, you calculate a digital signature using a cryptographic hash function. A cryptographic hash is a function that returns a unique hash value based on the input. The input to the hash function includes the text of your request and your secret access key. The hash function returns a hash value that you include in the request as your signature. The signature is part of the Authorization header of your request.

After receiving your request, Storage Gateway recalculates the signature using the same hash function and input that you used to sign the request. If the resulting signature matches the signature in the request, Storage Gateway processes the request. Otherwise, the request is rejected.

Storage Gateway supports authentication using Amazon Signature Version 4. The process for calculating a signature can be broken into three tasks:

  • Task 1: Create a Canonical Request

    Rearrange your HTTP request into a canonical format. Using a canonical form is necessary because Storage Gateway uses the same canonical form when it recalculates a signature to compare with the one you sent.

  • Task 2: Create a String to Sign

    Create a string that you will use as one of the input values to your cryptographic hash function. The string, called the string to sign, is a concatenation of the name of the hash algorithm, the request date, a credential scope string, and the canonicalized request from the previous task. The credential scope string itself is a concatenation of date, region, and service information.

  • Task 3: Create a Signature

    Create a signature for your request by using a cryptographic hash function that accepts two input strings: your string to sign and a derived key. The derived key is calculated by starting with your secret access key and using the credential scope string to create a series of Hash-based Message Authentication Codes (HMACs).

Example Signature Calculation

The following example walks you through the details of creating a signature for ListGateways. The example could be used as a reference to check your signature calculation method.

The example assumes the following:

  • The time stamp of the request is "Mon, 10 Sep 2012 00:00:00" GMT.

  • The endpoint is the US East (Ohio) region.

The general request syntax (including the JSON body) is:

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

The canonical form of the request calculated for is:

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

The last line of the canonical request is the hash of the request body. Also, note the empty third line in the canonical request. This is because there are no query parameters for this API (or any Storage Gateway APIs).

The string to sign for is:

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

The first line of the string to sign is the algorithm, the second line is the time stamp, the third line is the credential scope, and the last line is a hash of the canonical request from Task 1.

For , the derived key can be represented as:

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

If the secret access key, wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY, is used, then the calculated signature is:

6d4c40b8f2257534dbdca9f326f147a0a7a419b63aff349d9d9c737c9a0f4c81

The final step is to construct the Authorization header. For the demonstration access key AKIAIOSFODNN7EXAMPLE, the header (with line breaks added for readability) is:

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

Error Responses

This section provides reference information about Amazon Storage Gateway errors. These errors are represented by an error exception and an operation error code. For example, the error exception InvalidSignatureException is returned by any API response if there is a problem with the request signature. However, the operation error code ActivationKeyInvalid is returned only for the ActivateGateway API.

Depending on the type of error, Storage Gateway may return only just an exception, or it may return both an exception and an operation error code. Examples of error responses are shown in the Error Responses.

Exceptions

The following table lists Amazon Storage Gateway API exceptions. When an Amazon Storage Gateway operation returns an error response, the response body contains one of these exceptions. The InternalServerError and InvalidGatewayRequestException return one of the operation error codes Operation Error Codes message codes that give the specific operation error code.

Exception Message HTTP Status Code
IncompleteSignatureException The specified signature is incomplete. 400 Bad Request
InternalFailure The request processing has failed due to some unknown error, exception or failure. 500 Internal Server Error
InternalServerError One of the operation error code messages Operation Error Codes. 500 Internal Server Error
InvalidAction The requested action or operation is invalid. 400 Bad Request
InvalidClientTokenId The X.509 certificate or Amazon Access Key ID provided does not exist in our records. 403 Forbidden
InvalidGatewayRequestException One of the operation error code messages in Operation Error Codes. 400 Bad Request
InvalidSignatureException The request signature we calculated does not match the signature you provided. Check your Amazon Access Key and signing method. 400 Bad Request
MissingAction The request is missing an action or operation parameter. 400 Bad Request
MissingAuthenticationToken The request must contain either a valid (registered) Amazon Access Key ID or X.509 certificate. 403 Forbidden
RequestExpired The request is past the expiration date or the request date (either with 15 minute padding), or the request date occurs more than 15 minutes in the future. 400 Bad Request
SerializationException An error occurred during serialization. Check that your JSON payload is well-formed. 400 Bad Request
ServiceUnavailable The request has failed due to a temporary failure of the server. 503 Service Unavailable
SubscriptionRequiredException The Amazon Access Key Id needs a subscription for the service. 400 Bad Request
ThrottlingException Rate exceeded. 400 Bad Request
TooManyRequests Too many requests. 429 Too Many Requests
UnknownOperationException An unknown operation was specified. Valid operations are listed in Storage Gateway API Actions. 400 Bad Request
UnrecognizedClientException The security token included in the request is invalid. 400 Bad Request
ValidationException The value of an input parameter is bad or out of range. 400 Bad Request

Operation Error Codes

The following table shows the mapping between Amazon Storage Gateway operation error codes and APIs that can return the codes. All operation error codes are returned with one of two general exceptions—InternalServerError and InvalidGatewayRequestException—described in Exceptions.

Operation Error Code Message Operations That Return this Error Code
ActivationKeyExpired The specified activation key has expired. ActivateGateway
ActivationKeyInvalid The specified activation key is invalid. ActivateGateway
ActivationKeyNotFound The specified activation key was not found. ActivateGateway
BandwidthThrottleScheduleNotFound The specified bandwidth throttle was not found. DeleteBandwidthRateLimit
CannotExportSnapshot The specified snapshot cannot be exported.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

InitiatorNotFound The specified initiator was not found. DeleteChapCredentials
DiskAlreadyAllocated The specified disk is already allocated.

AddCache

AddUploadBuffer

AddWorkingStorage

CreateStorediSCSIVolume

DiskDoesNotExist The specified disk does not exist.

AddCache

AddUploadBuffer

AddWorkingStorage

CreateStorediSCSIVolume

DiskSizeNotGigAligned The specified disk is not gigabyte-aligned.

CreateStorediSCSIVolume

DiskSizeGreaterThanVolumeMaxSize The specified disk size is greater than the maximum volume size. CreateStorediSCSIVolume
DiskSizeLessThanVolumeSize The specified disk size is less than the volume size. CreateStorediSCSIVolume
DuplicateCertificateInfo The specified certificate information is a duplicate. ActivateGateway
FileSystemAssociationEndpointConfigurationConflict

Existing File System Association endpoint configuration conflicts with specified configuration.

AssociateFileSystem
FileSystemAssociationEndpointIpAddressAlreadyInUse

The specified endpoint IP address is already in use.

AssociateFileSystem
FileSystemAssociationEndpointIpAddressMissing

File System Association Endpoint IP address is missing.

AssociateFileSystem
FileSystemAssociationNotFound

The specified file system association was not found.

UpdateFileSystemAssociation

DisassociateFileSystem

DescribeFileSystemAssociations

FileSystemNotFound

The specified file system was not found.

AssociateFileSystem
GatewayInternalError A gateway internal error occurred.

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 The specified gateway is not connected.

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 The specified gateway was not found.

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 The specified gateway proxy network connection is busy.

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 An internal error occurred.

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 The specified request contains invalid parameters.

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 The local storage limit was exceeded.

AddCache

AddUploadBuffer

AddWorkingStorage

LunInvalid The specified LUN is invalid. CreateStorediSCSIVolume
MaximumVolumeCountExceeded The maximum volume count was exceeded.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

DescribeCachediSCSIVolumes

DescribeStorediSCSIVolumes

NetworkConfigurationChanged The gateway network configuration has changed.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

NotSupported The specified operation is not supported.

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 The specified gateway is out of date. ActivateGateway
SnapshotInProgressException The specified snapshot is in progress. DeleteVolume
SnapshotIdInvalid The specified snapshot is invalid.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

StagingAreaFull The staging area is full.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

TargetAlreadyExists The specified target already exists.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

TargetInvalid The specified target is invalid.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

DeleteChapCredentials

DescribeChapCredentials

UpdateChapCredentials

TargetNotFound The specified target was not found.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

DeleteChapCredentials

DescribeChapCredentials

DeleteVolume

UpdateChapCredentials

UnsupportedOperationForGatewayType The specified operation is not valid for the type of the gateway.

AddCache

AddWorkingStorage

CreateCachediSCSIVolume

CreateSnapshotFromVolumeRecoveryPoint

CreateStorediSCSIVolume

DeleteSnapshotSchedule

DescribeCache

DescribeCachediSCSIVolumes

DescribeStorediSCSIVolumes

DescribeUploadBuffer

DescribeWorkingStorage

ListVolumeRecoveryPoints

VolumeAlreadyExists The specified volume already exists.

CreateCachediSCSIVolume

CreateStorediSCSIVolume

VolumeIdInvalid The specified volume is invalid. DeleteVolume
VolumeInUse The specified volume is already in use. DeleteVolume
VolumeNotFound The specified volume was not found.

CreateSnapshot

CreateSnapshotFromVolumeRecoveryPoint

DeleteVolume

DescribeCachediSCSIVolumes

DescribeSnapshotSchedule

DescribeStorediSCSIVolumes

UpdateSnapshotSchedule

VolumeNotReady The specified volume is not ready.

CreateSnapshot

CreateSnapshotFromVolumeRecoveryPoint

Error Responses

When there is an error, the response header information contains:

  • Content-Type: application/x-amz-json-1.1

  • An appropriate 4xx or 5xx HTTP status code

The body of an error response contains information about the error that occurred. The following sample error response shows the output syntax of response elements common to all error responses.

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

The following table explains the JSON error response fields shown in the preceding syntax.

__type

One of the exceptions from Exceptions.

Type: String

error

Contains API-specific error details. In general errors (i.e., not specific to any API), this error information is not shown.

Type: Collection

errorCode

One of the operation error codes .

Type: String

errorDetails

This field is not used in the current version of the API.

Type: String

message

One of the operation error code messages.

Type: String

Error Response Examples

The following JSON body is returned if you use the DescribeStorediSCSIVolumes API and specify a gateway ARN request input that does not exist.

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

The following JSON body is returned if Storage Gateway calculates a signature that does not match the signature sent with a request.

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

Storage Gateway API Actions

For a list of Storage Gateway operations, see Actions in the Amazon Storage Gateway API Reference.