Skip to main content

connectors

Creates, updates, deletes, gets or lists a connectors resource.

Overview​

Nameconnectors
TypeResource
Idaws.transfer.connectors

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
access_rolestringConnectors are used to send files using either the AS2 or SFTP protocol. For the access role, provide the Amazon Resource Name (ARN) of the Identity and Access Management role to use. For AS2 connectors With AS2, you can send files by calling StartFileTransfer and specifying the file paths in the request parameter, SendFilePaths. We use the file’s parent directory (for example, for --send-file-paths /bucket/dir/file.txt, parent directory is /bucket/dir/) to temporarily store a processed AS2 message file, store the MDN when we receive them from the partner, and write a final JSON file containing relevant metadata of the transmission. So, the AccessRole needs to provide read and write access to the parent directory of the file location used in the StartFileTransfer request. Additionally, you need to provide read and write access to the parent directory of the files that you intend to send with StartFileTransfer. If you are using Basic authentication for your AS2 connector, the access role requires the secretsmanager:GetSecretValue permission for the secret. If the secret is encrypted using a customer-managed key instead of the Amazon Web Services managed key in Secrets Manager, then the role also needs the kms:Decrypt permission for that key. For SFTP connectors Make sure that the access role provides read and write access to the parent directory of the file location that's used in the StartFileTransfer request. Additionally, make sure that the role provides secretsmanager:GetSecretValue permission to Secrets Manager. (pattern: <code>arn:.*role/\S+</code>)
arnstringThe unique Amazon Resource Name (ARN) for the connector. (pattern: <code>arn:\S+</code>)
as_2_configobjectA structure that contains the parameters for an AS2 connector object.
connector_idstringThe unique identifier for the connector. (pattern: <code>c-([0-9a-f]{17})</code>)
egress_configobjectCurrent egress configuration of the connector, showing how traffic is routed to the SFTP server. Contains VPC Lattice settings when using VPC_LATTICE egress type. When using the VPC_LATTICE egress type, Transfer Family uses a managed Service Network to simplify the resource sharing process.
egress_typestringType of egress configuration for the connector. SERVICE_MANAGED uses Transfer Family managed NAT gateways, while VPC_LATTICE routes traffic through customer VPCs using VPC Lattice. (SERVICE_MANAGED, VPC_LATTICE)
error_messagestringError message providing details when the connector is in ERRORED status. Contains information to help troubleshoot connector creation or operation failures.
ip_address_typestringIP address type for the connector's network connections. When set to IPV4, the connector uses IPv4 addresses only. When set to DUALSTACK, the connector supports both IPv4 and IPv6 addresses, with IPv6 preferred when available. (IPV4, DUALSTACK)
logging_rolestringThe Amazon Resource Name (ARN) of the Identity and Access Management (IAM) role that allows a connector to turn on CloudWatch logging for Amazon S3 events. When set, you can view connector activity in your CloudWatch logs. (pattern: <code>arn:.*role/\S+</code>)
security_policy_namestringThe text name of the security policy for the specified connector. (pattern: <code>TransferSFTPConnectorSecurityPolicy-[A-Za-z0-9-]+</code>)
service_managed_egress_ip_addressesarrayThe list of egress IP addresses of this connector. These IP addresses are assigned automatically when you create the connector.
sftp_configobjectA structure that contains the parameters for an SFTP connector object.
statusstringCurrent status of the connector. PENDING indicates creation/update in progress, ACTIVE means ready for operations, and ERRORED indicates a failure requiring attention. (ACTIVE, ERRORED, PENDING)
tagsarrayKey-value pairs that can be used to group and search for connectors.
urlstringThe URL of the partner's AS2 or SFTP endpoint. When creating AS2 connectors or service-managed SFTP connectors (connectors without egress configuration), you must provide a URL to specify the remote server endpoint. For VPC Lattice type connectors, the URL must be null.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
describe_connectorselectregionDescribes the connector that's identified by the ConnectorId.
list_connectorsselectregionLists the connectors for the specified Region.
create_connectorinsertregion, AccessRoleCreates the connector, which captures the parameters for a connection for the AS2 or SFTP protocol. For AS2, the connector is required for sending files to an externally hosted AS2 server. For SFTP, the connector is required when sending files to an SFTP server or receiving files from an SFTP server. For more details about connectors, see Configure AS2 connectors and Create SFTP connectors. You must specify exactly one configuration object: either for AS2 (As2Config) or SFTP (SftpConfig).
update_connectorupdateregion, ConnectorIdUpdates some of the parameters for an existing connector. Provide the ConnectorId for the connector that you want to update, along with the new values for the parameters to update.
delete_connectordeleteregionDeletes the connector that's specified in the provided ConnectorId.
start_directory_listingexecregion, ConnectorId, RemoteDirectoryPath, OutputDirectoryPathRetrieves a list of the contents of a directory from a remote SFTP server. You specify the connector ID, the output path, and the remote directory path. You can also specify the optional MaxItems value to control the maximum number of items that are listed from the remote directory. This API returns a list of all files and directories in the remote directory (up to the maximum value), but does not return files or folders in sub-directories. That is, it only returns a list of files and directories one-level deep. After you receive the listing file, you can provide the files that you want to transfer to the RetrieveFilePaths parameter of the StartFileTransfer API call. The naming convention for the output file is connector-ID-listing-ID.json. The output file contains the following information: filePath: the complete path of a remote file, relative to the directory of the listing request for your SFTP connector on the remote server. modifiedTimestamp: the last time the file was modified, in UTC time format. This field is optional. If the remote file attributes don't contain a timestamp, it is omitted from the file listing. size: the size of the file, in bytes. This field is optional. If the remote file attributes don't contain a file size, it is omitted from the file listing. path: the complete path of a remote directory, relative to the directory of the listing request for your SFTP connector on the remote server. truncated: a flag indicating whether the list output contains all of the items contained in the remote directory or not. If your Truncated output value is true, you can increase the value provided in the optional max-items input attribute to be able to list more items (up to the maximum allowed list size of 200,000 items).
start_file_transferexecregion, ConnectorIdBegins a file transfer between local Amazon Web Services storage and a remote AS2 or SFTP server. For an AS2 connector, you specify the ConnectorId and one or more SendFilePaths to identify the files you want to transfer. For an SFTP connector, the file transfer can be either outbound or inbound. In both cases, you specify the ConnectorId. Depending on the direction of the transfer, you also specify the following items: If you are transferring file from a partner's SFTP server to Amazon Web Services storage, you specify one or more RetrieveFilePaths to identify the files you want to transfer, and a LocalDirectoryPath to specify the destination folder. If you are transferring file to a partner's SFTP server from Amazon Web Services storage, you specify one or more SendFilePaths to identify the files you want to transfer, and a RemoteDirectoryPath to specify the destination folder.
start_remote_deleteexecregion, ConnectorId, DeletePathDeletes a file or directory on the remote SFTP server.
start_remote_moveexecregion, ConnectorId, SourcePath, TargetPathMoves or renames a file or directory on the remote SFTP server.
test_connectionexecregion, ConnectorIdTests whether your SFTP connector is set up successfully. We highly recommend that you call this operation to test your ability to transfer files between local Amazon Web Services storage and a trading partner's SFTP server.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
regionstringAWS region (default: us-east-1)

SELECT examples​

Describes the connector that's identified by the ConnectorId.

SELECT
access_role,
arn,
as_2_config,
connector_id,
egress_config,
egress_type,
error_message,
ip_address_type,
logging_role,
security_policy_name,
service_managed_egress_ip_addresses,
sftp_config,
status,
tags,
url
FROM aws.transfer.connectors
WHERE region = '{{ region }}' -- required
;

INSERT examples​

Creates the connector, which captures the parameters for a connection for the AS2 or SFTP protocol. For AS2, the connector is required for sending files to an externally hosted AS2 server. For SFTP, the connector is required when sending files to an SFTP server or receiving files from an SFTP server. For more details about connectors, see Configure AS2 connectors and Create SFTP connectors. You must specify exactly one configuration object: either for AS2 (As2Config) or SFTP (SftpConfig).

INSERT INTO aws.transfer.connectors (
Url,
As2Config,
AccessRole,
LoggingRole,
Tags,
SftpConfig,
SecurityPolicyName,
EgressConfig,
IpAddressType,
region
)
SELECT 
'{{ Url }}',
'{{ As2Config }}',
'{{ AccessRole }}' /* required */,
'{{ LoggingRole }}',
'{{ Tags }}',
'{{ SftpConfig }}',
'{{ SecurityPolicyName }}',
'{{ EgressConfig }}',
'{{ IpAddressType }}',
'{{ region }}'
RETURNING
connector_id
;

UPDATE examples​

Updates some of the parameters for an existing connector. Provide the ConnectorId for the connector that you want to update, along with the new values for the parameters to update.

UPDATE aws.transfer.connectors
SET 
ConnectorId = '{{ ConnectorId }}',
Url = '{{ Url }}',
As2Config = '{{ As2Config }}',
AccessRole = '{{ AccessRole }}',
LoggingRole = '{{ LoggingRole }}',
SftpConfig = '{{ SftpConfig }}',
SecurityPolicyName = '{{ SecurityPolicyName }}',
EgressConfig = '{{ EgressConfig }}',
IpAddressType = '{{ IpAddressType }}'
WHERE 
region = '{{ region }}' --required
AND ConnectorId = '{{ ConnectorId }}' --required
RETURNING
connector_id;

DELETE examples​

Deletes the connector that's specified in the provided ConnectorId.

DELETE FROM aws.transfer.connectors
WHERE region = '{{ region }}' --required
;

Lifecycle Methods​

Retrieves a list of the contents of a directory from a remote SFTP server. You specify the connector ID, the output path, and the remote directory path. You can also specify the optional MaxItems value to control the maximum number of items that are listed from the remote directory. This API returns a list of all files and directories in the remote directory (up to the maximum value), but does not return files or folders in sub-directories. That is, it only returns a list of files and directories one-level deep. After you receive the listing file, you can provide the files that you want to transfer to the RetrieveFilePaths parameter of the StartFileTransfer API call. The naming convention for the output file is connector-ID-listing-ID.json. The output file contains the following information: filePath: the complete path of a remote file, relative to the directory of the listing request for your SFTP connector on the remote server. modifiedTimestamp: the last time the file was modified, in UTC time format. This field is optional. If the remote file attributes don't contain a timestamp, it is omitted from the file listing. size: the size of the file, in bytes. This field is optional. If the remote file attributes don't contain a file size, it is omitted from the file listing. path: the complete path of a remote directory, relative to the directory of the listing request for your SFTP connector on the remote server. truncated: a flag indicating whether the list output contains all of the items contained in the remote directory or not. If your Truncated output value is true, you can increase the value provided in the optional max-items input attribute to be able to list more items (up to the maximum allowed list size of 200,000 items).

EXEC aws.transfer.connectors.start_directory_listing 
@region='{{ region }}' --required 
@@json=
'{
"ConnectorId": "{{ ConnectorId }}", 
"RemoteDirectoryPath": "{{ RemoteDirectoryPath }}", 
"MaxItems": {{ MaxItems }}, 
"OutputDirectoryPath": "{{ OutputDirectoryPath }}"
}'
;
Last updated on