本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 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 S3) Storage Service 存储：
+ Secure Shell (SSH) 文件传输协议 (SFTP)
+ 安全文件传输协议 (FTPS)
+ 文件传输协议 (FTP)
+ 适用性声明 2 (AS2)
服务器、用户和角色均由其 Amazon 资源名称 (ARN) 标识。您可以为具有 ARN 的实体分配标签（键值对）。标签是可用于分组或搜索这些实体的元数据。标签有用的一个例子是用于会计目的。
在 AWS Transfer Family ID 格式中应遵守以下惯例：
+ `ServerId` 值采用 `s-01234567890abcdef` 形式。
+ `SshPublicKeyId` 值采用 `key-01234567890abcdef` 形式。
Amazon 资源名称 (ARN) 格式采用以下形式：
+ 对于服务器，ARN 采用 `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)。
**提示**
您可以将 `--generate-cli-skeleton` 参数与任何 API 调用一起使用来生成和显示参数模板，而不是实际运行命令。然后，您可以使用生成的模板进行自定义，并将其用作后续命令的输入。有关详细信息，请参阅[生成并使用参数骨架文件](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 一般参考* 中的 [AWS Transfer Family 端点和配额](https://docs.aws.amazon.com/general/latest/gr/transfer-service.html)
**注意**
使用 Tran AWS sfer Family; 开发应用程序时，也可以使用软件开发工具包。适用于 Java、.Net 和 PHP 的 AWS SDK 包含底层的 Transfer Family API，从而简化您的编程任务。有关下载开发 SDK 库的信息，请参阅[示例代码库](https://aws.amazon.com/code)。
### Transfer Family 必填请求标头
本部分描述您每次向 AWS Transfer Family发送 POST 请求时必须使用的标头。您将 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 对象，例如 `{}`。例如，T request/response ransfer Family 有效载荷的结构记录在现有的 API 参考中[DescribeServer](https://docs.aws.amazon.com/transfer/latest/userguide/API_DescribeServer.html)。
Transfer Family 支持使用 AWS 签名版本 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` 为现有用户的用户名。
*类型*：字符串
**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 为喜欢使用特定语言的 API 而不是命令行工具和 Query API 来构建应用程序的软件开发人员提供了库、示例代码、教程和其他资源。这些库提供了一些基本功能 (未包括 API 中)，比如请求身份验证、请求重试和错误处置，以便您轻松地开始工作。参见[可供构建的工具 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`身份验证方法允许你与 Microsoft Active Directory 的 AWS 目录服务 (AWS Directory Service for Microsoft Active Directory) 集成。
此选项使您能够通过现有的 Active Directory 组管理用户身份验证和访问权限。用户可以使用其活动目录凭据进行身份验证。
每台服务器的默认限制为 100 个 Active Directory 组，通过提高服务限制可以将其增加到最多 150 个组。
Lambda
`AWS_LAMBDA`身份验证方法允许您使用连接到自定义身份提供商 AWS Lambda。
此选项提供了与现有身份管理系统集成的灵活性。Lambda 函数负责对用户进行身份验证并返回相应的访问策略。
自定义（API Gateway）
`API_GATEWAY`身份验证方法（在控制台中显示为 “**自定义**”）允许您使用既提供用户身份验证又提供访问控制的自定义身份验证方法。
此方法依赖于 Amazon API Gateway 来使用您身份提供商的 API 调用对用户请求进行身份验证。您可以使用此自定义方法根据目录服务、数据库对或其他机制name/password 对用户进行身份验证。
对于所有身份验证方法，都会为用户分配策略，这些策略定义了他们对 Amazon S3 存储桶或 Amazon Elastic File System 文件系统的访问权限。服务器通过带有操作的 IAM 角色从用户那里继承信任关系，允许它代表用户执行文件操作。`AssumeRole`
## 命名惯例
AWS Transfer Family 对资源标识符和 Amazon 资源名称 (ARN) 使用标准化格式。使用 AWS Transfer Family API 时，了解这些约定非常重要。
### 身份证格式
在 AWS Transfer Family ID 格式中应遵守以下惯例：
服务器 ID
`ServerId` 值采用 `s-01234567890abcdef` 形式。
SSH 公钥 ID
`SshPublicKeyId` 值采用 `key-01234567890abcdef` 形式。
连接器 ID
`ConnectorId` 值采用 `c-01234567890abcdef` 形式。
工作流程 ID
`WorkflowId` 值采用 `w-01234567890abcdef` 形式。
个人资料 ID
`ProfileId` 值采用 `p-01234567890abcdef` 形式。
WebApp 身份证
`WebAppId` 值采用 `webapp-01234567890abcdef` 形式。
### ARN 格式
Amazon 资源名称 (ARN) 格式采用以下形式：
服务器 ARN
对于服务器，ARN 采用 `arn:aws:transfer:{{region}}:{{account-id}}:server/{{server-id}}` 形式。
示例：`arn:aws:transfer:us-east-1:123456789012:server/s-01234567890abcdef`。
用户 ARN
对于用户，ARN 采用 `arn:aws:transfer:{{region}}:{{account-id}}:user/{{server-id}}/{{username}}` 形式。
示例：`arn:aws:transfer:us-east-1:123456789012:user/s-01234567890abcdef/user1`。
连接器 ARN
对于连接器，ARN 采用以下形式`arn:aws:transfer:{{region}}:{{account-id}}:connector/{{connector-id}}`。
示例：`arn:aws:transfer:us-east-1:123456789012:connector/c-01234567890abcdef`。
工作流程 ARN
对于工作流程，ARN 采用以下形式`arn:aws:transfer:{{region}}:{{account-id}}:workflow/{{workflow-id}}`。
示例：`arn:aws:transfer:us-east-1:123456789012:workflow/w-01234567890abcdef`。
WebApp ARN
对于 Web 应用程序，ARN 采用以下形式`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`
Dual-Stack API 端点
AWS Transfer Family 提供双堆栈 API 端点，可以使用 IPv4 或 IPv6 请求访问这些端点：
+ 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 终端节点和配额*AWS 一般参考*](https://docs.aws.amazon.com/general/latest/gr/transfer-service.html)。