StartDirectoryListing - AWS Transfer Family
請求語法請求參數回應語法回應元素錯誤範例另請參閱

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

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 input 屬性中提供的值，以便能夠列出更多項目（最多允許列表大小為 10,000 個項目）。

請求語法

{
   "ConnectorId": "string",
   "MaxItems": number,
   "OutputDirectoryPath": "string",
   "RemoteDirectoryPath": "string"
}

請求參數

如需所有動作的一般參數資訊，請參閱《Common Parameters》。

請求接受採用 JSON 格式的下列資料。

ConnectorId

連接器的唯一識別碼。

類型：字串

長度約束：固定長度為 19。

模式：c-([0-9a-f]{17})

必要：是

MaxItems

選用參數，您可以在其中指定要擷取的檔案/目錄名稱數目上限。預設值為 1,000。

類型：整數

有效範圍：最小值為 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

返回存儲結果的文件名。這是連接器識別碼和清單識別碼的組合：<connector-id>-<listing-id>.json。

類型：字串

長度限制：長度下限為 26。最大長度為 537。

模式：c-([0-9a-f]{17})-[0-9a-zA-Z./-]+.json

錯誤

如需所有動作常見錯誤的資訊，請參閱常見錯誤。

InternalServiceError

當在 AWS Transfer Family 服務中發生錯誤時，拋出此異常。

HTTP 狀態碼：500

InvalidRequestException

當客戶端提交格式錯誤的請求時，拋出此異常。

HTTP 狀態碼：400

ResourceNotFoundException

當 AWS Transfer Family 服務找不到資源時，會擲回此例外狀況。

HTTP 狀態碼：400

ServiceUnavailableException

申請失敗，因為 AWS Transfer 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
}

另請參閱

如需在其中一個特定語言 AWS SDK 中使用此 API 的詳細資訊，請參閱下列內容：