Transferir archivos y directorios con Amazon S3 Transfer Manager - AWS SDK for Java 2.x
IntroducciónCarga de un archivoDescargar un archivoCopiar un objetoCargar un directorioDescargar en un directorioVea ejemplos completos

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Transferir archivos y directorios con Amazon S3 Transfer Manager

Amazon S3 Transfer Manager es una utilidad de transferencia de archivos de alto nivel y de código abierto para el AWS SDK for Java 2.x. Úselo para transferir archivos y directorios desde y hacia Amazon Simple Storage Service (Amazon S3).

Cuando se basa en el cliente S3 AWS basado en CRT o en el cliente asíncrono S3estándar basado en Java con la función multiparte habilitada, el S3 Transfer Manager puede aprovechar las mejoras de rendimiento, como la API de carga multiparte y las recuperaciones por rango de bytes.

Con el S3 Transfer Manager, también puede supervisar el progreso de una transferencia en tiempo real y pausarla para su posterior ejecución.

Introducción

Añadir dependencias a su archivo de compilación

Para utilizar el S3 Transfer Manager con un rendimiento multiparte mejorado, configure el archivo de compilación con las dependencias necesarias.

Use the AWS CRT-based S3 client
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>bom</artifactId>
            <version>2.27.211</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.29.1432</version>
    </dependency>
</dependencies>

1 Versión más reciente. 2 Última versión.

Use the Java-based S3 async client
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>software.amazon.awssdk</groupId>
            <artifactId>bom</artifactId>
            <version>2.27.211</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>s3-transfer-manager</artifactId>
    </dependency>
</dependencies>

1 Última versión.

Crear una instancia del S3 Transfer Manager

Para habilitar la transferencia paralela, debe pasar un cliente S3 basado en AWS CRT O un cliente asíncrono S3 basado en Java con múltiples partes habilitadas. Los siguientes ejemplos muestran cómo configurar un S3 Transfer Manager con ajustes personalizados.

Use the AWS CRT-based S3 client
        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();
Use the Java-based S3 async client

Si la aws-crt dependencia no está incluida en el archivo de compilación, S3 Transfer Manager se crea sobre el cliente asíncrono S3 estándar basado en Java que se utiliza en el SDK para Java 2.x.

Configuración personalizada del cliente S3: requiere tener habilitada la funcionalidad multiparte

        S3AsyncClient s3AsyncClient = S3AsyncClient.builder()
                .multipartEnabled(true)
                .credentialsProvider(DefaultCredentialsProvider.create())
                .region(Region.US_EAST_1)
                .build();

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

Sin configuración del cliente S3: la compatibilidad con varias partes se habilita automáticamente

S3TransferManager transferManager = S3TransferManager.create();

Cargar un archivo en un bucket de S3

El siguiente ejemplo muestra un ejemplo de carga de archivos junto con el uso opcional de un LoggingTransferListener, que registra el progreso de la carga.

Para cargar un archivo en Amazon S3 mediante el S3 Transfer Manager, pase un objeto UploadFileRequest al método uploadFile del S3TransferManager.

El FileUploadobjeto devuelto por el uploadFile método representa el proceso de carga. Una vez finalizada la solicitud, el CompletedFileUploadobjeto contiene información sobre la carga.

    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;

Descargar un archivo de un bucket de S3

El siguiente ejemplo muestra un ejemplo de descarga junto con el uso opcional de un LoggingTransferListener, que registra el progreso de la descarga.

Para descargar un objeto de un bucket de S3 mediante el administrador de transferencias de S3, cree un DownloadFileRequestobjeto y páselo al método downloadFile.

El FileDownloadobjeto devuelto por el downloadFile método S3TransferManager's representa la transferencia de archivos. Una vez completada la descarga, CompletedFileDownloadcontiene el acceso a la información sobre la descarga.

    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;

Copiar un objeto de Amazon S3 a otro bucket

En el siguiente ejemplo se muestra cómo copiar un objeto con S3 Transfer Manager.

Para empezar a copiar un objeto de un bucket de S3 a otro bucket, cree una CopyObjectRequestinstancia básica.

A continuación, incluya la básica CopyObjectRequest en una CopyRequestque pueda utilizar el S3 Transfer Manager.

El objeto Copy devuelto por el método copy de S3TransferManager representa el proceso de copia. Una vez finalizado el proceso de copia, el CompletedCopyobjeto contiene detalles sobre la respuesta.

    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 una copia entre regiones con el administrador de transferencias de S3, habilítelo crossRegionAccessEnabled en el generador de clientes S3 AWS basado en CRT, como se muestra en el siguiente fragmento.

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;

Cargar un directorio local en un bucket de S3

En el siguiente ejemplo se muestra cómo se puede cargar un directorio local en S3.

Comience por llamar al método UploadDirectory de la instancia e introduzca un. S3TransferManager UploadDirectoryRequest

El DirectoryUploadobjeto representa el proceso de carga, que genera un CompletedDirectoryUploadcuando se completa la solicitud. El objeto CompleteDirectoryUpload contiene información sobre los resultados de la transferencia, incluidos los archivos que no se pudieron transferir.

    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;

Descargar objetos de bucket S3 en un directorio local

Puede descargar los objetos de un bucket S3 en un directorio local tal y como se muestra en el siguiente ejemplo.

Para descargar los objetos de un bucket de S3 a un directorio local, comience por llamar al método downloadDirectory del Transfer Manager e introduzca un DownloadDirectoryRequest.

El DirectoryDownloadobjeto representa el proceso de descarga, que genera un CompletedDirectoryDownloadcuando se completa la solicitud. El objeto CompleteDirectoryDownload contiene información sobre los resultados de la transferencia, incluidos los archivos que no se pudieron transferir.

    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;

Vea ejemplos completos

GitHub contiene el código completo de todos los ejemplos de esta página.