start_directory_listing ¶

def start_directory_listing(
    self,
    connector_id: "capo_transfer.types.connector_id.ConnectorId",
    remote_directory_path: "capo_transfer.types.file_path.FilePath",
    output_directory_path: "capo_transfer.types.file_path.FilePath",
    *,
    config_overrides: Optional[TransferClientConfig] = None,
    max_items: Optional["capo_transfer.types.max_items.MaxItems"] = None,
) -> "capo_transfer.types.start_directory_listing_response.StartDirectoryListingResponse":
    """<p>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 <code>MaxItems</code> 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.</p> <p>After you receive the listing file, you can provide the files that you want to transfer to the <code>RetrieveFilePaths</code> parameter of the <code>StartFileTransfer</code> API call.</p> <p>The naming convention for the output file is <code> <i>connector-ID</i>-<i>listing-ID</i>.json</code>. The output file contains the following information:</p> <ul> <li> <p> <code>filePath</code>: the complete path of a remote file, relative to the directory of the listing request for your SFTP connector on the remote server.</p> </li> <li> <p> <code>modifiedTimestamp</code>: 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.</p> </li> <li> <p> <code>size</code>: 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.</p> </li> <li> <p> <code>path</code>: the complete path of a remote directory, relative to the directory of the listing request for your SFTP connector on the remote server.</p> </li> <li> <p> <code>truncated</code>: a flag indicating whether the list output contains all of the items contained in the remote directory or not. If your <code>Truncated</code> output value is true, you can increase the value provided in the optional <code>max-items</code> input attribute to be able to list more items (up to the maximum allowed list size of 200,000 items).</p> </li> </ul>

    Args:
        connector_id: <p>The unique identifier for the connector.</p>
        remote_directory_path: <p>Specifies the directory on the remote SFTP server for which you want to list its contents.</p>
        max_items: <p>An optional parameter where you can specify the maximum number of file/directory names to retrieve. The default value is 1,000.</p>
        output_directory_path: <p>Specifies the path (bucket and prefix) in Amazon S3 storage to store the results of the directory listing.</p>

    Raises:
        capo_transfer.errors.internal_service_error.InternalServiceError: <p>This exception is thrown when an error occurs in the Transfer Family service.</p>
        capo_transfer.errors.invalid_request_exception.InvalidRequestException: <p>This exception is thrown when the client submits a malformed request.</p>
        capo_transfer.errors.resource_not_found_exception.ResourceNotFoundException: <p>This exception is thrown when a resource is not found by the Amazon Web ServicesTransfer Family service.</p>
        capo_transfer.errors.service_unavailable_exception.ServiceUnavailableException: <p>The request has failed because the Amazon Web ServicesTransfer Family service is not available.</p>
        capo_transfer.errors.throttling_exception.ThrottlingException: <p>The request was denied due to request throttling.</p>
        capo_transfer.errors.UnknownServiceError: The service returned an error code this client does not model.
    """

    def _handler(
        req: "OperationRequest[capo_transfer.types.start_directory_listing_request.StartDirectoryListingRequest]",
    ) -> OperationResponse[
        "capo_transfer.types.start_directory_listing_response.StartDirectoryListingResponse"
    ]:
        import capo_transfer._operations.transfer_service.start_directory_listing

        output, http_response = (
            capo_transfer._operations.transfer_service.start_directory_listing.start_directory_listing(
                req.options, req.input
            )
        )
        return OperationResponse(output=output, response=http_response)

    interceptors_, options_ = self.operation_options(
        config_overrides, OperationLogging("StartDirectoryListing")
    )
    input_: capo_transfer.types.start_directory_listing_request.StartDirectoryListingRequest = {
        "connector_id": connector_id,
        "remote_directory_path": remote_directory_path,
        "output_directory_path": output_directory_path,
    }
    if max_items is not None:
        input_["max_items"] = max_items

    response = execute_pipeline(
        OperationRequest(input=input_, options=options_),
        handler=_handler,
        interceptors=list(interceptors_),
    )
    response.response.close()
    return response.output