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 以在使用. AWS Storage Gateway適用於 Java，.NET 和 PHP 的 AWS 開發套件包裝了基礎 AWS Storage Gateway API，從而簡化了您的編程任務。如需下載軟體開發套件程式庫的詳細資訊，請參閱範本程式碼程式庫
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 |
授權標頭包含幾段請求的資訊，讓 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 Signature 第 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)，標頭 (為了可讀性而新增了換行) 是：
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 |
指定的操作不明。有效操作會在 Storage 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 |
指定的磁碟區尚未準備就緒。 |
錯誤回應
當發生錯誤時，回應標頭資訊會包含：
-
內容類型：應用程式 /-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
-
的其中一項操作錯誤代碼訊息。
類型：字串
錯誤回應範例
如果您使用 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." }
Storage Gateway 中的操作
如需 Storage Gateway 作業的清單，請參閱 AWS Storage Gateway API 參考中的動作。
