Amazon S3 檔案閘道文件已移至什麼是 Amazon S3 檔案閘道？
Amazon FSx 檔案閘道文件已移至什麼是 Amazon FSx 檔案閘道？
磁碟區閘道文件已移至什麼是磁碟區閘道？
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
Storage Gateway 的 API 參考
除了使用主控台之外，您可以使用 AWS Storage Gateway API 來以程式設計方式設定及管理您的閘道。本節說明 AWS Storage Gateway 操作、身分驗證的請求簽章，以及錯誤處理。如需 Storage Gateway 可用區域和端點的相關資訊，請參閱AWS一般參考中的AWS Storage Gateway端點和配額。
使用開發應用程式時，您也可以使用AWS SDKAWS Storage Gateway。適用於 Java、.NET 與 PHP 的AWSAWS Storage Gateway SDK，簡化您的程式設計任務。如需下載軟體開發套件程式庫的詳細資訊，請參閱範本程式碼程式庫
Storage Gateway 必要的要求標頭
本節說明必須隨著每個 POST 要求傳送至 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
以下是 Storage Gateway POST 要求中必須包含的標頭。下面顯示以「x-amz」開頭的標題是AWS特定的標題。所有其他列出的標頭都是 HTTP 交易中使用的常見標頭。
| 標頭 | 描述 |
|---|---|
Authorization |
授權標頭包含許多有關請求的資訊，這些資訊可讓 Storage Gateway 判斷要求是否是要求者的有效動作。此標頭的格式如下 (為求可讀性已新增分行)：
在上述語法中 YourAccessKey，您可以指定年、月和日 (yyyymmdd)、區域和 CalculatedSignature. 授權標頭的格式由AWS V4 簽名過程的要求決定。簽章的詳細資訊會在簽署請求主題中討論。 |
Content-Type |
用
|
Host |
使用主機標頭來指定您傳送要求的 Storage Gateway 端點。例如，
|
x-amz-date |
您必須在 HTTP
|
x-amz-target |
此標頭會指定 API 的版本，以及您請求的操作。目標標頭值是透過串連 API 版本及 API 名稱構成，且其格式如下。
您可以從 API 清單中找到 operationName 值 (例如ActivateGateway「」)Storage Gateway 的 API 參考。 |
簽署請求
Storage Gateway 會要求您透過簽署要求來驗證您傳送的每個要求。若要簽署請求，請使用加密雜湊函數來計算數位簽章。加密雜湊是一個函數, 其根據輸入傳回一個唯一的雜湊值。此雜湊函數的輸入包含請求和私密存取金鑰的文字。雜湊函數會傳回一個雜湊值，您將此值包含在請求中做為簽章。該簽章是請求 Authorization 標頭中的一部分。
收到您的要求後，Storage Gateway 會使用您用來簽署要求的相同雜湊函數和輸入來重新計算簽章。如果產生的簽章符合要求中的簽章，Storage Gateway 會處理要求。否則，請求會遭到拒絕。
Storage Gateway 支援使用AWS簽章版本 4 進行驗證。計算簽章的程序可以分成三個任務：
-
將 HTTP 請求重新編排為正式格式。使用標準表單是必要的，因為 Storage Gateway 在重新計算簽名以與您傳送的簽名進行比較時，會使用相同的規範表單。
-
建立一個字串，您會使用此字串做為密碼編譯雜湊函數的其中一個輸入值。此字串，稱為登入字串，是雜湊演算法的名稱、請求日期、登入資料範圍字串和前一個任務的正式請求的串連。登入資料範圍字串本身是日期、區域和服務資訊的串連。
-
使用接受兩個輸入字串的密碼編譯雜湊函數來建立請求的簽章：您的 登入字串和衍生金鑰。「衍生金鑰」的計算方式是從私密存取金鑰開始，並使用「登入資料範圍」字串來建立一系列雜湊類型訊息身分驗證碼 (HMAC)。
簽章計算範例
以下範例會逐步解說為 ListGateways 建立簽章的詳細資訊 。此範例可用作檢查簽名簽章計算方法的參考。Amazon Web Services 詞彙表的 Signature Version 4 Test Suite 包含其他參考計算。
該範例假設如下：
-
請求的時間戳記為 "Mon, 10 Sep 2012 00:00:00" GMT。
-
端點是美國東部 (俄亥俄亥俄亥俄亥俄亥俄亥俄亥俄
一般請求語法 (包括 JSON 內文) 是：
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 {}
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")
如果使用密鑰訪問密鑰, 密鑰, 密bPxRfi鑰, 然後計算出的簽名是:
6d4c40b8f2257534dbdca9f326f147a0a7a419b63aff349d9d9c737c9a0f4c81
最後步驟是建立 Authorization 標頭。對於演示訪問密鑰 AKIAIOSFODNN7EXAMPLE，標題（為了可讀性添加了換行符）是：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對 ActivateGatewayAPI 傳回作業錯誤碼。
視錯誤類型而定，Storage Gateway 可能只會傳回例外狀況，或傳回例外狀況和作業錯誤碼。錯誤回應的範例會在錯誤回應中顯示。
例外狀況
下表列出 AWS Storage Gateway API 異常。當 AWS Storage Gateway 操作傳回錯誤回應時，回應內文會包含以下任一項異常。InternalServerError 和 InvalidGatewayRequestException 會傳回 操作錯誤代碼 訊息代碼中的其中一項操作錯誤代碼，提供特定操作錯誤代碼。
| 異常情形 | 訊息 | HTTP 狀態碼 |
|---|---|---|
IncompleteSignatureException |
指定的簽章不完整。 | 400 錯誤的請求 |
InternalFailure |
由於不明的錯誤、異常或故障，處理請求失敗。 | 500 內部伺服器錯誤 |
InternalServerError |
操作錯誤代碼 的其中一項操作錯誤代碼訊息。 | 500 內部伺服器錯誤 |
InvalidAction |
請求請求的動作請求的動作。 | 400 錯誤的請求 |
InvalidClientTokenId |
提供的 X.509 憑證或AWS存取金鑰識別碼不存在於我們的記錄中。 | 403 Forbidden (403 禁止) |
InvalidGatewayRequestException |
操作錯誤代碼 中的其中一項操作錯誤代碼訊息。 | 400 錯誤的請求 |
InvalidSignatureException |
我們計算的請求簽章不符合您提供的簽章。檢查您的AWS訪問密鑰和簽名方法。 | 400 錯誤的請求 |
MissingAction |
請求中遺失動作或操作參數。 | 400 錯誤的請求 |
MissingAuthenticationToken |
要求必須包含有效 (已註冊)AWS 存取金鑰識別碼或 X.509 憑證。 | 403 Forbidden (403 禁止) |
RequestExpired |
請求已超過過期日期或請求日期 (兩者皆具有 15 分鐘的填補)，或是請求日期的發生時間超過未來的 15 分鐘。 | 400 錯誤的請求 |
SerializationException |
序列化時發生錯誤。確認您的 JSON 承載格式正確。 | 400 錯誤的請求 |
ServiceUnavailable |
由於伺服器暫時故障，請求失敗。 | 503 Service Unavailable (503 服務無法使用) |
SubscriptionRequiredException |
AWS存取金鑰 ID 需要服務的訂閱。 | 400 錯誤的請求 |
ThrottlingException |
超過費率。 | 400 錯誤的請求 |
UnknownOperationException |
指定的操作不明。有效操作會在 SStorage Gateway 中列出。 | 400 錯誤的請求 |
UnrecognizedClientException |
請求中包含的安全令牌無效。 | 400 錯誤的請求 |
ValidationException |
輸入參數的值不符或超出範圍。 | 400 錯誤的請求 |
操作錯誤代碼
下表顯示 AWS Storage Gateway 操作錯誤代碼與傳回代碼之 API 間的映射。所有的操作錯誤代碼都會使用InternalServerError中所說明之兩種一般異常 (InvalidGatewayRequestException 和 例外狀況) 中的其中一種傳回。
| 操作錯誤代碼 | 訊息 | 傳回此錯誤代碼的操作 |
|---|---|---|
ActivationKeyExpired |
指定的啟用金鑰已過期。 | ActivateGateway |
ActivationKeyInvalid |
指定的啟動金鑰。 | ActivateGateway |
ActivationKeyNotFound |
找不到指定的啟用金鑰。 | ActivateGateway |
BandwidthThrottleScheduleNotFound |
找不到指定的頻寬調節。 | DeleteBandwidthRateLimit |
CannotExportSnapshot |
無法匯出指定的快照。 | |
InitiatorNotFound |
找不到指定的啟動器。 | DeleteChapCredentials |
DiskAlreadyAllocated |
指定的磁碟已配置。 | |
DiskDoesNotExist |
指定的磁碟不存在。 | |
DiskSizeNotGigAligned |
指定的磁碟未調整為 GB。 | |
DiskSizeGreaterThanVolumeMaxSize |
指定的磁碟大小大於磁碟區大小上限。 | CreateStorediSCSI 卷 |
DiskSizeLessThanVolumeSize |
指定的磁碟大小小於磁碟區大小。 | CreateStorediSCSI 卷 |
DuplicateCertificateInfo |
指定的憑證資訊重複。 | ActivateGateway |
GatewayInternalError |
發生閘道內部錯誤。 | |
GatewayNotConnected |
指定的閘道並未連線。 | |
GatewayNotFound |
找不到指定的閘道。 | |
GatewayProxyNetworkConnectionBusy |
指定的閘道代理網路連線忙碌中。 | |
InternalError |
發生內部錯誤。 | |
InvalidParameters |
指定的請求包含不正確的參數。 | |
LocalStorageLimitExceeded |
超過本機儲存限制。 | |
LunInvalid |
指定的 LUN 不正確。 | CreateStorediSCSI 卷 |
MaximumVolumeCountExceeded |
超過磁碟區計數上限。 | |
NetworkConfigurationChanged |
閘道網路組態已變更。 | |
NotSupported |
不支援指定的操作。 | |
OutdatedGateway |
指定的閘道已過期。 | ActivateGateway |
SnapshotInProgressException |
指定的快照正在進行。 | DeleteVolume |
SnapshotIdInvalid |
指定的快照。 | |
StagingAreaFull |
預備區域已滿。 | |
TargetAlreadyExists |
指定的目標已存在。 | |
TargetInvalid |
指定的目標目標。 | |
TargetNotFound |
找不到指定的目標。 | |
UnsupportedOperationForGatewayType |
指定的操作對於閘道類型無效。 | |
VolumeAlreadyExists |
指定的磁碟區已存在。 | |
VolumeIdInvalid |
指定的磁碟區。 | DeleteVolume |
VolumeInUse |
指定的磁碟區已在使用。 | DeleteVolume |
VolumeNotFound |
找不到指定的磁碟區。 | |
VolumeNotReady |
指定的磁碟區尚未準備就緒。 |
錯誤回應
當發生錯誤時，回應標頭資訊會包含：
-
內容類型：應用程式/x-amz-json-1.1
-
適當的
4xx或5xxHTTP 狀態代碼
錯誤回應的內文會包含發生錯誤的資訊。以下範例錯誤回應會顯示所有錯誤回應常見的回應元素輸出語法。
{ "__type": "String", "message": "String", "error": { "errorCode": "String", "errorDetails": "String" } }
下表說明在上述語法中顯示的 JSON 錯誤回應欄位。
- __type
-
其中一個來自例外狀況的異常。
類型：字串
- error
-
包含特定 API 的錯誤詳細資訊。在一般錯誤 (即不限定於任何 API) 中，不會顯示這項錯誤資訊。
類型：集合
- errorCode
-
其中一項操作錯誤代碼 。
類型：字串
- errorDetails
-
目前的 API 版本未使用此欄位。
類型：字串
- message
-
的其中一項操作錯誤代碼訊息。
類型：字串
錯誤回應範例
如果您使用 DescribeStoredi SCSiVolumes 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." }
SStorage Gateway
如需 Storage Gateway 作業的清單，請參閱 AWS Storage GatewayAPI 參考中的動作。
