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

AWS Transfer Family API 參考

Transfer Family 的完整 API 參考指南可在 AWS Transfer Family API 參考中取得。

AWS Transfer Family 是一種安全傳輸服務，可讓您透過下列通訊協定，將檔案傳入和傳出 Amazon Simple Storage Service (Amazon S3) 儲存體：

伺服器、使用者和角色都由其 Amazon Resource Name (ARN) 識別。您可以將索引鍵/值對的標籤指派給具有 ARN 的實體。標籤是中繼資料，可用於分組或搜尋這些實體。舉例來說，標籤在會計用途方面就非常有用。

下列慣例是以 AWS Transfer Family ID 格式觀察到的：

Amazon Resource Name (ARN) 格式採用下列格式：

使用中的 DNS 項目 （端點） 如下所示：

的此 API 界面參考 AWS Transfer Family 包含您可以用來管理的程式設計界面的文件 AWS Transfer Family。參考結構如下：

提出 API 請求

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

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 交易中使用的常見標頭。

Transfer Family 請求輸入和簽署

所有請求輸入都必須作為請求內文中 JSON 承載的一部分傳送。對於所有請求欄位都是選用的動作，例如 ListServers，您仍然需要在請求內文中提供空的 JSON 物件，例如 {}。Transfer Family 承載請求/回應的結構記錄在現有的 API 參考中，例如 DescribeServer。

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

錯誤回應

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

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

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

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

錯誤回應範例

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

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

如果執行 API 導致限流發生，則會傳回下列 JSON 內文。

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

如果您使用 CreateServer API，而且您沒有足夠的許可來建立 Transfer Family 伺服器，則會傳回下列 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 為偏好使用特定語言 APIs 而非命令列工具和查詢 API 建置應用程式的軟體開發人員提供程式庫、範例程式碼、教學課程和其他資源。這些程式庫提供基本函數 （不包含在 APIs中），例如請求身分驗證、請求重試和錯誤處理，以便更輕鬆地開始使用。請參閱要建置的工具 AWS

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

身分提供者

AWS Transfer Family 支援多種身分提供者類型來驗證和管理使用者。每個伺服器只能使用一種身分驗證方法，該方法必須在建立伺服器時選取。

對於所有身分驗證方法，會指派政策給使用者，以定義他們對 Amazon S3 儲存貯體或 Amazon Elastic File System 檔案系統的存取。伺服器會透過 IAM 角色與 AssumeRole動作繼承使用者的信任關係，允許其代表使用者執行檔案操作。

命名慣例

AWS Transfer Family 針對資源識別符和 Amazon Resource Name (ARNs) 使用標準化格式。使用 API 時， AWS Transfer Family 了解這些慣例非常重要。

ID 格式

下列慣例是以 AWS Transfer Family ID 格式觀察到的：

ARN 格式

Amazon Resource Name (ARN) 格式採用下列格式：

您可以使用 ARN 將鍵值對的標籤指派給實體。標籤是中繼資料，可用於分組或搜尋這些實體。舉例來說，標籤在會計用途方面就非常有用。

DNS 和端點

AWS Transfer Family 針對 API 端點和伺服器端點使用標準化 DNS 命名慣例。了解這些端點對於設定用戶端和進行 API 呼叫至關重要。

API 端點

API 端點用於進行 API 呼叫以管理 AWS Transfer Family 資源。這些端點採用下列形式：

伺服器端點

檔案傳輸用戶端會使用伺服器端點來連線至 AWS Transfer Family 伺服器。這些端點採用下列形式：

如需依 AWS 區域列出的 AWS Transfer Family 端點完整清單，請參閱 中的AWS Transfer Family 端點和配額AWS 一般參考。