Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

Amazon Transfer Family API 参考

Transfer Family 的完整 API 参考指南可在 Amazon Transfer Family API 参考中找到。

Amazon Transfer Family 是一项安全的传输服务，您可以使用它通过以下协议将文件传入和传出亚马逊简单存储服务 (Amazon S3) Storage Service 存储：

服务器、用户和角色均由其 Amazon 资源名称 (ARN) 标识。您可以为具有 ARN 的实体分配标签（键值对）。标签是可用于分组或搜索这些实体的元数据。标签有用的一个例子是用于会计目的。

在 Amazon Transfer Family ID 格式中应遵守以下惯例：

Amazon 资源名称 (ARN) 格式采用以下形式：

正在使用的 DNS 条目（端点）如下所示：

此 API 接口参考 Amazon Transfer Family 包含可用于管理的编程接口的文档 Amazon Transfer Family。参考结构如下所示：

提出 API 请求

除了使用控制台外，您还可以使用 Amazon Transfer Family API 以编程方式配置和管理服务器。本节介绍 Amazon Transfer Family 操作、身份验证请求签名和错误处理。有关 Transfer Family 可用的区域和端点的信息，请参阅 Amazon Web Services 一般参考 中的 Amazon Transfer Family 端点和配额

Transfer Family 必填请求标头

本部分描述您每次向 Amazon Transfer Family发送 POST 请求时必须使用的标头。您将 HTTP 标头包含在内以识别有关请求的密钥信息，包括您希望调用的操作、请求的日期以及表示您拥有请求发送者授权的信息。标头区分大小写，其次序不重要。

以下示例显示了ListServers操作中使用的标头。

POST / HTTP/1.1
Host: transfer.ap-northeast-1.amazonaws.com.cn
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” 开头的标题是特定的。 Amazon列出的其他所有标头均为 HTTP 事务中使用的普通标头。

Transfer Family 请求输入和签名

所有请求输入都必须作为请求正文中的 JSON 负载的一部分发送。对于所有请求字段均为可选字段的操作（例如 ListServers），您仍然需要在请求正文中提供一个空的 JSON 对象，例如 {}。例如，T request/response ransfer Family 有效载荷的结构记录在现有的 API 参考中DescribeServer。

Transfer Family 支持使用 Amazon 签名版本 4 进行身份验证。有关详细信息，请参阅签署 Amazon 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"
}

可用的库

Amazon 为喜欢使用特定语言的 API 而不是命令行工具和 Query API 来构建应用程序的软件开发人员提供了库、示例代码、教程和其他资源。这些库提供了一些基本功能 (未包括 API 中)，比如请求身份验证、请求重试和错误处置，以便您轻松地开始工作。参见可供构建的工具 Amazon

有关所有语言的库和示例代码，请参阅示例代码和库。

身份提供商

Amazon Transfer Family 支持多种身份提供商类型来对用户进行身份验证和管理。每台服务器只能使用一种身份验证方法，必须在创建服务器时选择这种方法。

对于所有身份验证方法，都会为用户分配策略，这些策略定义了他们对 Amazon S3 存储桶或 Amazon Elastic File System 文件系统的访问权限。服务器通过带有操作的 IAM 角色从用户那里继承信任关系，允许它代表用户执行文件操作。AssumeRole

命名惯例

Amazon Transfer Family 对资源标识符和 Amazon 资源名称 (ARN) 使用标准化格式。使用 Amazon Transfer Family API 时，了解这些约定非常重要。

身份证格式

在 Amazon Transfer Family ID 格式中应遵守以下惯例：

ARN 格式

Amazon 资源名称 (ARN) 格式采用以下形式：

您可以为具有 ARN 的实体分配标签（键值对）。标签是可用于分组或搜索这些实体的元数据。标签有用的一个例子是用于会计目的。

DNS 和端点

Amazon Transfer Family 对 API 端点和服务器端点使用标准化的 DNS 命名约定。了解这些端点对于配置客户端和进行 API 调用至关重要。

API 终端节点

API 端点用于发出 API 调用以管理 Amazon Transfer Family 资源。这些端点采用以下形式：

服务器端点

文件传输客户端使用服务器端点来连接 Amazon Transfer Family 服务器。这些端点采用以下形式：

有关按 Amazon 区域划分的 Amazon Transfer Family 终端节点的完整列表，请参阅中的Amazon Transfer Family 终端节点和配额Amazon Web Services 一般参考。