# 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 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 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](CommonParameters.md).

The request accepts the following data in JSON format.

 ** [ConnectorId](#API_StartDirectoryListing_RequestSyntax) **   <a name="TransferFamily-StartDirectoryListing-request-ConnectorId"></a>
The unique identifier for the connector.  
Type: String  
Length Constraints: Fixed length of 19.  
Pattern: `c-([0-9a-f]{17})`   
Required: Yes

 ** [MaxItems](#API_StartDirectoryListing_RequestSyntax) **   <a name="TransferFamily-StartDirectoryListing-request-MaxItems"></a>
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](#API_StartDirectoryListing_RequestSyntax) **   <a name="TransferFamily-StartDirectoryListing-request-OutputDirectoryPath"></a>
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](#API_StartDirectoryListing_RequestSyntax) **   <a name="TransferFamily-StartDirectoryListing-request-RemoteDirectoryPath"></a>
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](#API_StartDirectoryListing_ResponseSyntax) **   <a name="TransferFamily-StartDirectoryListing-response-ListingId"></a>
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](#API_StartDirectoryListing_ResponseSyntax) **   <a name="TransferFamily-StartDirectoryListing-response-OutputFileName"></a>
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 Error Types](CommonErrors.md).

 ** 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:
+  [Amazon Command Line Interface V2](https://docs.amazonaws.cn/goto/cli2/transfer-2018-11-05/StartDirectoryListing) 
+  [Amazon SDK for .NET V4](https://docs.amazonaws.cn/goto/DotNetSDKV4/transfer-2018-11-05/StartDirectoryListing) 
+  [Amazon SDK for C\$1\$1](https://docs.amazonaws.cn/goto/SdkForCpp/transfer-2018-11-05/StartDirectoryListing) 
+  [Amazon SDK for Go v2](https://docs.amazonaws.cn/goto/SdkForGoV2/transfer-2018-11-05/StartDirectoryListing) 
+  [Amazon SDK for Java V2](https://docs.amazonaws.cn/goto/SdkForJavaV2/transfer-2018-11-05/StartDirectoryListing) 
+  [Amazon SDK for JavaScript V3](https://docs.amazonaws.cn/goto/SdkForJavaScriptV3/transfer-2018-11-05/StartDirectoryListing) 
+  [Amazon SDK for Kotlin](https://docs.amazonaws.cn/goto/SdkForKotlin/transfer-2018-11-05/StartDirectoryListing) 
+  [Amazon SDK for PHP V3](https://docs.amazonaws.cn/goto/SdkForPHPV3/transfer-2018-11-05/StartDirectoryListing) 
+  [Amazon SDK for Python](https://docs.amazonaws.cn/goto/boto3/transfer-2018-11-05/StartDirectoryListing) 
+  [Amazon SDK for Ruby V3](https://docs.amazonaws.cn/goto/SdkForRubyV3/transfer-2018-11-05/StartDirectoryListing)