本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
StartDirectoryListing
从远程 SFTP 服务器检索目录内容列表。您可以指定连接器 ID、输出路径和远程目录路径。您也可以指定可选MaxItems值来控制远程目录中列出的最大项目数。此 API 返回远程目录中所有文件和目录的列表（不超过最大值），但不返回子目录中的文件或文件夹。也就是说，它只返回深度为一层的文件和目录的列表。
收到列表文件后，您可以将要传输的文件提供给 StartFileTransfer API 调用的RetrieveFilePaths参数。
输出文件的命名约定为
connector-ID-listing-ID.json。输出文件包含以下信息：
-
filePath：远程文件的完整路径，相对于远程服务器上 SFTP 连接器的列出请求目录。 -
modifiedTimestamp：上次修改文件的时间，采用 UTC 时间格式。该字段是可选的。如果远程文件属性不包含时间戳，则文件列表中将省略该时间戳。 -
size: 文件的大小，以字节为单位。该字段是可选的。如果远程文件属性不包含文件大小，则会将其从文件列表中省略。 -
path：远程目录的完整路径，相对于远程服务器上的 SFTP 连接器的列出请求目录。 -
truncated: 一个标志，指示列表输出是否包含远程目录中包含的所有项目。如果您的Truncated输出值为 true，则可以增加可选max-items输入属性中提供的值，以便能够列出更多项目（允许的最大列表大小为 10,000 个）。
请求语法
{
"ConnectorId": "string",
"MaxItems": number,
"OutputDirectoryPath": "string",
"RemoteDirectoryPath": "string"
}请求参数
有关所有操作的通用参数的信息，请参阅常用参数。
请求接受采用 JSON 格式的以下数据。
- ConnectorId
-
连接器的唯一标识符。
类型：字符串
长度限制：固定长度为 19。
模式：
c-([0-9a-f]{17})必需：是
- MaxItems
-
一个可选参数，您可以在其中指定要检索的最大文件/目录名数。默认值是 1000。
类型：整数
有效范围：最小值为 1。最大值为 10000。
必需：否
- OutputDirectoryPath
-
指定 Amazon S3 存储中用于存储目录列表结果的路径（存储桶和前缀）。
类型：字符串
长度限制：长度下限为 1。长度上限为 1024。
模式：
(.)+必需：是
- RemoteDirectoryPath
-
指定远程 SFTP 服务器上要列出其内容的目录。
类型：字符串
长度限制：长度下限为 1。长度上限为 1024。
模式：
(.)+必需：是
响应语法
{
"ListingId": "string",
"OutputFileName": "string"
}响应元素
如果此操作成功，则该服务将会发送回 HTTP 200 响应。
服务以 JSON 格式返回以下数据。
- ListingId
-
返回目录列表调用的唯一标识符。
类型：字符串
长度限制：长度下限为 1。最大长度为 512。
模式：
[0-9a-zA-Z./-]+ - OutputFileName
-
返回存储结果的文件名。这是连接器 ID 和列表 ID 的组合：
<connector-id>-<listing-id>.json。类型：字符串
长度限制：最小长度为 26。最大长度为 537。
模式：
c-([0-9a-f]{17})-[0-9a-zA-Z./-]+.json
错误
有关所有操作的常见错误的信息，请参阅常见错误。
- InternalServiceError
-
当 Amazon Transfer Family 服务中发生错误时，会引发此异常。
HTTP 状态代码：500
- InvalidRequestException
-
当客户端提交格式错误的请求时，会引发此异常。
HTTP 状态代码：400
- ResourceNotFoundException
-
当 Transfer Family 服务找不到资源时，就会 Amazon引发此异常。
HTTP 状态代码：400
- ServiceUnavailableException
-
请求失败，因为 Trans Amazon fer Family 服务不可用。
HTTP 状态代码：500
- ThrottlingException
-
由于请求限制而导致请求被拒绝。
HTTP 状态代码：400
示例
示例
以下示例列出了远程 SFTP 服务器上由指定连接器标识的home文件夹的内容。结果将放入 Amazon S3 位置/DOC-EXAMPLE-BUCKET/connector-files和名为的文件中c-AAAA1111BBBB2222C-6666abcd-11aa-22bb-cc33-0000aaaa3333.json。
示例请求
{
"ConnectorId": "c-AAAA1111BBBB2222C",
"MaxItems": "10",
"OutputDirectoryPath": "/DOC-EXAMPLE-BUCKET/connector-files",
"RemoteDirectoryPath": "/home"
}示例响应
{
"ListingId": "6666abcd-11aa-22bb-cc33-0000aaaa3333",
"OutputFileName": "c-AAAA1111BBBB2222C-6666abcd-11aa-22bb-cc33-0000aaaa3333.json"
}// under bucket "DOC-EXAMPLE-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 }
另请参阅
有关在特定语言的 Amazon SDK 中使用此 API 的更多信息，请参阅以下内容：