lib/aws-sdk-transfer/client.rb in aws-sdk-transfer-1.17.0 vs lib/aws-sdk-transfer/client.rb in aws-sdk-transfer-1.18.0

- old
+ new

@@ -277,12 +277,11 @@ # seconds to wait when opening a HTTP session before raising a # `Timeout::Error`. # # @option options [Integer] :http_read_timeout (60) The default # number of seconds to wait for response data. This value can - # safely be set - # per-request on the session yielded by {#session_for}. + # safely be set per-request on the session. # # @option options [Float] :http_idle_timeout (5) The number of # seconds a connection is allowed to sit idle before it is # considered stale. Stale connections are closed and removed # from the pool before making a request. @@ -290,11 +289,11 @@ # @option options [Float] :http_continue_timeout (1) The number of # seconds to wait for a 100-continue response before sending the # request body. This option has no effect unless the request has # "Expect" header set to "100-continue". Defaults to `nil` which # disables this behaviour. This value can safely be set per - # request on the session yielded by {#session_for}. + # request on the session. # # @option options [Boolean] :http_wire_trace (false) When `true`, # HTTP debug output will be sent to the `:logger`. # # @option options [Boolean] :ssl_verify_peer (true) When `true`, @@ -317,70 +316,94 @@ super end # @!group API Operations - # Instantiates an autoscaling virtual server based on Secure File - # Transfer Protocol (SFTP) in AWS. When you make updates to your server - # or when you work with users, use the service-generated `ServerId` - # property that is assigned to the newly created server. + # Instantiates an autoscaling virtual server based on the selected file + # transfer protocol in AWS. When you make updates to your file transfer + # protocol-enabled server or when you work with users, use the + # service-generated `ServerId` property that is assigned to the newly + # created server. # + # @option params [String] :certificate + # The Amazon Resource Name (ARN) of the AWS Certificate Manager (ACM) + # certificate. Required when `Protocols` is set to `FTPS`. + # # @option params [Types::EndpointDetails] :endpoint_details # The virtual private cloud (VPC) endpoint settings that are configured - # for your SFTP server. With a VPC endpoint, you can restrict access to - # your SFTP server to resources only within your VPC. To control - # incoming internet traffic, you will need to invoke the `UpdateServer` - # API and attach an Elastic IP to your server's endpoint. + # for your file transfer protocol-enabled server. When you host your + # endpoint within your VPC, you can make it accessible only to resources + # within your VPC, or you can attach Elastic IPs and make it accessible + # to clients over the internet. Your VPC's default security groups are + # automatically assigned to your endpoint. # # @option params [String] :endpoint_type - # The type of VPC endpoint that you want your SFTP server to connect to. - # You can choose to connect to the public internet or a virtual private - # cloud (VPC) endpoint. With a VPC endpoint, you can restrict access to - # your SFTP server and resources only within your VPC. + # The type of VPC endpoint that you want your file transfer + # protocol-enabled server to connect to. You can choose to connect to + # the public internet or a virtual private cloud (VPC) endpoint. With a + # VPC endpoint, you can restrict access to your server and resources + # only within your VPC. # # @option params [String] :host_key # The RSA private key as generated by the `ssh-keygen -N "" -f # my-new-server-key` command. # # If you aren't planning to migrate existing users from an existing - # SFTP server to a new AWS SFTP server, don't update the host key. + # SFTP-enabled server to a new server, don't update the host key. # Accidentally changing a server's host key can be disruptive. # - # For more information, see - # "https://alpha-docs-aws.amazon.com/transfer/latest/userguide/configuring-servers.html#change-host-key" - # in the *AWS SFTP User Guide.* + # For more information, see [Changing the Host Key for Your AWS Transfer + # Family Server][1] in the *AWS Transfer Family User Guide*. # + # + # + # [1]: https://docs.aws.amazon.com/transfer/latest/userguide/configuring-servers.html#change-host-key + # # @option params [Types::IdentityProviderDetails] :identity_provider_details - # This parameter is required when the `IdentityProviderType` is set to - # `API_GATEWAY`. Accepts an array containing all of the information - # required to call a customer-supplied authentication API, including the - # API Gateway URL. This property is not required when the - # `IdentityProviderType` is set to `SERVICE_MANAGED`. + # Required when `IdentityProviderType` is set to `API_GATEWAY`. Accepts + # an array containing all of the information required to call a + # customer-supplied authentication API, including the API Gateway URL. + # Not required when `IdentityProviderType` is set to `SERVICE_MANAGED`. # # @option params [String] :identity_provider_type - # Specifies the mode of authentication for the SFTP server. The default - # value is `SERVICE_MANAGED`, which allows you to store and access SFTP - # user credentials within the AWS Transfer for SFTP service. Use the - # `API_GATEWAY` value to integrate with an identity provider of your - # choosing. The `API_GATEWAY` setting requires you to provide an API - # Gateway endpoint URL to call for authentication using the - # `IdentityProviderDetails` parameter. + # Specifies the mode of authentication for a file transfer + # protocol-enabled server. The default value is `SERVICE_MANAGED`, which + # allows you to store and access user credentials within the AWS + # Transfer Family service. Use the `API_GATEWAY` value to integrate with + # an identity provider of your choosing. The `API_GATEWAY` setting + # requires you to provide an API Gateway endpoint URL to call for + # authentication using the `IdentityProviderDetails` parameter. # # @option params [String] :logging_role - # A value that allows the service to write your SFTP users' activity to - # your Amazon CloudWatch logs for monitoring and auditing purposes. + # Allows the service to write your users' activity to your Amazon + # CloudWatch logs for monitoring and auditing purposes. # + # @option params [Array<String>] :protocols + # Specifies the file transfer protocol or protocols over which your file + # transfer protocol client can connect to your server's endpoint. The + # available protocols are: + # + # * Secure Shell (SSH) File Transfer Protocol (SFTP): File transfer over + # SSH + # + # * File Transfer Protocol Secure (FTPS): File transfer with TLS + # encryption + # + # * File Transfer Protocol (FTP): Unencrypted file transfer + # # @option params [Array<Types::Tag>] :tags - # Key-value pairs that can be used to group and search for servers. + # Key-value pairs that can be used to group and search for file transfer + # protocol-enabled servers. # # @return [Types::CreateServerResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods: # # * {Types::CreateServerResponse#server_id #server_id} => String # # @example Request syntax with placeholder values # # resp = client.create_server({ + # certificate: "Certificate", # endpoint_details: { # address_allocation_ids: ["AddressAllocationId"], # subnet_ids: ["SubnetId"], # vpc_endpoint_id: "VpcEndpointId", # vpc_id: "VpcId", @@ -391,10 +414,11 @@ # url: "Url", # invocation_role: "Role", # }, # identity_provider_type: "SERVICE_MANAGED", # accepts SERVICE_MANAGED, API_GATEWAY # logging_role: "Role", + # protocols: ["SFTP"], # accepts SFTP, FTP, FTPS # tags: [ # { # key: "TagKey", # required # value: "TagValue", # required # }, @@ -412,109 +436,116 @@ def create_server(params = {}, options = {}) req = build_request(:create_server, params) req.send_request(options) end - # Creates a user and associates them with an existing Secure File - # Transfer Protocol (SFTP) server. You can only create and associate - # users with SFTP servers that have the `IdentityProviderType` set to - # `SERVICE_MANAGED`. Using parameters for `CreateUser`, you can specify - # the user name, set the home directory, store the user's public key, - # and assign the user's AWS Identity and Access Management (IAM) role. - # You can also optionally add a scope-down policy, and assign metadata - # with tags that can be used to group and search for users. + # Creates a user and associates them with an existing file transfer + # protocol-enabled server. You can only create and associate users with + # servers that have the `IdentityProviderType` set to `SERVICE_MANAGED`. + # Using parameters for `CreateUser`, you can specify the user name, set + # the home directory, store the user's public key, and assign the + # user's AWS Identity and Access Management (IAM) role. You can also + # optionally add a scope-down policy, and assign metadata with tags that + # can be used to group and search for users. # # @option params [String] :home_directory - # The landing directory (folder) for a user when they log in to the - # server using their SFTP client. + # The landing directory (folder) for a user when they log in to the file + # transfer protocol-enabled server using the client. # - # An example is &lt;`your-Amazon-S3-bucket-name>/home/username`. + # An example is `your-Amazon-S3-bucket-name>/home/username`. # # @option params [String] :home_directory_type # The type of landing directory (folder) you want your users' home - # directory to be when they log into the SFTP server. If you set it to - # `PATH`, the user will see the absolute Amazon S3 bucket paths as is in - # their SFTP clients. If you set it `LOGICAL`, you will need to provide - # mappings in the `HomeDirectoryMappings` for how you want to make S3 - # paths visible to your user. + # directory to be when they log into the file transfer protocol-enabled + # server. If you set it to `PATH`, the user will see the absolute Amazon + # S3 bucket paths as is in their file transfer protocol clients. If you + # set it `LOGICAL`, you will need to provide mappings in the + # `HomeDirectoryMappings` for how you want to make Amazon S3 paths + # visible to your users. # # @option params [Array<Types::HomeDirectoryMapEntry>] :home_directory_mappings - # Logical directory mappings that specify what S3 paths and keys should - # be visible to your user and how you want to make them visible. You - # will need to specify the "`Entry`" and "`Target`" pair, where + # Logical directory mappings that specify what Amazon S3 paths and keys + # should be visible to your user and how you want to make them visible. + # You will need to specify the "`Entry`" and "`Target`" pair, where # `Entry` shows how the path is made visible and `Target` is the actual - # S3 path. If you only specify a target, it will be displayed as is. You - # will need to also make sure that your AWS IAM Role provides access to - # paths in `Target`. The following is an example. + # Amazon S3 path. If you only specify a target, it will be displayed as + # is. You will need to also make sure that your AWS IAM Role provides + # access to paths in `Target`. The following is an example. # # `'[ "/bucket2/documentation", \{ "Entry": "your-personal-report.pdf", # "Target": "/bucket3/customized-reports/$\{transfer:UserName\}.pdf" \} # ]'` # - # In most cases, you can use this value instead of the scope down policy + # In most cases, you can use this value instead of the scope-down policy # to lock your user down to the designated home directory ("chroot"). # To do this, you can set `Entry` to '/' and set `Target` to the # HomeDirectory parameter value. # - # <note markdown="1"> If the target of a logical directory entry does not exist in S3, the - # entry will be ignored. As a workaround, you can use the S3 api to - # create 0 byte objects as place holders for your directory. If using - # the CLI, use the s3api call instead of s3 so you can use the - # put-object operation. For example, you use the following: `aws s3api - # put-object --bucket bucketname --key path/to/folder/`. Make sure that - # the end of the key name ends in a / for it to be considered a folder. + # <note markdown="1"> If the target of a logical directory entry does not exist in Amazon + # S3, the entry will be ignored. As a workaround, you can use the Amazon + # S3 api to create 0 byte objects as place holders for your directory. + # If using the CLI, use the `s3api` call instead of `s3` so you can use + # the put-object operation. For example, you use the following: `aws + # s3api put-object --bucket bucketname --key path/to/folder/`. Make sure + # that the end of the key name ends in a '/' for it to be considered a + # folder. # # </note> # # @option params [String] :policy # A scope-down policy for your user so you can use the same IAM role # across multiple users. This policy scopes down user access to portions # of their Amazon S3 bucket. Variables that you can use inside this # policy include `$\{Transfer:UserName\}`, # `$\{Transfer:HomeDirectory\}`, and `$\{Transfer:HomeBucket\}`. # - # <note markdown="1"> For scope-down policies, AWS Transfer for SFTP stores the policy as a + # <note markdown="1"> For scope-down policies, AWS Transfer Family stores the policy as a # JSON blob, instead of the Amazon Resource Name (ARN) of the policy. # You save the policy as a JSON blob and pass it in the `Policy` # argument. # - # For an example of a scope-down policy, see - # "https://docs.aws.amazon.com/transfer/latest/userguide/users.html#users-policies-scope-down"&gt;Creating - # a Scope-Down Policy. + # For an example of a scope-down policy, see [Creating a Scope-Down + # Policy][1]. # - # For more information, see - # "https://docs.aws.amazon.com/STS/latest/APIReference/API\_AssumeRole.html" - # in the *AWS Security Token Service API Reference*. + # For more information, see [AssumeRole][2] in the *AWS Security Token + # Service API Reference*. # # </note> # + # + # + # [1]: https://docs.aws.amazon.com/transfer/latest/userguide/users.html#users-policies-scope-down + # [2]: https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html + # # @option params [required, String] :role - # The IAM role that controls your user's access to your Amazon S3 + # The IAM role that controls your users' access to your Amazon S3 # bucket. The policies attached to this role will determine the level of # access you want to provide your users when transferring files into and # out of your Amazon S3 bucket or buckets. The IAM role should also - # contain a trust relationship that allows the SFTP server to access - # your resources when servicing your SFTP user's transfer requests. + # contain a trust relationship that allows the file transfer + # protocol-enabled server to access your resources when servicing your + # users' transfer requests. # # @option params [required, String] :server_id - # A system-assigned unique identifier for an SFTP server instance. This - # is the specific SFTP server that you added your user to. + # A system-assigned unique identifier for a file transfer + # protocol-enabled server instance. This is the specific server that you + # added your user to. # # @option params [String] :ssh_public_key_body # The public portion of the Secure Shell (SSH) key used to authenticate - # the user to the SFTP server. + # the user to the file transfer protocol-enabled server. # # @option params [Array<Types::Tag>] :tags # Key-value pairs that can be used to group and search for users. Tags # are metadata attached to users for any purpose. # # @option params [required, String] :user_name - # A unique string that identifies a user and is associated with a server - # as specified by the `ServerId`. This user name must be a minimum of 3 - # and a maximum of 32 characters long. The following are valid - # characters: a-z, A-Z, 0-9, underscore, and hyphen. The user name - # can't start with a hyphen. + # A unique string that identifies a user and is associated with a file + # transfer protocol-enabled server as specified by the `ServerId`. This + # user name must be a minimum of 3 and a maximum of 32 characters long. + # The following are valid characters: a-z, A-Z, 0-9, underscore, and + # hyphen. The user name can't start with a hyphen. # # @return [Types::CreateUserResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods: # # * {Types::CreateUserResponse#server_id #server_id} => String # * {Types::CreateUserResponse#user_name #user_name} => String @@ -555,17 +586,17 @@ def create_user(params = {}, options = {}) req = build_request(:create_user, params) req.send_request(options) end - # Deletes the Secure File Transfer Protocol (SFTP) server that you - # specify. + # Deletes the file transfer protocol-enabled server that you specify. # # No response returns from this operation. # # @option params [required, String] :server_id - # A unique system-assigned identifier for an SFTP server instance. + # A unique system-assigned identifier for a file transfer + # protocol-enabled server instance. # # @return [Struct] Returns an empty {Seahorse::Client::Response response}. # # @example Request syntax with placeholder values # @@ -585,12 +616,12 @@ # Deletes a user's Secure Shell (SSH) public key. # # No response is returned from this operation. # # @option params [required, String] :server_id - # A system-assigned unique identifier for a Secure File Transfer - # Protocol (SFTP) server instance that has the user assigned to it. + # A system-assigned unique identifier for a file transfer + # protocol-enabled server instance that has the user assigned to it. # # @option params [required, String] :ssh_public_key_id # A unique identifier used to reference your user's specific SSH key. # # @option params [required, String] :user_name @@ -614,25 +645,26 @@ def delete_ssh_public_key(params = {}, options = {}) req = build_request(:delete_ssh_public_key, params) req.send_request(options) end - # Deletes the user belonging to the server you specify. + # Deletes the user belonging to a file transfer protocol-enabled server + # you specify. # # No response returns from this operation. # # <note markdown="1"> When you delete a user from a server, the user's information is lost. # # </note> # # @option params [required, String] :server_id - # A system-assigned unique identifier for an SFTP server instance that - # has the user assigned to it. + # A system-assigned unique identifier for a file transfer + # protocol-enabled server instance that has the user assigned to it. # # @option params [required, String] :user_name - # A unique string that identifies a user that is being deleted from the - # server. + # A unique string that identifies a user that is being deleted from a + # file transfer protocol-enabled server. # # @return [Struct] Returns an empty {Seahorse::Client::Response response}. # # @example Request syntax with placeholder values # @@ -648,19 +680,20 @@ def delete_user(params = {}, options = {}) req = build_request(:delete_user, params) req.send_request(options) end - # Describes the server that you specify by passing the `ServerId` - # parameter. + # Describes a file transfer protocol-enabled server that you specify by + # passing the `ServerId` parameter. # - # The response contains a description of the server's properties. When + # The response contains a description of a server's properties. When # you set `EndpointType` to VPC, the response will contain the # `EndpointDetails`. # # @option params [required, String] :server_id - # A system-assigned unique identifier for an SFTP server. + # A system-assigned unique identifier for a file transfer + # protocol-enabled server. # # @return [Types::DescribeServerResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods: # # * {Types::DescribeServerResponse#server #server} => Types::DescribedServer # @@ -671,10 +704,11 @@ # }) # # @example Response structure # # resp.server.arn #=> String + # resp.server.certificate #=> String # resp.server.endpoint_details.address_allocation_ids #=> Array # resp.server.endpoint_details.address_allocation_ids[0] #=> String # resp.server.endpoint_details.subnet_ids #=> Array # resp.server.endpoint_details.subnet_ids[0] #=> String # resp.server.endpoint_details.vpc_endpoint_id #=> String @@ -683,10 +717,12 @@ # resp.server.host_key_fingerprint #=> String # resp.server.identity_provider_details.url #=> String # resp.server.identity_provider_details.invocation_role #=> String # resp.server.identity_provider_type #=> String, one of "SERVICE_MANAGED", "API_GATEWAY" # resp.server.logging_role #=> String + # resp.server.protocols #=> Array + # resp.server.protocols[0] #=> String, one of "SFTP", "FTP", "FTPS" # resp.server.server_id #=> String # resp.server.state #=> String, one of "OFFLINE", "ONLINE", "STARTING", "STOPPING", "START_FAILED", "STOP_FAILED" # resp.server.tags #=> Array # resp.server.tags[0].key #=> String # resp.server.tags[0].value #=> String @@ -699,24 +735,25 @@ def describe_server(params = {}, options = {}) req = build_request(:describe_server, params) req.send_request(options) end - # Describes the user assigned to a specific server, as identified by its - # `ServerId` property. + # Describes the user assigned to the specific file transfer + # protocol-enabled server, as identified by its `ServerId` property. # # The response from this call returns the properties of the user # associated with the `ServerId` value that was specified. # # @option params [required, String] :server_id - # A system-assigned unique identifier for an SFTP server that has this - # user assigned. + # A system-assigned unique identifier for a file transfer + # protocol-enabled server that has this user assigned. # # @option params [required, String] :user_name - # The name of the user assigned to one or more servers. User names are - # part of the sign-in credentials to use the AWS Transfer for SFTP - # service and perform file transfer tasks. + # The name of the user assigned to one or more file transfer + # protocol-enabled servers. User names are part of the sign-in + # credentials to use the AWS Transfer Family service and perform file + # transfer tasks. # # @return [Types::DescribeUserResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods: # # * {Types::DescribeUserResponse#server_id #server_id} => String # * {Types::DescribeUserResponse#user #user} => Types::DescribedUser @@ -756,24 +793,26 @@ req = build_request(:describe_user, params) req.send_request(options) end # Adds a Secure Shell (SSH) public key to a user account identified by a - # `UserName` value assigned to a specific server, identified by - # `ServerId`. + # `UserName` value assigned to the specific file transfer + # protocol-enabled server, identified by `ServerId`. # # The response returns the `UserName` value, the `ServerId` value, and # the name of the `SshPublicKeyId`. # # @option params [required, String] :server_id - # A system-assigned unique identifier for an SFTP server. + # A system-assigned unique identifier for a file transfer + # protocol-enabled server. # # @option params [required, String] :ssh_public_key_body # The public key portion of an SSH key pair. # # @option params [required, String] :user_name - # The name of the user account that is assigned to one or more servers. + # The name of the user account that is assigned to one or more file + # transfer protocol-enabled servers. # # @return [Types::ImportSshPublicKeyResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods: # # * {Types::ImportSshPublicKeyResponse#server_id #server_id} => String # * {Types::ImportSshPublicKeyResponse#ssh_public_key_id #ssh_public_key_id} => String @@ -800,28 +839,30 @@ def import_ssh_public_key(params = {}, options = {}) req = build_request(:import_ssh_public_key, params) req.send_request(options) end - # Lists the Secure File Transfer Protocol (SFTP) servers that are - # associated with your AWS account. + # Lists the file transfer protocol-enabled servers that are associated + # with your AWS account. # # @option params [Integer] :max_results - # Specifies the number of servers to return as a response to the - # `ListServers` query. + # Specifies the number of file transfer protocol-enabled servers to + # return as a response to the `ListServers` query. # # @option params [String] :next_token - # When additional results are obtained from the `ListServers` command, a + # When additional results are obtained from the`ListServers` command, a # `NextToken` parameter is returned in the output. You can then pass the # `NextToken` parameter in a subsequent command to continue listing - # additional servers. + # additional file transfer protocol-enabled servers. # # @return [Types::ListServersResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods: # # * {Types::ListServersResponse#next_token #next_token} => String # * {Types::ListServersResponse#servers #servers} => Array&lt;Types::ListedServer&gt; # + # The returned {Seahorse::Client::Response response} is a pageable response and is Enumerable. For details on usage see {Aws::PageableResponse PageableResponse}. + # # @example Request syntax with placeholder values # # resp = client.list_servers({ # max_results: 1, # next_token: "NextToken", @@ -870,10 +911,12 @@ # # * {Types::ListTagsForResourceResponse#arn #arn} => String # * {Types::ListTagsForResourceResponse#next_token #next_token} => String # * {Types::ListTagsForResourceResponse#tags #tags} => Array&lt;Types::Tag&gt; # + # The returned {Seahorse::Client::Response response} is a pageable response and is Enumerable. For details on usage see {Aws::PageableResponse PageableResponse}. + # # @example Request syntax with placeholder values # # resp = client.list_tags_for_resource({ # arn: "Arn", # required # max_results: 1, @@ -895,12 +938,12 @@ def list_tags_for_resource(params = {}, options = {}) req = build_request(:list_tags_for_resource, params) req.send_request(options) end - # Lists the users for the server that you specify by passing the - # `ServerId` parameter. + # Lists the users for a file transfer protocol-enabled server that you + # specify by passing the `ServerId` parameter. # # @option params [Integer] :max_results # Specifies the number of users to return as a response to the # `ListUsers` request. # @@ -909,19 +952,21 @@ # `NextToken` parameter is returned in the output. You can then pass in # a subsequent command to the `NextToken` parameter to continue listing # additional users. # # @option params [required, String] :server_id - # A system-assigned unique identifier for a Secure File Transfer - # Protocol (SFTP) server that has users assigned to it. + # A system-assigned unique identifier for a file transfer + # protocol-enabled server that has users assigned to it. # # @return [Types::ListUsersResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods: # # * {Types::ListUsersResponse#next_token #next_token} => String # * {Types::ListUsersResponse#server_id #server_id} => String # * {Types::ListUsersResponse#users #users} => Array&lt;Types::ListedUser&gt; # + # The returned {Seahorse::Client::Response response} is a pageable response and is Enumerable. For details on usage see {Aws::PageableResponse PageableResponse}. + # # @example Request syntax with placeholder values # # resp = client.list_users({ # max_results: 1, # next_token: "NextToken", @@ -947,23 +992,24 @@ def list_users(params = {}, options = {}) req = build_request(:list_users, params) req.send_request(options) end - # Changes the state of a Secure File Transfer Protocol (SFTP) server - # from `OFFLINE` to `ONLINE`. It has no impact on an SFTP server that is - # already `ONLINE`. An `ONLINE` server can accept and process file - # transfer jobs. + # Changes the state of a file transfer protocol-enabled server from + # `OFFLINE` to `ONLINE`. It has no impact on a server that is already + # `ONLINE`. An `ONLINE` server can accept and process file transfer + # jobs. # # The state of `STARTING` indicates that the server is in an # intermediate state, either not fully able to respond, or not fully # online. The values of `START_FAILED` can indicate an error condition. # # No response is returned from this call. # # @option params [required, String] :server_id - # A system-assigned unique identifier for an SFTP server that you start. + # A system-assigned unique identifier for a file transfer + # protocol-enabled server that you start. # # @return [Struct] Returns an empty {Seahorse::Client::Response response}. # # @example Request syntax with placeholder values # @@ -978,26 +1024,26 @@ def start_server(params = {}, options = {}) req = build_request(:start_server, params) req.send_request(options) end - # Changes the state of an SFTP server from `ONLINE` to `OFFLINE`. An - # `OFFLINE` server cannot accept and process file transfer jobs. - # Information tied to your server such as server and user properties are - # not affected by stopping your server. Stopping a server will not - # reduce or impact your Secure File Transfer Protocol (SFTP) endpoint - # billing. + # Changes the state of a file transfer protocol-enabled server from + # `ONLINE` to `OFFLINE`. An `OFFLINE` server cannot accept and process + # file transfer jobs. Information tied to your server, such as server + # and user properties, are not affected by stopping your server. + # Stopping the server will not reduce or impact your file transfer + # protocol endpoint billing. # # The state of `STOPPING` indicates that the server is in an # intermediate state, either not fully able to respond, or not fully # offline. The values of `STOP_FAILED` can indicate an error condition. # # No response is returned from this call. # # @option params [required, String] :server_id - # A system-assigned unique identifier for an SFTP server that you - # stopped. + # A system-assigned unique identifier for a file transfer + # protocol-enabled server that you stopped. # # @return [Struct] Returns an empty {Seahorse::Client::Response response}. # # @example Request syntax with placeholder values # @@ -1050,27 +1096,39 @@ def tag_resource(params = {}, options = {}) req = build_request(:tag_resource, params) req.send_request(options) end - # If the `IdentityProviderType` of the server is `API_Gateway`, tests - # whether your API Gateway is set up successfully. We highly recommend - # that you call this operation to test your authentication method as - # soon as you create your server. By doing so, you can troubleshoot - # issues with the API Gateway integration to ensure that your users can - # successfully use the service. + # If the `IdentityProviderType` of a file transfer protocol-enabled + # server is `API_Gateway`, tests whether your API Gateway is set up + # successfully. We highly recommend that you call this operation to test + # your authentication method as soon as you create your server. By doing + # so, you can troubleshoot issues with the API Gateway integration to + # ensure that your users can successfully use the service. # # @option params [required, String] :server_id - # A system-assigned identifier for a specific server. That server's - # user authentication method is tested with a user name and password. + # A system-assigned identifier for a specific file transfer + # protocol-enabled server. That server's user authentication method is + # tested with a user name and password. # # @option params [required, String] :user_name - # This request parameter is the name of the user account to be tested. + # The name of the user account to be tested. # # @option params [String] :user_password # The password of the user account to be tested. # + # @option params [String] :server_protocol + # The type of file transfer protocol to be tested. + # + # The available protocols are: + # + # * Secure Shell (SSH) File Transfer Protocol (SFTP) + # + # * File Transfer Protocol Secure (FTPS) + # + # * File Transfer Protocol (FTP) + # # @return [Types::TestIdentityProviderResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods: # # * {Types::TestIdentityProviderResponse#response #response} => String # * {Types::TestIdentityProviderResponse#status_code #status_code} => Integer # * {Types::TestIdentityProviderResponse#message #message} => String @@ -1080,10 +1138,11 @@ # # resp = client.test_identity_provider({ # server_id: "ServerId", # required # user_name: "UserName", # required # user_password: "UserPassword", + # server_protocol: "SFTP", # accepts SFTP, FTP, FTPS # }) # # @example Response structure # # resp.response #=> String @@ -1105,13 +1164,13 @@ # entities. # # No response is returned from this call. # # @option params [required, String] :arn - # This is the value of the resource that will have the tag removed. An - # Amazon Resource Name (ARN) is an identifier for a specific AWS - # resource, such as a server, user, or role. + # The value of the resource that will have the tag removed. An Amazon + # Resource Name (ARN) is an identifier for a specific AWS resource, such + # as a server, user, or role. # # @option params [required, Array<String>] :tag_keys # TagKeys are key-value pairs assigned to ARNs that can be used to group # and search for resources by type. This metadata can be attached to # resources for any purpose. @@ -1132,60 +1191,83 @@ def untag_resource(params = {}, options = {}) req = build_request(:untag_resource, params) req.send_request(options) end - # Updates the server properties after that server has been created. + # Updates the file transfer protocol-enabled server's properties after + # that server has been created. # - # The `UpdateServer` call returns the `ServerId` of the Secure File - # Transfer Protocol (SFTP) server you updated. + # The `UpdateServer` call returns the `ServerId` of the server you + # updated. # + # @option params [String] :certificate + # The Amazon Resource Name (ARN) of the AWS Certificate Manager (ACM) + # certificate. Required when `Protocols` is set to `FTPS`. + # # @option params [Types::EndpointDetails] :endpoint_details # The virtual private cloud (VPC) endpoint settings that are configured - # for your SFTP server. With a VPC endpoint, you can restrict access to - # your SFTP server to resources only within your VPC. To control - # incoming internet traffic, you will need to associate one or more - # Elastic IP addresses with your server's endpoint. + # for your file transfer protocol-enabled server. With a VPC endpoint, + # you can restrict access to your server to resources only within your + # VPC. To control incoming internet traffic, you will need to associate + # one or more Elastic IP addresses with your server's endpoint. # # @option params [String] :endpoint_type - # The type of endpoint that you want your SFTP server to connect to. You - # can choose to connect to the public internet or a virtual private - # cloud (VPC) endpoint. With a VPC endpoint, your SFTP server isn't - # accessible over the public internet. + # The type of endpoint that you want your file transfer protocol-enabled + # server to connect to. You can choose to connect to the public internet + # or a VPC endpoint. With a VPC endpoint, your server isn't accessible + # over the public internet. # # @option params [String] :host_key # The RSA private key as generated by `ssh-keygen -N "" -f # my-new-server-key`. # # If you aren't planning to migrate existing users from an existing - # SFTP server to a new AWS SFTP server, don't update the host key. - # Accidentally changing a server's host key can be disruptive. + # file transfer protocol-enabled server to a new server, don't update + # the host key. Accidentally changing a server's host key can be + # disruptive. # - # For more information, see - # "https://docs.aws.amazon.com/transfer/latest/userguide/configuring-servers.html#change-host-key" - # in the *AWS SFTP User Guide.* + # For more information, see [Changing the Host Key for Your AWS Transfer + # Family Server][1] in the *AWS Transfer Family User Guide*. # + # + # + # [1]: https://docs.aws.amazon.com/transfer/latest/userguide/configuring-servers.html#change-host-key + # # @option params [Types::IdentityProviderDetails] :identity_provider_details - # This response parameter is an array containing all of the information - # required to call a customer's authentication API method. + # An array containing all of the information required to call a + # customer's authentication API method. # # @option params [String] :logging_role - # A value that changes the AWS Identity and Access Management (IAM) role - # that allows Amazon S3 events to be logged in Amazon CloudWatch, - # turning logging on or off. + # Changes the AWS Identity and Access Management (IAM) role that allows + # Amazon S3 events to be logged in Amazon CloudWatch, turning logging on + # or off. # + # @option params [Array<String>] :protocols + # Specifies the file transfer protocol or protocols over which your file + # transfer protocol client can connect to your server's endpoint. The + # available protocols are: + # + # * Secure Shell (SSH) File Transfer Protocol (SFTP): File transfer over + # SSH + # + # * File Transfer Protocol Secure (FTPS): File transfer with TLS + # encryption + # + # * File Transfer Protocol (FTP): Unencrypted file transfer + # # @option params [required, String] :server_id - # A system-assigned unique identifier for an SFTP server instance that - # the user account is assigned to. + # A system-assigned unique identifier for a file transfer + # protocol-enabled server instance that the user account is assigned to. # # @return [Types::UpdateServerResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods: # # * {Types::UpdateServerResponse#server_id #server_id} => String # # @example Request syntax with placeholder values # # resp = client.update_server({ + # certificate: "Certificate", # endpoint_details: { # address_allocation_ids: ["AddressAllocationId"], # subnet_ids: ["SubnetId"], # vpc_endpoint_id: "VpcEndpointId", # vpc_id: "VpcId", @@ -1195,10 +1277,11 @@ # identity_provider_details: { # url: "Url", # invocation_role: "Role", # }, # logging_role: "NullableRole", + # protocols: ["SFTP"], # accepts SFTP, FTP, FTPS # server_id: "ServerId", # required # }) # # @example Response structure # @@ -1219,48 +1302,51 @@ # # The response returns the `ServerId` and the `UserName` for the updated # user. # # @option params [String] :home_directory - # A parameter that specifies the landing directory (folder) for a user - # when they log in to the server using their client. + # Specifies the landing directory (folder) for a user when they log in + # to the file transfer protocol-enabled server using their file transfer + # protocol client. # - # An example is `<your-Amazon-S3-bucket-name>/home/username`. + # An example is `your-Amazon-S3-bucket-name>/home/username`. # # @option params [String] :home_directory_type # The type of landing directory (folder) you want your users' home - # directory to be when they log into the SFTP serve. If you set it to - # `PATH`, the user will see the absolute Amazon S3 bucket paths as is in - # their SFTP clients. If you set it `LOGICAL`, you will need to provide - # mappings in the `HomeDirectoryMappings` for how you want to make S3 - # paths visible to your user. + # directory to be when they log into the file transfer protocol-enabled + # server. If you set it to `PATH`, the user will see the absolute Amazon + # S3 bucket paths as is in their file transfer protocol clients. If you + # set it `LOGICAL`, you will need to provide mappings in the + # `HomeDirectoryMappings` for how you want to make Amazon S3 paths + # visible to your users. # # @option params [Array<Types::HomeDirectoryMapEntry>] :home_directory_mappings - # Logical directory mappings that specify what S3 paths and keys should - # be visible to your user and how you want to make them visible. You - # will need to specify the "`Entry`" and "`Target`" pair, where + # Logical directory mappings that specify what Amazon S3 paths and keys + # should be visible to your user and how you want to make them visible. + # You will need to specify the "`Entry`" and "`Target`" pair, where # `Entry` shows how the path is made visible and `Target` is the actual - # S3 path. If you only specify a target, it will be displayed as is. You - # will need to also make sure that your AWS IAM Role provides access to - # paths in `Target`. The following is an example. + # Amazon S3 path. If you only specify a target, it will be displayed as + # is. You will need to also make sure that your AWS IAM Role provides + # access to paths in `Target`. The following is an example. # # `'[ "/bucket2/documentation", \{ "Entry": "your-personal-report.pdf", # "Target": "/bucket3/customized-reports/$\{transfer:UserName\}.pdf" \} # ]'` # - # In most cases, you can use this value instead of the scope down policy + # In most cases, you can use this value instead of the scope-down policy # to lock your user down to the designated home directory ("chroot"). # To do this, you can set `Entry` to '/' and set `Target` to the # HomeDirectory parameter value. # - # <note markdown="1"> If the target of a logical directory entry does not exist in S3, the - # entry will be ignored. As a workaround, you can use the S3 api to - # create 0 byte objects as place holders for your directory. If using - # the CLI, use the s3api call instead of s3 so you can use the - # put-object operation. For example, you use the following: `aws s3api - # put-object --bucket bucketname --key path/to/folder/`. Make sure that - # the end of the key name ends in a / for it to be considered a folder. + # <note markdown="1"> If the target of a logical directory entry does not exist in Amazon + # S3, the entry will be ignored. As a workaround, you can use the Amazon + # S3 api to create 0 byte objects as place holders for your directory. + # If using the CLI, use the `s3api` call instead of `s3` so you can use + # the put-object operation. For example, you use the following: `aws + # s3api put-object --bucket bucketname --key path/to/folder/`. Make sure + # that the end of the key name ends in a / for it to be considered a + # folder. # # </note> # # @option params [String] :policy # Allows you to supply a scope-down policy for your user so you can use @@ -1268,45 +1354,48 @@ # users. The policy scopes down user access to portions of your Amazon # S3 bucket. Variables you can use inside this policy include # `$\{Transfer:UserName\}`, `$\{Transfer:HomeDirectory\}`, and # `$\{Transfer:HomeBucket\}`. # - # <note markdown="1"> For scope-down policies, AWS Transfer for SFTP stores the policy as a + # <note markdown="1"> For scope-down policies, AWS Transfer Family stores the policy as a # JSON blob, instead of the Amazon Resource Name (ARN) of the policy. # You save the policy as a JSON blob and pass it in the `Policy` # argument. # - # For an example of a scope-down policy, see - # "https://docs.aws.amazon.com/transfer/latest/userguide/users.html#users-policies-scope-down"&gt;Creating - # a Scope-Down Policy. + # For an example of a scope-down policy, see [Creating a Scope-Down + # Policy][1]. # - # For more information, see - # "https://docs.aws.amazon.com/STS/latest/APIReference/API\_AssumeRole.html" - # in the *AWS Security Token Service API Reference*. + # For more information, see [AssumeRole][2] in the *AWS Security Token + # Service API Reference*. # # </note> # + # + # + # [1]: https://docs.aws.amazon.com/transfer/latest/userguide/users.html#users-policies-scope-down + # [2]: https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html + # # @option params [String] :role - # The IAM role that controls your user's access to your Amazon S3 + # The IAM role that controls your users' access to your Amazon S3 # bucket. The policies attached to this role will determine the level of # access you want to provide your users when transferring files into and # out of your Amazon S3 bucket or buckets. The IAM role should also - # contain a trust relationship that allows the Secure File Transfer - # Protocol (SFTP) server to access your resources when servicing your - # SFTP user's transfer requests. + # contain a trust relationship that allows the file transfer + # protocol-enabled server to access your resources when servicing your + # users' transfer requests. # # @option params [required, String] :server_id - # A system-assigned unique identifier for an SFTP server instance that - # the user account is assigned to. + # A system-assigned unique identifier for a file transfer + # protocol-enabled server instance that the user account is assigned to. # # @option params [required, String] :user_name - # A unique string that identifies a user and is associated with a server - # as specified by the `ServerId`. This is the string that will be used - # by your user when they log in to your SFTP server. This user name is a - # minimum of 3 and a maximum of 32 characters long. The following are - # valid characters: a-z, A-Z, 0-9, underscore, and hyphen. The user name - # can't start with a hyphen. + # A unique string that identifies a user and is associated with a file + # transfer protocol-enabled server as specified by the `ServerId`. This + # is the string that will be used by your user when they log in to your + # server. This user name is a minimum of 3 and a maximum of 32 + # characters long. The following are valid characters: a-z, A-Z, 0-9, + # underscore, and hyphen. The user name can't start with a hyphen. # # @return [Types::UpdateUserResponse] Returns a {Seahorse::Client::Response response} object which responds to the following methods: # # * {Types::UpdateUserResponse#server_id #server_id} => String # * {Types::UpdateUserResponse#user_name #user_name} => String @@ -1353,10 +1442,10 @@ operation: config.api.operation(operation_name), client: self, params: params, config: config) context[:gem_name] = 'aws-sdk-transfer' - context[:gem_version] = '1.17.0' + context[:gem_version] = '1.18.0' Seahorse::Client::Request.new(handlers, context) end # @api private # @deprecated