API Reference for Storage Gateway
In addition to using the console, you can use the AWS Storage Gateway API to programmatically configure and manage your gateways. This section describes the AWS Storage Gateway operations, request signing for authentication and the error handling. For information about the regions and endpoints available for Storage Gateway, see AWS Storage Gateway Endpoints and Quotas in the AWS General Reference.
Note
You can also use the AWS SDKs when developing applications with Storage Gateway. The AWS
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
Topics
AWS Storage Gateway Required Request Headers
This section describes the required headers that you must send with every POST request to AWS 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 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 AWS Storage Gateway. Headers shown below that begin with "x-amz" are AWS-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 AWS 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):
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 AWS V4 Signing process. The details of signing are discussed in the topic Signing Requests. |
Content-Type |
Use
|
Host |
Use the host header to specify the AWS Storage Gateway endpoint where you send
your request. For example,
|
x-amz-date |
You must provide the time stamp in either the HTTP
|
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.
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 AWS 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.
-
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:SignatureToBeCalculatedContent-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).
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 AWS 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 AWS Storage Gateway API exceptions. When an AWS 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 AWS 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 AWS 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) AWS 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 AWS 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 AWS 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. | |
InitiatorNotFound |
The specified initiator was not found. | DeleteChapCredentials |
DiskAlreadyAllocated |
The specified disk is already allocated. | |
DiskDoesNotExist |
The specified disk does not exist. | |
DiskSizeNotGigAligned |
The specified disk is not gigabyte-aligned. | |
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. |
|
| FileSystemNotFound |
The specified file system was not found. |
AssociateFileSystem |
GatewayInternalError |
A gateway internal error occurred. | |
GatewayNotConnected |
The specified gateway is not connected. | |
GatewayNotFound |
The specified gateway was not found. | |
GatewayProxyNetworkConnectionBusy |
The specified gateway proxy network connection is busy. | |
InternalError |
An internal error occurred. | |
InvalidParameters |
The specified request contains invalid parameters. | |
LocalStorageLimitExceeded |
The local storage limit was exceeded. | |
LunInvalid |
The specified LUN is invalid. | CreateStorediSCSIVolume |
MaximumVolumeCountExceeded |
The maximum volume count was exceeded. | |
NetworkConfigurationChanged |
The gateway network configuration has changed. | |
NotSupported |
The specified operation is not supported. | |
OutdatedGateway |
The specified gateway is out of date. | ActivateGateway |
SnapshotInProgressException |
The specified snapshot is in progress. | DeleteVolume |
SnapshotIdInvalid |
The specified snapshot is invalid. | |
StagingAreaFull |
The staging area is full. | |
TargetAlreadyExists |
The specified target already exists. | |
TargetInvalid |
The specified target is invalid. | |
TargetNotFound |
The specified target was not found. | |
UnsupportedOperationForGatewayType |
The specified operation is not valid for the type of the gateway. | |
VolumeAlreadyExists |
The specified volume already exists. | |
VolumeIdInvalid |
The specified volume is invalid. | DeleteVolume |
VolumeInUse |
The specified volume is already in use. | DeleteVolume |
VolumeNotFound |
The specified volume was not found. | |
VolumeNotReady |
The specified volume is not ready. |
Error Responses
When there is an error, the response header information contains:
-
Content-Type: application/x-amz-json-1.1
-
An appropriate
4xxor5xxHTTP 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 AWS Storage Gateway API Reference.
