Storage Gateway の API リファレンス

コンソールの使用に加えて、AWS Storage Gateway API を使用してゲートウェイをプログラミングで設定し、管理できます。このセクションでは、AWS Storage Gateway のオペレーション、認証のための署名要求、エラー処理について説明します。Storage Gateway で使用可能なリージョンとエンドポイントの詳細については、「」を参照してください。AWS Storage GatewayエンドポイントとクォータのAWS全般のリファレンス。

AWS Storage Gateway必須リクエストヘッダー

このセクションでは、すべての POST リクエストで送信する必要がある必須のヘッダーについて説明します。AWS Storage Gateway。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

次に示すのは、に対する POST リクエストに含める必要があるヘッダーです。AWS Storage Gateway。次に示す「x-amz」で始まるヘッダーは次のとおりです。AWS固有ヘッダー。それ以外のヘッダーはすべて、HTTP トランザクションで使用される共通のヘッダーです。

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

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

Host: storagegateway.region.amazonaws.com

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

x-amz-target: StorageGateway_APIversion.operationName

リクエストへの署名

Storage Gateway では、リクエストに署名することで、送信するすべてのリクエストを認証する必要があります。リクエストに署名するには、暗号化ハッシュ関数を使用してデジタル署名を計算します。暗号化ハッシュは、入力データから一意のハッシュ値生成して返す関数です。ハッシュ関数に渡される入力データとしては、リクエストのテキスト、およびシークレットアクセスキーが該当します。ハッシュ関数から返されるハッシュ値をリクエストに署名として含めます。署名は、リクエストの Authorization ヘッダーの一部です。

Storage Gateway は、リクエストを受け取ると、リクエストの署名に使用されたものと同じハッシュ関数と入力を使用して署名を再計算します。再計算された署名とリクエスト内の署名が一致した場合、Storage Gateway はリクエストを処理します。それ以外の場合、リクエストは拒否されます。

Storage Gateway は認証をサポートしていますAWS署名バージョン 4。署名の計算プロセスは 3 つのタスクに分けることができます。

署名の計算例

次の例で、ListGateways の署名を作成する詳細な手順を示します。実際の署名計算方法を確認するときに、この例を参考にしてください。その他の参考計算例については、アマゾン ウェブ サービス用語集の「Signature Version 4 Test Suite」を参照してください。

例では、次のように想定しています。

リクエストの一般的な構文 (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

正規リクエストの最後の行はリクエストボディのハッシュです。また、正規リクエストの 3 行目が空であることに注意してください。これは、この API（またはStorage Gateway API）のクエリパラメータがないためです。

-署名対象の文字列にとっては:

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

署名する文字列の最初の行はアルゴリズム、2 行目はタイムスタンプ、3 行目は認証情報スコープ、最後の行はタスク 1 で作成した正規リクエストのハッシュです。

の場合、派生キーは、次のように表すことができます。

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

シークレットアクセスキー wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY が使用されている場合、計算された署名は次のようになります。

6d4c40b8f2257534dbdca9f326f147a0a7a419b63aff349d9d9c737c9a0f4c81

最後のステップは、Authorization ヘッダーの構築です。デモンストレーションのアクセスキー AKAKIAIOSFODNN7EXAMPLE AMPLE の場合、ヘッダーは次のとおりです (読みやすいように改行しています)。

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 エラーに関するリファレンス情報を提供します。これらのエラーは、エラー例外とオペレーションエラーコードを表しています。例えば、エラー例外 InvalidSignatureException は、リクエスト署名に問題がある場合に、API レスポンスによって返されます。ただし、オペレーションエラーコード ActivationKeyInvalid は、ActivateGateway API に対してのみ返されます。

エラーの種類に応じて、Storage Gateway は例外だけを返すことも、例外とオペレーションエラーコードの両方を返すこともあります。エラーレスポンスの例を エラーレスポンス に示します。

例外

次の表は、AWS Storage Gateway API の例外を表示しています。AWS Storage Gateway オペレーションがエラーレスポンスを返す場合、レスポンス本文には、次の例外のいずれかが含まれます。InternalServerError と InvalidGatewayRequestException は、特定のオペレーションエラーコードを表示するオペレーションエラーコード オペレーションエラーコード メッセージの 1 つを返します。

オペレーションエラーコード

次のテーブルに、AWS Storage Gateway オペレーションエラーコードと、そのコードを返す API の対応を示します。すべての操作エラーコードは、2 つの一般的な例外のいずれかとともに返されます。InternalServerErrorそしてInvalidGatewayRequestException—で説明しています。例外。

エラーレスポンス

エラーが発生した場合、レスポンスヘッダー情報には、以下の項目が含まれています。

エラーレスポンスの本文には、発生したエラーに関する情報が含まれています。次のサンプルエラーは、すべてのエラーレスポンスに共通する、レスポンスエレメントの出力構文を示します。

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

次の表では、前述の構文で表示される JSON エラーレスポンスフィールドを説明します。

エラーレスポンスの例

DescribeStorediSCSIVolumes API を使用して、存在しないゲートウェイ ARN リクエスト入力を指定した場合、次の JSON 本文が返されます。

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

次に示す JSON 本文は、Storage Gateway がリクエストで送信された署名と一致しない場合、返されます。

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

Storage Gateway での操作

Storage Gateway オペレーションのリストについては、「」を参照してください。アクションのAWS Storage GatewayAPI リファレンス。