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 CRT baseado, o S3 Transfer Manager pode aproveitar as melhorias de desempenho, como o upload de várias partes API e a busca 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 com base no cliente S3 AWS CRT baseado, configure seu arquivo de compilação com as seguintes dependências.

Use a versão 2.19.1 ou superior ao SDK para Java 2.x.
Adicionar o artefato s3-transfer-manager como uma dependência.
Adicione o aws-crt artefato como uma dependência na versão 0.20.3 ou superior.

O exemplo de código a seguir mostra como configurar as dependências do projeto para o Maven.


<project>
   <properties>
     <aws.sdk.version>2.19.1</aws.sdk.version>
  </properties>  
  <dependencyManagement>
   <dependencies>
      <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>bom</artifactId>
        <version>${aws.sdk.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
   </dependencies>
  </dependencyManagement>
  <dependencies>
   <dependency>
      <groupId>software.amazon.awssdk</groupId>
      <artifactId>s3-transfer-manager</artifactId>
   </dependency>
   <dependency>
      <groupId>software.amazon.awssdk.crt</groupId>
      <artifactId>aws-crt</artifactId>
      <version>0.20.3</version>
   </dependency>
  </dependencies>
</project>

Pesquise no repositório central do Maven as versões mais recentes dos artefatos s3-transfer-manager e aws-crt.

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

O trecho a seguir mostra como criar uma TransferManager instância do S3 com configurações padrão.


        S3TransferManager transferManager = S3TransferManager.create();

O exemplo a seguir mostra como configurar um gerenciador de transferências do S3 com configurações personalizadas. Neste exemplo, uma AsyncClient instância S3 AWS CRT baseada é usada como cliente subjacente para o S3 Transfer Manager.


        S3AsyncClient s3AsyncClient = S3AsyncClient.crtBuilder()
                .credentialsProvider(DefaultCredentialsProvider.create())
                .region(Region.US_EAST_1)
                .targetThroughputInGbps(20.0)
                .minimumPartSizeInBytes(8 * MB)
                .build();

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

nota

Se a aws-crt dependência não estiver incluída no arquivo de compilação, o S3 Transfer Manager será construído sobre o cliente assíncrono S3 padrão usado no for Java 2.x. SDK

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 fazer upload de um arquivo para o Amazon S3 usando o S3 Transfer Manager, passe um UploadFileRequestobjeto para o S3TransferManager método's. uploadFile

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 String uploadFile(S3TransferManager transferManager, String bucketName,
                             String key, URI filePathURI) {
        UploadFileRequest uploadFileRequest = UploadFileRequest.builder()
            .putObjectRequest(b -> b.bucket(bucketName).key(key))
            .source(Paths.get(filePathURI))
            .build();

        FileUpload fileUpload = transferManager.uploadFile(uploadFileRequest);

        CompletedFileUpload uploadResult = fileUpload.completionFuture().join();
        return uploadResult.response().eTag();
    }


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 downloadFilemétodo.

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 Long downloadFile(S3TransferManager transferManager, String bucketName,
                             String key, String downloadedFileWithPath) {
        DownloadFileRequest downloadFileRequest = DownloadFileRequest.builder()
                .getObjectRequest(b -> b.bucket(bucketName).key(key))
                .destination(Paths.get(downloadedFileWithPath))
                .build();

        FileDownload downloadFile = transferManager.downloadFile(downloadFileRequest);

        CompletedFileDownload downloadResult = downloadFile.completionFuture().join();
        logger.info("Content length [{}]", downloadResult.response().contentLength());
        return downloadResult.response().contentLength();
    }



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 CRT baseado, 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 uploadDirectorymétodo 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 downloadDirectorymétodo do Transfer Manager, passando a. 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

Usar um cliente do S3 de alta performance

Notificações de eventos do S3