Amazon S3 檔案閘道文件已移至什麼是 Amazon S3 檔案閘道？
Amazon FSx 檔案閘道文件已移至什麼是 Amazon FSx 檔案閘道？
磁帶閘道文件已移至什麼是磁帶閘道？
本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
APIStorage Gateway 的參考
除了使用主控台之外，您還可以使用 AWS Storage Gateway API以程式設計方式設定和管理閘道。本節說明作 AWS Storage Gateway 業、驗證要求簽署以及錯誤處理。如需 Storage Gateway 可用區域和端點的詳細資訊，請參閱 AWS 一般參考 中的 AWS Storage Gateway 端點與配額。
注意
您也可以在使用開發應用程式 AWS SDKs時使用 AWS Storage Gateway。對 AWS SDKs於爪哇，. NET，並PHP包裝底層 AWS Storage Gateway API，簡化您的編程任務。如需下載程式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「」) APIStorage Gateway 的參考。 |
簽署請求
Storage Gateway 會要求您簽署請求，對您發送的每個請求進行身分驗證。若要簽署請求，請使用加密雜湊函數來計算數位簽章。加密雜湊是一個函數, 其根據輸入傳回一個唯一的雜湊值。此雜湊函數的輸入包含請求和私密存取金鑰的文字。雜湊函數會傳回一個雜湊值，您將此值包含在請求中做為簽章。該簽章是請求 Authorization 標頭中的一部分。
收到請求後，Storage Gateway 會使用您原先用以簽署請求的相同雜湊函數與輸入，重新計算簽章。如果產生的簽章符合請求中的簽章，Storage Gateway 將處理請求。否則，請求會遭到拒絕。
Storage Gateway 支援使用 AWS Signature 第 4 版進行身分驗證。計算簽章的程序可以分成三個任務：
-
將您的HTTP請求重新排列為標準格式。使用標準表單是必要的，因為 Storage Gateway 在重新計算簽章以與所傳送的簽章進行比較時，會使用相同的標準表單。
-
建立一個字串，您會使用此字串做為密碼編譯雜湊函數的其中一個輸入值。此字串，稱為登入字串，是雜湊演算法的名稱、請求日期、登入資料範圍字串和前一個任務的正式請求的串連。登入資料範圍字串本身是日期、區域和服務資訊的串連。
-
使用接受兩個輸入字串的密碼編譯雜湊函數來建立請求的簽章：您的 登入字串和衍生金鑰。衍生金鑰的計算方式是從您的秘密存取金鑰開始，並使用認證範圍字串建立一系列雜湊型訊息驗證碼 (HMACs)。
簽章計算範例
下列範例會逐步引導您建立簽名的詳細資訊ListGateways。此範例可用作檢查簽名簽章計算方法的參考。Amazon Web Services 詞彙表的 Signature Version 4 Test Suite 包含其他參考計算。
該範例假設如下：
-
申請的時間戳記為「二零一二年九月十日（星期一）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 GatewayAPIs）的查詢參數。
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")
如果使用密鑰訪問密鑰 wJalr XUtnFEMI /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的作業錯誤碼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 錯誤的請求 |
TooManyRequests |
請求過多。 | 429 個太多的要求 |
UnknownOperationException |
指定的操作不明。有效操作會在 Storage Gateway 中的操作 中列出。 | 400 錯誤的請求 |
UnrecognizedClientException |
包含在請求中的安全性權杖無效。 | 400 錯誤的請求 |
ValidationException |
輸入參數的值不符或超出範圍。 | 400 錯誤的請求 |
操作錯誤代碼
下表顯示了 AWS Storage Gateway 操作錯誤代碼和APIs可以返回代碼之間的映射。所有的操作錯誤代碼都會使用InternalServerError中所說明之兩種一般異常 (InvalidGatewayRequestException 和 例外狀況) 中的其中一種傳回。
| 操作錯誤代碼 | 訊息 | 傳回此錯誤代碼的操作 |
|---|---|---|
ActivationKeyExpired |
指定的啟用金鑰已過期。 | ActivateGateway |
ActivationKeyInvalid |
指定的啟用金鑰無效。 | ActivateGateway |
ActivationKeyNotFound |
找不到指定的啟用金鑰。 | ActivateGateway |
BandwidthThrottleScheduleNotFound |
找不到指定的頻寬調節。 | DeleteBandwidthRateLimit |
CannotExportSnapshot |
無法匯出指定的快照。 | |
InitiatorNotFound |
找不到指定的啟動器。 | DeleteChapCredentials |
DiskAlreadyAllocated |
指定的磁碟已配置。 | |
DiskDoesNotExist |
指定的磁碟不存在。 | |
DiskSizeNotGigAligned |
指定的磁碟未調整為 GB。 | |
DiskSizeGreaterThanVolumeMaxSize |
指定的磁碟大小大於磁碟區大小上限。 | CreateStorediSCSIVolume |
DiskSizeLessThanVolumeSize |
指定的磁碟大小小於磁碟區大小。 | CreateStorediSCSIVolume |
DuplicateCertificateInfo |
指定的憑證資訊重複。 | ActivateGateway |
GatewayInternalError |
發生閘道內部錯誤。 | |
GatewayNotConnected |
指定的閘道並未連線。 | |
GatewayNotFound |
找不到指定的閘道。 | |
GatewayProxyNetworkConnectionBusy |
指定的閘道代理網路連線忙碌中。 | |
InternalError |
發生內部錯誤。 | |
InvalidParameters |
指定的請求包含不正確的參數。 | |
LocalStorageLimitExceeded |
超過本機儲存限制。 | |
LunInvalid |
指定的不LUN正確。 | CreateStorediSCSIVolume |
MaximumVolumeCountExceeded |
超過磁碟區計數上限。 | |
NetworkConfigurationChanged |
閘道網路組態已變更。 | |
NotSupported |
不支援指定的操作。 | |
OutdatedGateway |
指定的閘道已過期。 | ActivateGateway |
SnapshotInProgressException |
指定的快照正在進行。 | DeleteVolume |
SnapshotIdInvalid |
指定的快照無效。 | |
StagingAreaFull |
預備區域已滿。 | |
TargetAlreadyExists |
指定的目標已存在。 | |
TargetInvalid |
指定的目標無效。 | |
TargetNotFound |
找不到指定的目標。 | |
UnsupportedOperationForGatewayType |
指定的操作對於閘道類型無效。 | |
VolumeAlreadyExists |
指定的磁碟區已存在。 | |
VolumeIdInvalid |
指定的磁碟區無效。 | DeleteVolume |
VolumeInUse |
指定的磁碟區已在使用。 | DeleteVolume |
VolumeNotFound |
找不到指定的磁碟區。 | |
VolumeNotReady |
指定的磁碟區尚未準備就緒。 |
錯誤回應
當發生錯誤時，回應標頭資訊會包含：
-
內容類型：應用程式 /-1.1 x-amz-json
-
適當的
4xx或5xxHTTP狀態碼
錯誤回應的內文會包含發生錯誤的資訊。以下範例錯誤回應會顯示所有錯誤回應常見的回應元素輸出語法。
{ "__type": "String", "message": "String", "error": { "errorCode": "String", "errorDetails": "String" } }
下表說明上述語法中顯示的JSON錯誤回應欄位。
- __type
-
其中一個來自例外狀況的異常。
類型：字串
- error
-
包含API特定錯誤詳細資訊。在一般錯誤（即不特定於任何錯誤API）中，不會顯示此錯誤信息。
類型：集合
- errorCode
-
其中一項操作錯誤代碼 。
類型：字串
- errorDetails
-
此欄位不在目前版本的中使用API。
類型：字串
- message
-
的其中一項操作錯誤代碼訊息。
類型：字串
錯誤回應範例
如果您使用 DescribeStorediSCSIVolumesAPI並指定不存在的閘道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參考資料中的動作。
