提出 API 请求 - AWS Transfer Family
Transfer Family 必填请求标头Transfer Family 请求输入和签名错误响应可用的库

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

提出 API 请求

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

注意

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

Transfer Family 必填请求标头

本部分描述您每次向 AWS Transfer Family发送 POST 请求时必须使用的标头。您将 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 事务中使用的普通标头。

标头 描述
Authorization 授权标头为必填项。格式为标准的 Sigv4 请求签名，该签名记录在 签署 AWS API 请求中。
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 端点的更多信息，请参阅AWS 一般参考中的AWS Transfer Family 端点和配额。

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

您必须在 HTTP Date 标头或AWS x-amz-date标头中提供时间戳。(部分 HTTP 客户端库文件不允许您设置Date标头。) 当 x-amz-date 标头存在时，Transfer Family 会在请求验证期间忽略任何Date 标头。x-amz-date 格式必须为 YYYYMMDD'T'HHMMSS'Z' 格式的 ISO8601 Basic。

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

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

x-amz-target: TransferService.operationName

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

Transfer Family 请求输入和签名

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

Transfer Family 支持使用 AWS 签名版本 4 进行身份验证。有关详细信息，请参阅签署 AWS API 请求。

错误响应

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

  • Content-Type: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。

类型：字符串

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"
}

可用的库

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

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