本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
CreateServer
在 AWS中基于所选文件传输协议实例化自动伸缩的虚拟服务器。当您更新启用文件传输协议的服务器或与用户一起工作时,使用分配给新创建的服务器的服务生成的 ServerId
属性。
请求语法
{
"Certificate": "string
",
"Domain": "string
",
"EndpointDetails": {
"AddressAllocationIds": [ "string
" ],
"SecurityGroupIds": [ "string
" ],
"SubnetIds": [ "string
" ],
"VpcEndpointId": "string
",
"VpcId": "string
"
},
"EndpointType": "string
",
"HostKey": "string
",
"IdentityProviderDetails": {
"DirectoryId": "string
",
"Function": "string
",
"InvocationRole": "string
",
"SftpAuthenticationMethods": "string
",
"Url": "string
"
},
"IdentityProviderType": "string
",
"LoggingRole": "string
",
"PostAuthenticationLoginBanner": "string
",
"PreAuthenticationLoginBanner": "string
",
"ProtocolDetails": {
"As2Transports": [ "string
" ],
"PassiveIp": "string
",
"SetStatOption": "string
",
"TlsSessionResumptionMode": "string
"
},
"Protocols": [ "string
" ],
"S3StorageOptions": {
"DirectoryListingOptimization": "string
"
},
"SecurityPolicyName": "string
",
"StructuredLogDestinations": [ "string
" ],
"Tags": [
{
"Key": "string
",
"Value": "string
"
}
],
"WorkflowDetails": {
"OnPartialUpload": [
{
"ExecutionRole": "string
",
"WorkflowId": "string
"
}
],
"OnUpload": [
{
"ExecutionRole": "string
",
"WorkflowId": "string
"
}
]
}
}
请求参数
有关所有操作的通用参数的信息,请参阅通用参数。
请求接受采用 JSON 格式的以下数据。
- Certificate
-
AWS Certificate Manager (ACM)证书的 Amazon 资源名称(ARN)。在
Protocols
设置为FTPS
时是必需的。要申请新的公共证书,请参阅 AWS Certificate Manager 用户指南中的申请公共证书。
要将现有证书导入 ACM,请参阅 AWS Certificate Manager 用户指南中的将证书导入 ACM。
要请求私有证书通过私有 IP 地址使用 FTPS,请参阅 AWS Certificate Manager 用户指南中的申请私有证书。
支持具有以下加密算法和密钥大小的证书:
-
2048 位 RSA (RSA_2048)
-
4096 位 RSA (RSA_4096)
-
Elliptic Prime Curve 256 位 (EC_prime256v1)
-
Elliptic Prime Curve 384 位 (EC_secp384r1)
-
Elliptic Prime Curve 521 位 (EC_secp521r1)
注意
证书必须是指定了 FQDN 或 IP 地址且具有有关颁发者的信息的有效 SSL/TLS X.509 版本 3 证书。
类型:字符串
长度约束:最小长度为 0。长度上限为 1600。
必需:否
-
- Domain
-
指定用于文件传输的存储系统的域。有两个域可用:Amazon Simple Storage Service 和 Amazon Elastic File System System (Amazon EFS)。默认值为 3。
注意
在创建用户后,将无法更改用户名。
类型:字符串
有效值:
S3 | EFS
必需:否
- EndpointDetails
-
要为服务器配置的 Virtual Private Cloud (VPC) 端点设置。当您在 VPC 中托管端点时,您可以使端点仅可供 VPC 内的资源访问,也可以附加弹性 IP 地址并使端点可由客户端通过 Internet 访问。您 VPC 的默认安全组会自动分配到您的端点。
类型:EndpointDetails 对象
必需:否
- EndpointType
-
您希望服务器使用的端点类型。您可以选择使服务器的端点可公开访问(PUBLIC),或将其托管在 VPC 内。如果端点在 VPC 中托管,您可以仅在 VPC 内限制对服务器和资源的访问,或者通过将弹性 IP 地址直接附加到其上,使其面向 Internet。
注意
2021 年 5 月 19 日之后, AWS 账户 如果您的账户
EndpointType=VPC_ENDPOINT
在 2021 年 5 月 19 日之前尚未使用自己的服务器创建服务器,则您将无法使用创建服务器。如果您已EndpointType=VPC_ENDPOINT
在 2021 年 5 月 19 AWS 账户 日当天或之前创建过服务器,则不会受到影响。在此日期之后,使用EndpointType
=VPC
。有关更多信息,请参阅 停止使用 VPC_ENDPOINT。
建议您使用
VPC
作为EndpointType
。使用此终端节点类型,您可以选择将最多三个弹性 IPv4 地址(包括 BYO IP)直接与服务器的终端节点相关联,并使用 VPC 安全组限制客户端的公有 IP 地址的流量。如果EndpointType
设置为VPC_ENDPOINT
,则无法实现此操作。类型:字符串
有效值:
PUBLIC | VPC | VPC_ENDPOINT
必需:否
- HostKey
-
用于启用 SFTP 的服务器的 RSA、ECDSA 或 ED25519 私钥。如果要轮换密钥,可以添加多个主机密钥,也可以添加一组使用不同算法的活动密钥。
使用以下命令生成不带密码的 RSA 2048 位密钥:
ssh-keygen -t rsa -b 2048 -N "" -m PEM -f my-new-server-key
.为
-b
选项使用最小值 2048。您可以使用 3072 或 4096 创建更强的密钥。使用以下命令生成不带密码的 ECDSA 256 位密钥:
ssh-keygen -t ecdsa -b 256 -N "" -m PEM -f my-new-server-key
.ECDSA 的
-b
选项的有效值为 256、384 和 521。使用以下命令生成不带密码的 ED25519 密钥:
ssh-keygen -t ed25519 -N "" -f my-new-server-key
.对于所有这些命令,你可以my-new-server-key用你选择的字符串替换。
重要
如果您不打算将现有用户从启用 SFTP 的现有服务器迁移到新服务器,不要更新主机密钥。意外更改服务器的主机密钥会导致中断。
有关更多信息,请参阅《用户指南》中的更新启用 SFTP 的服务器的主机密钥。 AWS Transfer Family
类型:字符串
长度约束:最小长度为 0。最大长度为 4096。
必需:否
- IdentityProviderDetails
-
在
IdentityProviderType
设置为AWS_DIRECTORY_SERVICE
或 时是必需的。接受包含使用AWS_DIRECTORY_SERVICE
中的目录或调用客户提供的身份验证 API(包括 API 网关 URL)所需的所有信息的数组。在IdentityProviderType
设置为SERVICE_MANAGED
时不是必需的。类型:IdentityProviderDetails 对象
必需:否
- IdentityProviderType
-
服务器的身份验证模式。默认值为
SERVICE_MANAGED
,允许您在 AWS Transfer Family 服务中存储和访问用户凭证。用于
AWS_DIRECTORY_SERVICE
访问本地环境中的活动目录组 AWS Directory Service for Microsoft Active Directory 或 Microsoft Active Directory 或 AWS 使用 AD Connector。此选项还要求您使用IdentityProviderDetails
参数提供 Directory ID。使用
API_GATEWAY
值以与您选择的身份提供者集成。API_GATEWAY
设置要求您提供 Amazon API Gateway 端点 URL 以使用IdentityProviderDetails
参数调用身份验证。使用该
AWS_LAMBDA
值可直接使用 AWS Lambda 函数作为您的身份提供商。如果选择该值,则必须在Function
数据类型的IdentityProviderDetails
参数中指定 Lambda 函数的 ARN。类型:字符串
有效值:
SERVICE_MANAGED | API_GATEWAY | AWS_DIRECTORY_SERVICE | AWS_LAMBDA
必需:否
- LoggingRole
-
(IAM) 角色的亚马逊资源名称 (ARN),允许服务器为亚马逊 S3 或 Amazon efSevents 开启亚马逊 CloudWatch 日志记录。 AWS Identity and Access Management 设置后,您可以在 CloudWatch 日志中查看用户活动。
类型:字符串
长度约束:最小长度为 0。最大长度为 2048。
模式:
(|arn:.*role/\S+)
必需:否
- PostAuthenticationLoginBanner
-
指定用户连接到服务器时要显示的字符串。此字符串在用户进行身份验证后显示。
注意
SFTP 协议不支持身份验证后显示横幅。
类型:字符串
长度约束:最小长度为 0。最大长度为 4096。
模式:
[\x09-\x0D\x20-\x7E]*
必需:否
- PreAuthenticationLoginBanner
-
指定用户连接到服务器时要显示的字符串。此字符串在用户进行身份验证前显示。例如,以下横幅显示有关使用系统的详细信息:
This system is for the use of authorized users only. Individuals using this computer system without authority, or in excess of their authority, are subject to having all of their activities on this system monitored and recorded by system personnel.
类型:字符串
长度约束:最小长度为 0。最大长度为 4096。
模式:
[\x09-\x0D\x20-\x7E]*
必需:否
- ProtocolDetails
-
为服务器配置的协议设置。
-
要指示被动模式(适用于 FTP 和 FTPS 协议),请使用
PassiveIp
参数。输入一个点分四组的 IPv4 地址,例如防火墙、路由器或负载均衡器的外部 IP 地址。 -
要忽略当客户端尝试对您上传到 S3 桶的文件使用
SETSTAT
命令时生成的错误,请使用SetStatOption
参数。要让 AWS Transfer Family 服务器忽略SETSTAT
命令并上传文件而不必对 SFTP 客户端进行任何更改,请将该值设置为。ENABLE_NO_OP
如果您将SetStatOption
参数设置为ENABLE_NO_OP
,Transfer Family 会生成一个到 Amazon Logs 的 CloudWatch 日志条目,以便您可以确定客户何时SETSTAT
拨打电话。 -
要确定您的 AWS Transfer Family 服务器是否通过唯一的会话 ID 恢复最近协商的会话,请使用
TlsSessionResumptionMode
参数。 -
As2Transports
指示 AS2 消息的传输方法。目前仅支持 HTTP。
类型:ProtocolDetails 对象
必需:否
-
- Protocols
-
指定文件传输协议客户端可以用来连接到服务器端点的一个或多个文件传输协议。可用的协议包括:
-
SFTP
(Secure Shell (SSH) 文件传输协议):通过 SSH 的文件传输 -
FTPS
(文件传输协议安全):使用 TLS 加密的文件传输 -
FTP
(文件传输协议):未加密的文件传输 -
AS2
(适用性声明 2):用于传输结构化 business-to-business 数据
注意
-
如果选择
FTPS
,则必须选择存储在 AWS Certificate Manager (ACM) 中的证书,当客户端通过 FTPS 连接到服务器时,该证书用于识别您的服务器。 -
如果
Protocol
包括FTP
或FTPS
,则EndpointType
必须为VPC
,且IdentityProviderType
必须为AWS_DIRECTORY_SERVICE
、AWS_LAMBDA
或API_GATEWAY
。 -
如果
Protocol
包含FTP
,则无法关联AddressAllocationIds
。 -
如果仅将
Protocol
设置为SFTP
,则可以将EndpointType
设置为PUBLIC
,并且可以将IdentityProviderType
设置为任何支持的身份类型:SERVICE_MANAGED
、AWS_DIRECTORY_SERVICE
、AWS_LAMBDA
或API_GATEWAY
。 -
如果
Protocol
包括AS2
,则EndpointType
必须是VPC
,并且域必须是 Amazon S3。
类型:字符串数组
数组成员:最少 1 个物品。最多 4 项。
有效值:
SFTP | FTP | FTPS | AS2
必需:否
-
- S3StorageOptions
-
指定是否优化您的 Amazon S3 目录的性能。默认情况下,将禁用该功能。
默认情况下,主目录映射
TYPE
的值为。DIRECTORY
如果启用此选项,则需要将显式设置为,HomeDirectoryMapEntry
Type
以FILE
使映射具有文件目标。类型:S3StorageOptions 对象
必需:否
- SecurityPolicyName
-
指定服务器安全策略的名称。
类型:字符串
长度限制:长度下限为 0。最大长度为 100。
模式:
Transfer[A-Za-z0-9]*SecurityPolicy-[A-Za-z0-9-]+
必需:否
- StructuredLogDestinations
-
指定将服务器日志发送到日志组。
要指定日志组,必须提供现有日志组的 ARN。在这种情况下,日志组的格式如下所示:
arn:aws:logs:region-name:amazon-account-id:log-group:log-group-name:*
例如,
arn:aws:logs:us-east-1:111122223333:log-group:mytestgroup:*
如果您之前为服务器指定了日志组,则可以通过在
update-server
调用中为该参数提供空值来清除该日志组,从而关闭结构化日志记录。例如:update-server --server-id s-1234567890abcdef0 --structured-log-destinations
类型:字符串数组
数组成员:最少 0 项。最多 1 项。
长度约束:最小长度为 20。长度上限为 1600。
模式:
arn:\S+
必需:否
- Tags
-
可用于分组和搜索服务器的键/值对。
类型:Tag 对象数组
数组成员:最少 1 个物品。最多 50 项。
必需:否
- WorkflowDetails
-
指定要分配的工作流的工作流 ID 以及用于执行工作流的执行角色。
除了要在文件完全上传时执行的工作流,
WorkflowDetails
还可能包含在部分文件上传时执行的工作流的工作流 ID(和执行角色)。在文件仍在上传时,如果断开连接,则会发生部分上传。类型:WorkflowDetails 对象
必需:否
响应语法
{
"ServerId": "string"
}
响应元素
如果此操作成功,则该服务将会发送回 HTTP 200 响应。
服务以 JSON 格式返回以下数据。
- ServerId
-
创建的服务器的服务分配的 ID。
类型:字符串
长度限制:固定长度为 19。
模式:
s-([0-9a-f]{17})
错误
有关所有操作返回的常见错误的信息,请参阅常见错误。
- AccessDeniedException
-
您没有足够的访问权限,无法执行该操作。
HTTP 状态代码:400
- InternalServiceError
-
当 AWS Transfer Family 服务中发生错误时,会引发此异常。
HTTP 状态代码:500
- InvalidRequestException
-
当客户端提交格式错误的请求时,会引发此异常。
HTTP 状态代码:400
- ResourceExistsException
-
请求的资源不存在,或者存在于为命令指定的区域以外的区域。
HTTP 状态代码:400
- ResourceNotFoundException
-
当 Transfer Family 服务找不到资源时,就会 AWS引发此异常。
HTTP 状态代码:400
- ServiceUnavailableException
-
请求失败,因为 Trans AWS fer Family 服务不可用。
HTTP 状态代码:500
- ThrottlingException
-
由于请求限制而导致请求被拒绝。
HTTP 状态代码:400
示例
示例
以下 示例使用 创建一个新的 表。
示例请求
{
"EndpointType": "VPC",
"EndpointDetails":...,
"HostKey": "Your RSA private key",
"IdentityProviderDetails": "IdentityProvider",
"IdentityProviderType": "SERVICE_MANAGED",
"LoggingRole": "CloudWatchLoggingRole",
"Tags": [
{
"Key": "Name",
"Value": "MyServer"
}
]
}
示例
这是此 API 调用的示例响应。
示例响应
{
"ServerId": "s-01234567890abcdef"
}
另请参阅
有关在特定语言的 AWS SDK 中使用此 API 的更多信息,请参阅以下内容: