提出 API 请求 - Amazon Transfer Family
Transfer Family 必需的请求标题Transfer Family 请求输入和签名错误响应可用的库
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 Amazon Web Services 服务入门。

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

提出 API 请求

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

注意

您也可以使用Amazon使用 Transfer Family 开发应用程序时开发工具包；这些区域有：Amazon适用于 Java、.Net 和 PHP 的开发工具包包含底层的 Transfer Family API，从而简化您的编程任务。有关下载开发工具包库的信息，请参阅示例代码库。

Transfer Family 必需的请求标题

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

下例展示了在ListServersoperation.

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特定于 RIGN。列出的其他所有标头均为 HTTP 事务中使用的普通标头。

标头 描述
Authorization 需要授权标头。格式为标准 Sigv4 请求签名，记录在Signature Version 4 签名流程.
Content-Type

使用application/x-amz-json-1.1作为向 Transfer Family 的所有请求的内容类型。

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

使用主机标头指定发送请求的 Transfer Family 终端节点。例如，transfer.us-east-1.amazonaws.com是美国东部（俄亥俄）区域的终端节点。有关可用于 Transfer Family 的终端节点的更多信息，请参阅Amazon Transfer Family终端节点和配额中的Amazon一般参考.

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

您必须在 HTTP 中提供时间戳。Date标头或Amazon x-amz-date标头。(部分 HTTP 客户端库文件不允许您设置Date标头。) 当x-amz-date标头存在，Transfer Family 将忽略任何内容。Date请求身份验证期间的标头。这些区域有：x-amz-date格式必须为 ISO8601，采用 YYYYYMMDD'T'HHMMSS'Z' 格式。

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

该标头指定 API 的版本以及您要请求的操作。目标标头值通过结合 API 版本和 API 名称而形成，其格式如下。

x-amz-target: TransferService.operationName

这些区域有：OoperationName值（例如ListServers）可从 API 列表中找到，ListServers.
x-amz-security-token 当用于签署请求的凭证是临时证书或会话证书时，必须使用此标头（有关详细信息，请参阅将临时凭证用于Amazon资源中的IAM 用户指南. 请参阅将签名添加到 HTTP 请求有关更多信息，请参阅 Amazon Web Services 一般参考。

Transfer Family 请求输入和签名

所有请求输入必须作为请求正文中 JSON 有效负载的一部分发送。例如，对于所有请求字段都是可选的操作ListServers，你仍然需要在请求正文中提供一个空的 JSON 对象，例如{}. 例如，在现有 API 参考中记录了 Transfer Family 有效负载请求/响应的结构描述服务器.

Transfer Family 支持使用Amazon签名版本 4. 有关如何签名的详细信息Amazon请参阅 API 请求有符号AmazonAPI 请求.

错误响应

当存在错误时，响应头信息会包含：

  • 内容类型：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是现有用户的用户名称。

类型：字符串

ResourceType

调用错误的资源类型。例如，如果您尝试创建已存在的用户，则ResourceType是User.

类型：字符串

秒后重试

重试命令前等待的秒数。

类型：字符串

错误响应示例

如果使用 DescribeServer 并指定不存在的服务器。

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

如果执行 API 导致发生限制，则返回以下 JSON 正文。

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

如果使用CreateServer并且您没有足够的权限来创建 Transfer Family 服务器。

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

如果使用CreateUserAPI 并指定已存在的用户。

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

可用的库

Amazon为倾向于使用特定语言的 API 而非命令行工具和查询 API 来构建应用程序的软件开发人员提供了库文件、示例代码、教程和其他资源。这些库提供了一些基本功能（未包括在 API 中），如请求身份验证、请求重试和错误处理，以便您更轻松地开始工作。请参阅要构建的工具Amazon

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