Conceitos básicos Carregar um arquivo Baixar um arquivo Copiar um objeto Fazer upload de um diretório Baixar para um diretório Ver exemplos completos

Transfira arquivos e diretórios com o Gerenciador de transferências do Amazon S3

O gerenciador de transferências do S3 é um utilitário de transferência de arquivos de alto nível e de código aberto para o AWS SDK for Java 2.x. Use-o para transferir arquivos e diretórios de e para o Amazon Simple Storage Service (Amazon S3).

Quando construído com base no cliente S3 AWS baseado em CRT ou no cliente assíncrono S3 padrão baseado em Java com várias partes habilitadas, o S3 Transfer Manager pode aproveitar as melhorias de desempenho, como a API de upload de várias partes e as buscas por intervalo de bytes.

Com o gerenciador de transferências do S3, você também pode monitorar o progresso de uma transferência em tempo real e pausar a transferência para execução posterior.

Conceitos básicos

Adicionar dependências ao seu arquivo de compilação

Para usar o S3 Transfer Manager com desempenho aprimorado em várias partes, configure seu arquivo de compilação com as dependências necessárias.

Criar uma instância do gerenciador de transferências do S3

Para habilitar a transferência paralela, você deve transmitir um cliente S3 AWS baseado em CRT OU um cliente assíncrono S3 baseado em Java com multipartes habilitado. Os exemplos a seguir mostram como configurar um S3 Transfer Manager com configurações personalizadas.

Carregar um arquivo em um bucket do S3

O exemplo a seguir mostra um exemplo de upload de arquivo junto com o uso opcional de um LoggingTransferListener, que registra o progresso do upload.

Para carregar um arquivo para o Amazon S3 usando o gerenciador de transferências do S3, passe um objeto UploadFileRequest para o método uploadFile do S3TransferManager.

O FileUploadobjeto retornado do uploadFile método representa o processo de upload. Depois que a solicitação for concluída, o CompletedFileUploadobjeto conterá informações sobre o upload.


    public void trackUploadFile(S3TransferManager transferManager, String bucketName,
                             String key, URI filePathURI) {
        UploadFileRequest uploadFileRequest = UploadFileRequest.builder()
                .putObjectRequest(b -> b.bucket(bucketName).key(key))
                .addTransferListener(LoggingTransferListener.create())  // Add listener.
                .source(Paths.get(filePathURI))
                .build();

        FileUpload fileUpload = transferManager.uploadFile(uploadFileRequest);

        fileUpload.completionFuture().join();
        /*
            The SDK provides a LoggingTransferListener implementation of the TransferListener interface.
            You can also implement the interface to provide your own logic.

            Configure log4J2 with settings such as the following.
                <Configuration status="WARN">
                    <Appenders>
                        <Console name="AlignedConsoleAppender" target="SYSTEM_OUT">
                            <PatternLayout pattern="%m%n"/>
                        </Console>
                    </Appenders>

                    <Loggers>
                        <logger name="software.amazon.awssdk.transfer.s3.progress.LoggingTransferListener" level="INFO" additivity="false">
                            <AppenderRef ref="AlignedConsoleAppender"/>
                        </logger>
                    </Loggers>
                </Configuration>

            Log4J2 logs the progress. The following is example output for a 21.3 MB file upload.
                Transfer initiated...
                |                    | 0.0%
                |====                | 21.1%
                |============        | 60.5%
                |====================| 100.0%
                Transfer complete!
        */
    }


import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.transfer.s3.S3TransferManager;
import software.amazon.awssdk.transfer.s3.model.CompletedFileUpload;
import software.amazon.awssdk.transfer.s3.model.FileUpload;
import software.amazon.awssdk.transfer.s3.model.UploadFileRequest;
import software.amazon.awssdk.transfer.s3.progress.LoggingTransferListener;
import java.net.URI;
import java.net.URISyntaxException;
import java.net.URL;
import java.nio.file.Paths;
import java.util.UUID;

Baixar um arquivo de um bucket do S3

O exemplo a seguir mostra um exemplo de download junto com o uso opcional de um LoggingTransferListener, que registra o progresso do download.

Para baixar um objeto de um bucket do S3 usando o S3 Transfer Manager, crie um DownloadFileRequestobjeto e passe-o para o método downloadFile.

O FileDownloadobjeto retornado pelo downloadFile método S3TransferManager's representa a transferência do arquivo. Após a conclusão do download, ele CompletedFileDownloadcontém acesso às informações sobre o download.


    public void trackDownloadFile(S3TransferManager transferManager, String bucketName,
                             String key, String downloadedFileWithPath) {
        DownloadFileRequest downloadFileRequest = DownloadFileRequest.builder()
                .getObjectRequest(b -> b.bucket(bucketName).key(key))
                .addTransferListener(LoggingTransferListener.create())  // Add listener.
                .destination(Paths.get(downloadedFileWithPath))
                .build();

        FileDownload downloadFile = transferManager.downloadFile(downloadFileRequest);

        CompletedFileDownload downloadResult = downloadFile.completionFuture().join();
        /*
            The SDK provides a LoggingTransferListener implementation of the TransferListener interface.
            You can also implement the interface to provide your own logic.

            Configure log4J2 with settings such as the following.
                <Configuration status="WARN">
                    <Appenders>
                        <Console name="AlignedConsoleAppender" target="SYSTEM_OUT">
                            <PatternLayout pattern="%m%n"/>
                        </Console>
                    </Appenders>

                    <Loggers>
                        <logger name="software.amazon.awssdk.transfer.s3.progress.LoggingTransferListener" level="INFO" additivity="false">
                            <AppenderRef ref="AlignedConsoleAppender"/>
                        </logger>
                    </Loggers>
                </Configuration>

            Log4J2 logs the progress. The following is example output for a 21.3 MB file download.
                Transfer initiated...
                |=======             | 39.4%
                |===============     | 78.8%
                |====================| 100.0%
                Transfer complete!
        */
    }



import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.core.sync.RequestBody;
import software.amazon.awssdk.transfer.s3.S3TransferManager;
import software.amazon.awssdk.transfer.s3.model.CompletedFileDownload;
import software.amazon.awssdk.transfer.s3.model.DownloadFileRequest;
import software.amazon.awssdk.transfer.s3.model.FileDownload;
import software.amazon.awssdk.transfer.s3.progress.LoggingTransferListener;

import java.io.IOException;
import java.net.URISyntaxException;
import java.net.URL;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.UUID;

Adicionar um objeto a um bucket do Amazon S3

O exemplo a seguir mostra como copiar um objeto com o gerenciador de transferência do S3.

Para começar a cópia de um objeto de um bucket do S3 para outro bucket, crie uma CopyObjectRequestinstância básica.

Em seguida, envolva o básico CopyObjectRequest em um CopyRequestque possa ser usado pelo S3 Transfer Manager.

O objeto Copy retornado pelo método copy do S3TransferManager representa o processo de cópia. Depois que o processo de cópia for concluído, o CompletedCopyobjeto conterá detalhes sobre a resposta.


    public String copyObject(S3TransferManager transferManager, String bucketName,
            String key, String destinationBucket, String destinationKey) {
        CopyObjectRequest copyObjectRequest = CopyObjectRequest.builder()
                .sourceBucket(bucketName)
                .sourceKey(key)
                .destinationBucket(destinationBucket)
                .destinationKey(destinationKey)
                .build();

        CopyRequest copyRequest = CopyRequest.builder()
                .copyObjectRequest(copyObjectRequest)
                .build();

        Copy copy = transferManager.copy(copyRequest);

        CompletedCopy completedCopy = copy.completionFuture().join();
        return completedCopy.response().copyObjectResult().eTag();
    }

nota

Para realizar uma cópia entre regiões com o S3 Transfer Manager, habilite crossRegionAccessEnabled no construtor de clientes S3 AWS baseado em CRT, conforme mostrado no trecho a seguir.


S3AsyncClient s3AsyncClient = S3AsyncClient.crtBuilder()
                .crossRegionAccessEnabled(true)
                .build();

S3TransferManager transferManager = S3TransferManager.builder()
                .s3Client(s3AsyncClient)
                .build();


import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.core.sync.RequestBody;
import software.amazon.awssdk.services.s3.model.CopyObjectRequest;
import software.amazon.awssdk.transfer.s3.S3TransferManager;
import software.amazon.awssdk.transfer.s3.model.CompletedCopy;
import software.amazon.awssdk.transfer.s3.model.Copy;
import software.amazon.awssdk.transfer.s3.model.CopyRequest;

import java.util.UUID;

Carregamento de um diretório local para um bucket do S3

O exemplo a seguir demonstra como fazer upload de um diretório local para o S3.

Comece chamando o método uploadDirectory da S3TransferManager instância, passando um. UploadDirectoryRequest

O DirectoryUploadobjeto representa o processo de upload, que gera um CompletedDirectoryUploadquando a solicitação é concluída. O objeto CompleteDirectoryUpload contém informações sobre os resultados da transferência, incluindo quais arquivos falharam na transferência.


    public Integer uploadDirectory(S3TransferManager transferManager,
            URI sourceDirectory, String bucketName) {
        DirectoryUpload directoryUpload = transferManager.uploadDirectory(UploadDirectoryRequest.builder()
                .source(Paths.get(sourceDirectory))
                .bucket(bucketName)
                .build());

        CompletedDirectoryUpload completedDirectoryUpload = directoryUpload.completionFuture().join();
        completedDirectoryUpload.failedTransfers()
                .forEach(fail -> logger.warn("Object [{}] failed to transfer", fail.toString()));
        return completedDirectoryUpload.failedTransfers().size();
    }


import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.services.s3.model.ObjectIdentifier;
import software.amazon.awssdk.transfer.s3.S3TransferManager;
import software.amazon.awssdk.transfer.s3.model.CompletedDirectoryUpload;
import software.amazon.awssdk.transfer.s3.model.DirectoryUpload;
import software.amazon.awssdk.transfer.s3.model.UploadDirectoryRequest;

import java.net.URI;
import java.net.URISyntaxException;
import java.net.URL;
import java.nio.file.Paths;
import java.util.UUID;

Baixar objetos do bucket do S3 para um diretório local

É possível baixar os objetos em um bucket do S3 para um diretório local, conforme mostrado no exemplo a seguir.

Para baixar os objetos em um bucket do S3 para um diretório local, comece chamando o método downloadDirectory do Transfer Manager, passando um. DownloadDirectoryRequest

O DirectoryDownloadobjeto representa o processo de download, que gera um CompletedDirectoryDownloadquando a solicitação é concluída. O objeto CompleteDirectoryDownload contém informações sobre os resultados da transferência, incluindo quais arquivos falharam na transferência.


    public Integer downloadObjectsToDirectory(S3TransferManager transferManager,
            URI destinationPathURI, String bucketName) {
        DirectoryDownload directoryDownload = transferManager.downloadDirectory(DownloadDirectoryRequest.builder()
                .destination(Paths.get(destinationPathURI))
                .bucket(bucketName)
                .build());
        CompletedDirectoryDownload completedDirectoryDownload = directoryDownload.completionFuture().join();

        completedDirectoryDownload.failedTransfers()
                .forEach(fail -> logger.warn("Object [{}] failed to transfer", fail.toString()));
        return completedDirectoryDownload.failedTransfers().size();
    }


import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.core.sync.RequestBody;
import software.amazon.awssdk.services.s3.model.ObjectIdentifier;
import software.amazon.awssdk.transfer.s3.S3TransferManager;
import software.amazon.awssdk.transfer.s3.model.CompletedDirectoryDownload;
import software.amazon.awssdk.transfer.s3.model.DirectoryDownload;
import software.amazon.awssdk.transfer.s3.model.DownloadDirectoryRequest;
import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.HashSet;
import java.util.Set;
import java.util.UUID;
import java.util.stream.Collectors;

Ver exemplos completos

GitHub contém o código completo de todos os exemplos desta página.

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Configurar o suporte à transferência paralela

Notificações de eventos do S3