Storage Gateway 的 API 參考

除了使用 主控台之外，您還可以使用 AWS Storage Gateway API 以程式設計方式設定和管理閘道。本節說明 AWS Storage Gateway 操作、身分驗證的請求簽署和錯誤處理。如需 Storage Gateway 可用區域和端點的詳細資訊，請參閱 AWS 一般參考 中的 AWS Storage Gateway 端點與配額。

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" 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 Signature 第 4 版進行身分驗證。計算簽章的程序可以分成三個任務：

簽章計算範例

下列範例會逐步解說如何建立 ListGateways 簽章的詳細資訊。此範例可用作檢查簽名簽章計算方法的參考。Amazon Web Services 詞彙表的 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

正式請求的最後一行是請求內文的雜湊值。另外，請注意正式請求中的空的第三行。這是因為此 API (或任何 Storage Gateway API) 沒有查詢參數。

的「登入字串」為：

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

錯誤回應

本節提供有關 AWS Storage Gateway 錯誤的參考資訊。這些錯誤會以錯誤異常及操作錯誤代碼表示。例如，若請求簽章發生問題，任意 API 回應會傳回 InvalidSignatureException 錯誤異常。但是，操作錯誤代碼 ActivationKeyInvalid 僅會由 ActivateGateway API 傳回。

根據錯誤的類型，Storage Gateway 可能只會傳回異常，或是同時傳回異常及操作錯誤代碼。錯誤回應的範例會在錯誤回應中顯示。

例外狀況

下表列出 AWS Storage Gateway API 例外狀況。當 AWS Storage Gateway 操作傳回錯誤回應時，回應內文會包含其中一個例外狀況。InternalServerError 和 InvalidGatewayRequestException 會傳回 操作錯誤代碼 訊息代碼中的其中一項操作錯誤代碼，提供特定操作錯誤代碼。

操作錯誤代碼

下表顯示 AWS Storage Gateway 操作錯誤代碼與可傳回代碼APIs 之間的映射。所有的操作錯誤代碼都會使用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"
  }
}

若 Storage Gateway 計算出的簽章不符合與請求一同傳送的簽章，便會傳回以下 JSON 內文。

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

Storage Gateway 中的操作

如需 Storage Gateway 操作的清單，請參閱 AWS Storage Gateway API 參考中的動作。