提出 API 要求 - AWS Transfer Family
Transfer Family 必要的要求標頭Transfer Family 請求輸入和簽名錯誤回應可用程式庫

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

提出 API 要求

除了使用主控台之外，您還可以使用 AWS Transfer Family API 以程式設計方式設定和管理伺服器。本節說明 AWS Transfer Family 操作、身分驗證的請求簽章，以及錯誤處理。如需有關可用於 Transfer Family 的區域和AWS Transfer Family端點的資訊，請參閱 AWS 一般參考

注意

使用 Transfer Family 開發應用程序時，您也可以使用 AWS SDK;。適用於 Java，.NET 和 PHP 的AWS開發套件包裝了基礎的 Transfer Family API，從而簡化了您的編程任務。如需下載 SDK 程式庫的詳細資訊，請參閱範例程式碼程式庫。

Transfer Family 必要的要求標頭

本節說明必須與每個 POST 要求一起傳送的必要標頭AWS Transfer Family。您會透過包含 HTTP 標頭，來識別關於請求的關鍵資訊，包含您希望呼叫的操作、請求的日期，以及表示授權您做為請求寄件者的資訊。標頭不區分大小寫，並且標頭的順序也不重要。

下列範例顯示ListServers作業中使用的標頭。

POST / HTTP/1.1
Host: transfer.us-east-1.amazonaws.com
x-amz-target: TransferService.ListServers
x-amz-date: 20220507T012034Z
Authorization: AWS4-HMAC-SHA256 Credential=AKIDEXAMPLE/20220507/us-east-1/transfer/aws4_request,
    SignedHeaders=content-type;host;x-amz-date;x-amz-target,
    Signature=13550350a8681c84c861aac2e5b440161c2b33a3e4f302ac680ca5b686de48de
Content-Type: application/x-amz-json-1.1
Content-Length: 17

{"MaxResults":10}

以下是 Transfer Family 的 POST 請求中必須包含的標題。以下顯示以「x-amz」開頭的標題是特定的。AWS所有其他列出的標頭都是 HTTP 交易中使用的常見標頭。

標頭 描述
Authorization 授權標頭是必需的。該格式是標準的 Sigv4 請求簽名，其記錄在簽署 AWS API 請求中。
Content-Type

用application/x-amz-json-1.1作 Transfer Family 的所有請求的內容類型。

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

使用主機標頭指定傳送請求的轉移系列端點。例如，transfer.us-east-1.amazonaws.com是美國東部 (俄亥俄) 區域的端點。如需有關可用於 Transfer Family 之AWS Transfer Family端點的詳細資訊，請參閱 AWS 一般參考.

Host: transfer.region.amazonaws.com
x-amz-date

您必須在 HTTP Date 標頭或標頭中提供時間戳記。AWS x-amz-date(有些 HTTP 用戶端程式庫不讓您設定 Date 標頭。) 當x-amz-date標頭存在時，Transfer Family 會在要求驗證期間忽略任何Date標頭。x-amz-date格式必須是 ISO8601，格式為年月月日「海里曼斯」Z。

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

此標頭會指定 API 的版本，以及您請求的操作。目標標頭值是透過串連 API 版本及 API 名稱構成，且其格式如下。

x-amz-target: TransferService.operationName

您可以從 API 清單中找到 operationName 值 (例如ListServers)。ListServers
x-amz-security-token 當用於簽署請求的登入資料為臨時登入資料或工作階段登入資料時，需要此標頭 (如需詳細資訊，請參閱《IAM 使用者指南》中的 ＜ 使用臨時登入AWS資料 Amazon Web Services 一般參考如需詳細資訊，請參閱中的將簽章新增至 HTTP 要求。

Transfer Family 請求輸入和簽名

所有請求輸入都必須作為請求正文中 JSON 有效負載的一部分發送。例如，對於所有請求字段都是可選的操作ListServers，您仍然需要在請求主體中提供一個空的 JSON 對象，例如{}。例如，Transfer Family 有效負載請求/響應的結構記錄在現有的 API 參考中。DescribeServer

Transfer Family 支援使用AWS簽名版本 4 進行驗證。如需詳細資訊，請參閱簽署 AWS API 要求。

錯誤回應

當發生錯誤時，回應標頭資訊會包含：

  • 內容類型：application/x-amz-json-1.1

  • 適當的 4xx 或 5xx HTTP 狀態代碼

錯誤回應的內文會包含發生錯誤的資訊。以下範例錯誤回應會顯示所有錯誤回應常見的回應元素輸出語法。

{
    "__type": "String",
    "Message": "String", <!-- Message is lowercase in some instances -->
    "Resource": String,
    "ResourceType": String
    "RetryAfterSeconds": String
}

下表說明在上述語法中顯示的 JSON 錯誤回應欄位。

__type

Transfer Family API 呼叫的其中一個例外狀況。

類型：字串

訊息或訊息

的其中一項操作錯誤代碼訊息。

注意

有些例外使用message，而其他例外則使用Message。您可以檢查界面的代碼以確定正確的大小寫。或者，您可以測試每個選項以查看哪些有效。

類型：字串

Resource

呼叫錯誤的資源。例如，如果您嘗試建立已存在的使用者，Resource就是現有使用者的使用者名稱。

類型：字串

ResourceType

呼叫錯誤的資源類型。例如，如果您嘗試建立一個已存在的使用者，則ResourceType為User.

類型：字串

RetryAfterSeconds

重試指令之前等待的秒數。

類型：字串

錯誤回應範例

如果您呼叫 DescribeServer API 並指定不存在的伺服器，則會傳回下列 JSON 主體。

{
  "__type": "ResourceNotFoundException",
  "Message": "Unknown server",
  "Resource": "s-11112222333344444",
  "ResourceType": "Server"
}

如果執行 API 導致節流發生，則返回以下 JSON 主體。

{
   "__type":"ThrottlingException",
   "RetryAfterSeconds":"1"
}

如果您使用 CreateServer API，且您沒有足夠的權限來建立轉移系列伺服器，則會傳回下列 JSON 主體。

{
  "__type": "AccessDeniedException",
  "Message": "You do not have sufficient access to perform this action."
}

如果您使用 CreateUser API 並指定已存在的使用者，則會傳回下列 JSON 主體。

{  
  "__type": "ResourceExistsException",  
  "Message": "User already exists",
  "Resource": "Alejandro-Rosalez",
  "ResourceType": "User"
}

可用程式庫

AWS提供程式庫、範例程式碼、教學課程和其他資源，讓他們偏好使用特定語言的 API 來建置應用程式，而不是命令列工具和 Query API 來建置應用程式。這些庫提供基本功能（不包括在 API 中），例如請求身份驗證，請求重試和錯誤處理，以便更容易上手。請參閱建置基礎的工具 AWS

如需所有語言的程式庫和範例程式碼，請參閱範例程式碼與程式庫。