本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# AWS Transfer Family API 參考
Transfer Family 的完整 API 參考指南可在 [AWS Transfer Family API 參考](https://docs.aws.amazon.com/transfer/latest/APIReference/api-welcome.html)中取得。
AWS Transfer Family 是一種安全傳輸服務，可讓您透過下列通訊協定，將檔案傳入和傳出 Amazon Simple Storage Service (Amazon S3) 儲存體：
+ 安全殼層 (SSH) 檔案傳輸通訊協定 (SFTP)
+ 檔案傳輸通訊協定安全 (FTPS)
+ 檔案傳輸通訊協定 (FTP)
+ 適用性聲明 2 (AS2)
伺服器、使用者和角色都由其 Amazon Resource Name (ARN) 識別。您可以將索引鍵/值對的標籤指派給具有 ARN 的實體。標籤是中繼資料，可用於分組或搜尋這些實體。舉例來說，標籤在會計用途方面就非常有用。
下列慣例是以 AWS Transfer Family ID 格式觀察到的：
+ `ServerId` 值採用 `s-01234567890abcdef` 的形式。
+ `SshPublicKeyId` 值採用 `key-01234567890abcdef` 的形式。
Amazon Resource Name (ARN) 格式採用下列格式：
+ 對於 伺服器，ARNs採用格式 `arn:aws:transfer:{{region}}:{{account-id}}:server/{{server-id}}`。
伺服器 ARN 的範例為 `arn:aws:transfer:us-east-1:123456789012:server/s-01234567890abcdef`。
+ 針對使用者，ARN 採用 `arn:aws:transfer:{{region}}:{{account-id}}:user/{{server-id}}/{{username}}` 的形式。
例如，`arn:aws:transfer:us-east-1:123456789012:user/s-01234567890abcdef/user1`。
使用中的 DNS 項目 （端點） 如下所示：
+ API 端點採用 `transfer.{{region}}.amazonaws.com` 的形式。
+ 伺服器端點採用 `{{server-id}}.server.transfer.{{region}}.amazonaws.com` 的形式。
的此 API 界面參考 AWS Transfer Family 包含您可以用來管理的程式設計界面的文件 AWS Transfer Family。參考結構如下：
+ 如需 API 動作的字母清單，請參閱 [Actions](https://docs.aws.amazon.com/transfer/latest/APIReference/API_Operations.html)。
+ 如需資料類型的字母清單，請參閱 [Types](https://docs.aws.amazon.com/transfer/latest/APIReference/API_Types.html)。
+ 如需常用查詢參數的清單，請參閱[常用參數](https://docs.aws.amazon.com/transfer/latest/APIReference/CommonParameters.html)。
+ 如需錯誤碼的說明，請參閱[常見錯誤](https://docs.aws.amazon.com/transfer/latest/APIReference/CommonErrors.html)。
**提示**
您可以搭配任何 API 呼叫使用 `--generate-cli-skeleton` 參數來產生和顯示參數範本，而不是實際執行命令。然後，您可以使用產生的範本來自訂和使用 做為稍後命令的輸入。如需詳細資訊，請參閱[產生和使用參數骨架檔案](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-skeleton.html#cli-usage-skeleton-generate)。
## 提出 API 請求
除了使用 主控台之外，您還可以使用 AWS Transfer Family API 以程式設計方式設定和管理伺服器。本節說明 AWS Transfer Family 操作、身分驗證的請求簽署和錯誤處理。如需 Transfer Family 可用區域和端點的相關資訊，請參閱《》中的[AWS Transfer Family 端點和配額](https://docs.aws.amazon.com/general/latest/gr/transfer-service.html)。 *AWS 一般參考*
**注意**
使用 Transfer Family 開發應用程式時，您也可以使用 AWS SDKs。適用於 Java、.NET 和 PHP AWS SDKs 包裝基礎 Transfer 系列 API，簡化您的程式設計任務。如需下載 SDK 程式庫的資訊，請參閱[範例程式碼程式庫](https://aws.amazon.com/code)。
### Transfer Family 必要請求標頭
本節說明您必須隨每個 POST 請求傳送至 的必要標頭 AWS Transfer Family。您會透過包含 HTTP 標頭，來識別關於請求的關鍵資訊，包含您希望呼叫的操作、請求的日期，以及表示授權您做為請求寄件者的資訊。標頭不區分大小寫，並且標頭的順序也不重要。
下列範例顯示 [ListServers](https://docs.aws.amazon.com/transfer/latest/userguide/API_ListServers.html) 操作中使用的標頭。
```
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](https://docs.aws.amazon.com/transfer/latest/userguide/API_DescribeServer.html)。
Transfer Family 支援使用 AWS Signature 第 4 版進行身分驗證。如需詳細資訊，請參閱[簽署 AWS API 請求](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html)。
### 錯誤回應
當發生錯誤時，回應標頭資訊會包含：
+ Content-Type： `application/x-amz-json-1.1`
+ 適當的 `4xx` 或 `5xx` HTTP 狀態代碼
錯誤回應的內文會包含發生錯誤的資訊。以下範例錯誤回應會顯示所有錯誤回應常見的回應元素輸出語法。
```
{
"__type": "String",
"Message": "String",
"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，而且您沒有足夠的許可來建立 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](https://aws.amazon.com/tools/?id=docs_gateway)
如需所有語言的程式庫和範本程式碼，請參閱[範本程式碼和程式庫](https://aws.amazon.com/code)。
## 身分提供者
AWS Transfer Family 支援多種身分提供者類型來驗證和管理使用者。每個伺服器只能使用一種身分驗證方法，該方法必須在建立伺服器時選取。
服務受管
使用 `SERVICE_MANAGED` 身分驗證方法時，使用者登入資料會存放在其中並進行管理 AWS Transfer Family。使用者會使用與伺服器上使用者名稱相關聯的 SSH 公有金鑰進行身分驗證。
每個使用者可以在服務中存放一或多個 SSH 公有金鑰。當用戶端請求檔案操作時，它會提供使用者名稱和 SSH 私有金鑰，這會根據儲存的公有金鑰進行驗證。
Directory Service
`AWS_DIRECTORY_SERVICE` 身分驗證方法可讓您與 AWS Directory Service for Microsoft Active Directory (AWS Directory Service for Microsoft Active Directory) 整合。
此選項可讓您透過現有的 Active Directory 群組管理使用者身分驗證和存取。使用者可以使用其 Active Directory 登入資料進行身分驗證。
預設限制為每部伺服器 100 個 Active Directory 群組，透過增加服務限制，最多可增加至 150 個群組。
Lambda
`AWS_LAMBDA` 身分驗證方法可讓您使用 連線至自訂身分提供者 AWS Lambda。
此選項提供與現有身分管理系統整合的彈性。Lambda 函數負責驗證使用者並傳回適當的存取政策。
自訂 (API Gateway)
`API_GATEWAY` 身分驗證方法 （在主控台中顯示為**自訂**) 可讓您使用同時提供使用者身分驗證和存取控制的自訂身分驗證方法。
此方法依賴 Amazon API Gateway 使用來自身分提供者的 API 呼叫來驗證使用者請求。您可以使用自訂方法，藉由目錄服務、資料庫名稱/密碼對，或一些其他機制來驗證使用者。
對於所有身分驗證方法，會指派政策給使用者，以定義他們對 Amazon S3 儲存貯體或 Amazon Elastic File System 檔案系統的存取。伺服器會透過 IAM 角色與 `AssumeRole`動作繼承使用者的信任關係，允許其代表使用者執行檔案操作。
## 命名慣例
AWS Transfer Family 針對資源識別符和 Amazon Resource Name (ARNs) 使用標準化格式。使用 API 時， AWS Transfer Family 了解這些慣例非常重要。
### ID 格式
下列慣例是以 AWS Transfer Family ID 格式觀察到的：
伺服器 IDs
`ServerId` 值採用 `s-01234567890abcdef` 的形式。
SSH 公IDs
`SshPublicKeyId` 值採用 `key-01234567890abcdef` 的形式。
連接器 IDs
`ConnectorId` 值採用 `c-01234567890abcdef` 的形式。
工作流程 IDs
`WorkflowId` 值採用 `w-01234567890abcdef` 的形式。
設定檔 IDs
`ProfileId` 值採用 `p-01234567890abcdef` 的形式。
WebApp IDs
`WebAppId` 值採用 `webapp-01234567890abcdef` 的形式。
### ARN 格式
Amazon Resource Name (ARN) 格式採用下列格式：
伺服器 ARNs
對於 伺服器，ARNs採用格式 `arn:aws:transfer:{{region}}:{{account-id}}:server/{{server-id}}`。
範例：`arn:aws:transfer:us-east-1:123456789012:server/s-01234567890abcdef`。
使用者 ARNs
針對使用者，ARN 採用 `arn:aws:transfer:{{region}}:{{account-id}}:user/{{server-id}}/{{username}}` 的形式。
範例：`arn:aws:transfer:us-east-1:123456789012:user/s-01234567890abcdef/user1`。
連接器 ARNs
對於連接器，ARNs 採用 形式`arn:aws:transfer:{{region}}:{{account-id}}:connector/{{connector-id}}`。
範例：`arn:aws:transfer:us-east-1:123456789012:connector/c-01234567890abcdef`。
工作流程 ARNs
對於工作流程，ARNs採用格式 `arn:aws:transfer:{{region}}:{{account-id}}:workflow/{{workflow-id}}`。
範例：`arn:aws:transfer:us-east-1:123456789012:workflow/w-01234567890abcdef`。
WebApp ARNs
對於 Web 應用程式，ARNs採用 形式`arn:aws:transfer:{{region}}:{{account-id}}:webapp/{{webapp-id}}`。
範例：`arn:aws:transfer:us-east-1:123456789012:webapp/webapp-01234567890abcdef`。
您可以使用 ARN 將鍵值對的標籤指派給實體。標籤是中繼資料，可用於分組或搜尋這些實體。舉例來說，標籤在會計用途方面就非常有用。
## DNS 和端點
AWS Transfer Family 針對 API 端點和伺服器端點使用標準化 DNS 命名慣例。了解這些端點對於設定用戶端和進行 API 呼叫至關重要。
### API 端點
API 端點用於進行 API 呼叫以管理 AWS Transfer Family 資源。這些端點採用下列形式：
標準 API 端點
標準 API 端點採用 形式`transfer.{{region}}.amazonaws.com`。
範例：`transfer.us-east-1.amazonaws.com`
雙堆疊 API 端點
AWS Transfer Family 提供可使用 IPv4 或 IPv6 請求存取的雙堆疊 API 端點：
+ https://transfer.*{{region-code}}*.api.aws
+ https://transfer-fips.*{{region-code}}*.api.aws
### 伺服器端點
檔案傳輸用戶端會使用伺服器端點來連線至 AWS Transfer Family 伺服器。這些端點採用下列形式：
標準伺服器端點
標準伺服器端點採用 形式`{{server-id}}.server.transfer.{{region}}.amazonaws.com`。
範例：`s-01234567890abcdef.server.transfer.us-east-1.amazonaws.com`
自訂主機名稱
您也可以為 AWS Transfer Family 伺服器設定自訂主機名稱。自訂主機名稱可用來為您的使用者提供更易於使用或品牌化的體驗。
若要使用自訂主機名稱，您必須：
1. 擁有網域名稱
1. 提供有效的憑證
1. 設定 DNS 記錄以指向您的 AWS Transfer Family 伺服器
如需依 AWS 區域列出的 AWS Transfer Family 端點完整清單，請參閱 中的[AWS Transfer Family 端點和配額](https://docs.aws.amazon.com/general/latest/gr/transfer-service.html)*AWS 一般參考*。