StartDirectoryListing
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 yourTruncated
output value is true, you can increase the value provided in the optionalmax-items
input attribute to be able to list more items (up to the maximum allowed list size of 10,000 items).
Request Syntax
{
"ConnectorId": "string
",
"MaxItems": number
,
"OutputDirectoryPath": "string
",
"RemoteDirectoryPath": "string
"
}
Request Parameters
For information about the parameters that are common to all actions, see Common Parameters.
The request accepts the following data in JSON format.
- ConnectorId
-
The unique identifier for the connector.
Type: String
Length Constraints: Fixed length of 19.
Pattern:
c-([0-9a-f]{17})
Required: Yes
- MaxItems
-
An optional parameter where you can specify the maximum number of file/directory names to retrieve. The default value is 1,000.
Type: Integer
Valid Range: Minimum value of 1. Maximum value of 10000.
Required: No
- OutputDirectoryPath
-
Specifies the path (bucket and prefix) in Amazon S3 storage to store the results of the directory listing.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 1024.
Pattern:
(.)+
Required: Yes
- RemoteDirectoryPath
-
Specifies the directory on the remote SFTP server for which you want to list its contents.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 1024.
Pattern:
(.)+
Required: Yes
Response Syntax
{
"ListingId": "string",
"OutputFileName": "string"
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
- ListingId
-
Returns a unique identifier for the directory listing call.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 512.
Pattern:
[0-9a-zA-Z./-]+
- OutputFileName
-
Returns the file name where the results are stored. This is a combination of the connector ID and the listing ID:
<connector-id>-<listing-id>.json
.Type: String
Length Constraints: Minimum length of 26. Maximum length of 537.
Pattern:
c-([0-9a-f]{17})-[0-9a-zA-Z./-]+.json
Errors
For information about the errors that are common to all actions, see Common Errors.
- InternalServiceError
-
This exception is thrown when an error occurs in the Amazon Transfer Family service.
HTTP Status Code: 500
- InvalidRequestException
-
This exception is thrown when the client submits a malformed request.
HTTP Status Code: 400
- ResourceNotFoundException
-
This exception is thrown when a resource is not found by the AmazonTransfer Family service.
HTTP Status Code: 400
- ServiceUnavailableException
-
The request has failed because the AmazonTransfer Family service is not available.
HTTP Status Code: 500
- ThrottlingException
-
The request was denied due to request throttling.
HTTP Status Code: 400
Examples
Example
The following example lists the contents of the home
folder on the remote
SFTP server, which is identified by the specified connector. The results are placed into
the Amazon S3 location /amzn-s3-demo-bucket/connector-files
, and into
a file named
c-AAAA1111BBBB2222C-6666abcd-11aa-22bb-cc33-0000aaaa3333.json
.
Sample Request
{
"ConnectorId": "c-AAAA1111BBBB2222C",
"MaxItems": "10",
"OutputDirectoryPath": "/amzn-s3-demo-bucket/connector-files",
"RemoteDirectoryPath": "/home"
}
Sample Response
{
"ListingId": "6666abcd-11aa-22bb-cc33-0000aaaa3333",
"OutputFileName": "c-AAAA1111BBBB2222C-6666abcd-11aa-22bb-cc33-0000aaaa3333.json"
}
// under bucket "amzn-s3-demo-bucket" connector-files/c-AAAA1111BBBB2222C-6666abcd-11aa-22bb-cc33-0000aaaa3333.json { "files": [ { "filePath": "/home/what.txt", "modifiedTimestamp": "2024-01-30T20:34:54Z", "size" : 2323 }, { "filePath": "/home/how.pgp", "modifiedTimestamp": "2024-01-30T20:34:54Z", "size" : 51238 } ], "paths": [ { "path": "/home/magic" }, { "path": "/home/aws" }, ], "truncated": false }
See Also
For more information about using this API in one of the language-specific Amazon SDKs, see the following: