Carga de archivos y directorios Descarga de archivos o directorios Copia de objetos Esperar a que se complete una transferencia Obtener el estado y el progreso de una transferencia Más información

Uso de TransferManager para operaciones de Amazon S3

Puede utilizar la clase AWS SDK for Java TransferManager para transferir archivos de forma fiable desde el entorno local a Amazon S3 y para copiar objetos de una ubicación de S3 a otra. TransferManager puede obtener el progreso de la transferencia y detener o reanudar las cargas y descargas.

nota

Práctica recomendada

Le recomendamos que habilite la regla del ciclo de vida AbortIncompleteMultipartUpload en los buckets de Amazon S3.

Esta regla le indica a Amazon S3 que anule las cargas multiparte que no se completen en un número especificado de días después de iniciarse. Cuando se supera el plazo establecido, Amazon S3 anula la carga y, a continuación, elimina la carga de datos incompleta.

Para obtener más información, consulte Configuración de ciclo de vida para un bucket con control de versiones en la Guía del usuario de Amazon S3.

nota

En estos ejemplos de código se presupone que conoce la información que se describe en Uso del AWS SDK for Java y que ha configurado credenciales de AWS predeterminadas mediante la información de Configuración de credenciales y regiones de AWS para desarrollo.

Carga de archivos y directorios

TransferManager puede cargar archivos, listas de archivos y directorios en cualquier bucket de Amazon S3 que haya creado previamente.

Carga de un solo archivo

Llame al método upload de TransferManager, proporcionando un nombre de bucket de Amazon S3, un nombre de clave (objeto) y un objeto File Java estándar que represente el archivo que se va a cargar.

Importaciones


import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.s3.transfer.MultipleFileUpload;
import com.amazonaws.services.s3.transfer.TransferManager;
import com.amazonaws.services.s3.transfer.TransferManagerBuilder;
import com.amazonaws.services.s3.transfer.Upload;

import java.io.File;
import java.util.ArrayList;
import java.util.Arrays;

Code


File f = new File(file_path);
TransferManager xfer_mgr = TransferManagerBuilder.standard().build();
try {
    Upload xfer = xfer_mgr.upload(bucket_name, key_name, f);
    // loop with Transfer.isDone()
    XferMgrProgress.showTransferProgress(xfer);
    //  or block with Transfer.waitForCompletion()
    XferMgrProgress.waitForCompletion(xfer);
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.exit(1);
}
xfer_mgr.shutdownNow();

El método upload regresa inmediatamente, proporcionando el objeto Upload que se va a usar para comprobar el estado de la transferencia o esperar a que se complete.

Consulte Esperar a que se complete una transferencia para obtener información sobre cómo usar waitForCompletion para completar correctamente una transferencia antes de llamar al método shutdownNow de TransferManager. Mientras espera a que se complete la transferencia, puede buscar o atender las actualizaciones sobre su estado y su progreso. Consulte Obtener el estado y el progreso de una transferencia para obtener más información.

Consulte el ejemplo completo en GitHub.

Carga de una lista de archivos

Para cargar varios archivos en una sola operación, llame al método uploadFileList de TransferManager, proporcionando lo siguiente:

Un nombre de bucket de Amazon S3
Un prefijo de clave para adjuntarlo a los nombres de los objetos creados (la ruta en el bucket en el que se colocan los objetos)
Un objeto File que represente el directorio relativo desde el que crean las rutas de archivo
Un objeto List que contenga el conjunto de objetos File que se van a cargar

Importaciones


import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.s3.transfer.MultipleFileUpload;
import com.amazonaws.services.s3.transfer.TransferManager;
import com.amazonaws.services.s3.transfer.TransferManagerBuilder;
import com.amazonaws.services.s3.transfer.Upload;

import java.io.File;
import java.util.ArrayList;
import java.util.Arrays;

Code


ArrayList<File> files = new ArrayList<File>();
for (String path : file_paths) {
    files.add(new File(path));
}

TransferManager xfer_mgr = TransferManagerBuilder.standard().build();
try {
    MultipleFileUpload xfer = xfer_mgr.uploadFileList(bucket_name,
            key_prefix, new File("."), files);
    // loop with Transfer.isDone()
    XferMgrProgress.showTransferProgress(xfer);
    // or block with Transfer.waitForCompletion()
    XferMgrProgress.waitForCompletion(xfer);
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.exit(1);
}
xfer_mgr.shutdownNow();

El objeto MultipleFileUpload devuelto por uploadFileList se puede usar para consultar el estado o el progreso de la transferencia. Consulte Sondear el progreso actual de una transferencia y Obtener el progreso de una transferencia con ProgressListener para obtener más información.

También puede usar el método MultipleFileUpload de getSubTransfers para obtener los distintos objetos Upload para cada archivo que se va a transferir. Para obtener más información, consulte Obtener el progreso de las transferencias secundarias.

Consulte el ejemplo completo en GitHub.

Carga de un directorio

Puede utilizar el método uploadDirectory de TransferManager para cargar un directorio de archivos completo, con la opción de copiar archivos en subdirectorios recursivamente. Proporciona el nombre de un bucket de Amazon S3, un prefijo de clave de S3, un objeto File que representa el directorio local donde se va a realizar la copia y un valor boolean que indica si desea copiar los subdirectorios recursivamente (true o false).

Importaciones


import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.s3.transfer.MultipleFileUpload;
import com.amazonaws.services.s3.transfer.TransferManager;
import com.amazonaws.services.s3.transfer.TransferManagerBuilder;
import com.amazonaws.services.s3.transfer.Upload;

import java.io.File;
import java.util.ArrayList;
import java.util.Arrays;

Code


TransferManager xfer_mgr = TransferManagerBuilder.standard().build();
try {
    MultipleFileUpload xfer = xfer_mgr.uploadDirectory(bucket_name,
            key_prefix, new File(dir_path), recursive);
    // loop with Transfer.isDone()
    XferMgrProgress.showTransferProgress(xfer);
    // or block with Transfer.waitForCompletion()
    XferMgrProgress.waitForCompletion(xfer);
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.exit(1);
}
xfer_mgr.shutdownNow();

Consulte el ejemplo completo en GitHub.

Descarga de archivos o directorios

Utilice la clase TransferManager para descargar un solo archivo (objeto Amazon S3) o un directorio (el nombre de un bucket de Amazon S3 seguido de un prefijo de objeto) de Amazon S3.

Temas

Descarga de un solo archivo
Descarga de un directorio

Descarga de un solo archivo

Utilice el método download de TransferManager, proporcionando el nombre del bucket de Amazon S3 que contiene el objeto que desea descargar, la clave (nombre de objeto) y un objeto File que represente el archivo que va a crear en su sistema local.

Importaciones


import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.s3.transfer.Download;
import com.amazonaws.services.s3.transfer.MultipleFileDownload;
import com.amazonaws.services.s3.transfer.TransferManager;
import com.amazonaws.services.s3.transfer.TransferManagerBuilder;

import java.io.File;

Code


File f = new File(file_path);
TransferManager xfer_mgr = TransferManagerBuilder.standard().build();
try {
    Download xfer = xfer_mgr.download(bucket_name, key_name, f);
    // loop with Transfer.isDone()
    XferMgrProgress.showTransferProgress(xfer);
    // or block with Transfer.waitForCompletion()
    XferMgrProgress.waitForCompletion(xfer);
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.exit(1);
}
xfer_mgr.shutdownNow();

Consulte el ejemplo completo en GitHub.

Descarga de un directorio

Para descargar un conjunto de archivos que comparten un prefijo de clave común (similar a un directorio en un sistema de archivos) desde Amazon S3, utilice el método downloadDirectory de TransferManager. El método toma el nombre del bucket de Amazon S3 que contiene los objetos que desea descargar, el prefijo de objeto compartido por todos los objetos y un objeto File que representa el directorio en el que se van a descargar los archivos en su sistema local. Si el directorio designado aún no existe, se creará.

Importaciones


import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.s3.transfer.Download;
import com.amazonaws.services.s3.transfer.MultipleFileDownload;
import com.amazonaws.services.s3.transfer.TransferManager;
import com.amazonaws.services.s3.transfer.TransferManagerBuilder;

import java.io.File;

Code


TransferManager xfer_mgr = TransferManagerBuilder.standard().build();

try {
    MultipleFileDownload xfer = xfer_mgr.downloadDirectory(
            bucket_name, key_prefix, new File(dir_path));
    // loop with Transfer.isDone()
    XferMgrProgress.showTransferProgress(xfer);
    // or block with Transfer.waitForCompletion()
    XferMgrProgress.waitForCompletion(xfer);
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.exit(1);
}
xfer_mgr.shutdownNow();

Consulte el ejemplo completo en GitHub.

Copia de objetos

Para copiar un objeto en un bucket de S3 en otro, utilice el método copy de TransferManager.

Importaciones


import com.amazonaws.AmazonServiceException;
import com.amazonaws.services.s3.transfer.Copy;
import com.amazonaws.services.s3.transfer.TransferManager;
import com.amazonaws.services.s3.transfer.TransferManagerBuilder;

Code


System.out.println("Copying s3 object: " + from_key);
System.out.println("      from bucket: " + from_bucket);
System.out.println("     to s3 object: " + to_key);
System.out.println("        in bucket: " + to_bucket);

TransferManager xfer_mgr = TransferManagerBuilder.standard().build();
try {
    Copy xfer = xfer_mgr.copy(from_bucket, from_key, to_bucket, to_key);
    // loop with Transfer.isDone()
    XferMgrProgress.showTransferProgress(xfer);
    // or block with Transfer.waitForCompletion()
    XferMgrProgress.waitForCompletion(xfer);
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.exit(1);
}
xfer_mgr.shutdownNow();

Consulte el ejemplo completo en GitHub.

Esperar a que se complete una transferencia

Si la aplicación (o subproceso) se puede bloquear hasta que se complete la transferencia, puede utilizar el método waitForCompletion de la interfaz Transfer para aplicar un bloqueo hasta que se complete la transferencia o se produzca una excepción.


try {
    xfer.waitForCompletion();
} catch (AmazonServiceException e) {
    System.err.println("Amazon service error: " + e.getMessage());
    System.exit(1);
} catch (AmazonClientException e) {
    System.err.println("Amazon client error: " + e.getMessage());
    System.exit(1);
} catch (InterruptedException e) {
    System.err.println("Transfer interrupted: " + e.getMessage());
    System.exit(1);
}

Puede obtener el progreso de las transferencias si sondea eventos antes de llamar a waitForCompletion, implementar un mecanismo de sondeo en un subproceso distinto o recibir actualizaciones sobre el progreso de forma asíncrona utilizando un ProgressListener.

Consulte el ejemplo completo en GitHub.

Obtener el estado y el progreso de una transferencia

Cada una de las clases devueltas por los métodos upload*, download* y copy de TransferManager devuelve una instancia de una de las siguientes clases, en función de si se trata de una operación en un solo archivo o en varios.


Clase	Devuelta por
Copiar	`copy`
Descargar	`download`
MultipleFileDownload	`downloadDirectory`
Cargar	`upload`
MultipleFileUpload	`uploadFileList`, `uploadDirectory`

Todas estas clases implementan la interfaz Transfer. Transfer proporciona métodos útiles para obtener el progreso de una transferencia, detener o reanudar la transferencia y obtener el estado actual o final de la transferencia.

Temas

Sondear el progreso actual de una transferencia
Obtener el progreso de una transferencia con ProgressListener
Obtener el progreso de las transferencias secundarias

Sondear el progreso actual de una transferencia

Este bucle muestra el progreso de una transferencia, examina su progreso actual mientras se ejecuta y, cuando se completa, muestra su estado final.

Importaciones


import com.amazonaws.AmazonClientException;
import com.amazonaws.AmazonServiceException;
import com.amazonaws.event.ProgressEvent;
import com.amazonaws.event.ProgressListener;
import com.amazonaws.services.s3.transfer.*;
import com.amazonaws.services.s3.transfer.Transfer.TransferState;

import java.io.File;
import java.util.ArrayList;
import java.util.Collection;

Code


// print the transfer's human-readable description
System.out.println(xfer.getDescription());
// print an empty progress bar...
printProgressBar(0.0);
// update the progress bar while the xfer is ongoing.
do {
    try {
        Thread.sleep(100);
    } catch (InterruptedException e) {
        return;
    }
    // Note: so_far and total aren't used, they're just for
    // documentation purposes.
    TransferProgress progress = xfer.getProgress();
    long so_far = progress.getBytesTransferred();
    long total = progress.getTotalBytesToTransfer();
    double pct = progress.getPercentTransferred();
    eraseProgressBar();
    printProgressBar(pct);
} while (xfer.isDone() == false);
// print the final state of the transfer.
TransferState xfer_state = xfer.getState();
System.out.println(": " + xfer_state);

Consulte el ejemplo completo en GitHub.

Obtener el progreso de una transferencia con ProgressListener

Puede asociar ProgressListener a cualquier transferencia mediante el método addProgressListener de la interfaz Transfer.

Un ProgressListener requiere solo un método progressChanged, que toma un objeto ProgressEvent. Puede utilizar el objeto para obtener el total de bytes de la operación llamando a su método getBytes y el número de bytes que se han transferido hasta el momento llamando a getBytesTransferred.

Importaciones


import com.amazonaws.AmazonClientException;
import com.amazonaws.AmazonServiceException;
import com.amazonaws.event.ProgressEvent;
import com.amazonaws.event.ProgressListener;
import com.amazonaws.services.s3.transfer.*;
import com.amazonaws.services.s3.transfer.Transfer.TransferState;

import java.io.File;
import java.util.ArrayList;
import java.util.Collection;

Code


File f = new File(file_path);
TransferManager xfer_mgr = TransferManagerBuilder.standard().build();
try {
    Upload u = xfer_mgr.upload(bucket_name, key_name, f);
    // print an empty progress bar...
    printProgressBar(0.0);
    u.addProgressListener(new ProgressListener() {
        public void progressChanged(ProgressEvent e) {
            double pct = e.getBytesTransferred() * 100.0 / e.getBytes();
            eraseProgressBar();
            printProgressBar(pct);
        }
    });
    // block with Transfer.waitForCompletion()
    XferMgrProgress.waitForCompletion(u);
    // print the final state of the transfer.
    TransferState xfer_state = u.getState();
    System.out.println(": " + xfer_state);
} catch (AmazonServiceException e) {
    System.err.println(e.getErrorMessage());
    System.exit(1);
}
xfer_mgr.shutdownNow();

Consulte el ejemplo completo en GitHub.

Obtener el progreso de las transferencias secundarias

La clase MultipleFileUpload puede devolver información sobre sus transferencias secundarias llamando a su método getSubTransfers. Devuelve una colección no modificable de objetos Upload que proporcionan el estado y el progreso de cada transferencia secundaria.

Importaciones


import com.amazonaws.AmazonClientException;
import com.amazonaws.AmazonServiceException;
import com.amazonaws.event.ProgressEvent;
import com.amazonaws.event.ProgressListener;
import com.amazonaws.services.s3.transfer.*;
import com.amazonaws.services.s3.transfer.Transfer.TransferState;

import java.io.File;
import java.util.ArrayList;
import java.util.Collection;

Code


Collection<? extends Upload> sub_xfers = new ArrayList<Upload>();
sub_xfers = multi_upload.getSubTransfers();

do {
    System.out.println("\nSubtransfer progress:\n");
    for (Upload u : sub_xfers) {
        System.out.println("  " + u.getDescription());
        if (u.isDone()) {
            TransferState xfer_state = u.getState();
            System.out.println("  " + xfer_state);
        } else {
            TransferProgress progress = u.getProgress();
            double pct = progress.getPercentTransferred();
            printProgressBar(pct);
            System.out.println();
        }
    }

    // wait a bit before the next update.
    try {
        Thread.sleep(200);
    } catch (InterruptedException e) {
        return;
    }
} while (multi_upload.isDone() == false);
// print the final state of the transfer.
TransferState xfer_state = multi_upload.getState();
System.out.println("\nMultipleFileUpload " + xfer_state);

Consulte el ejemplo completo en GitHub.

Más información

Claves de objeto en la Guía del usuario de Amazon Simple Storage Service

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Administración del acceso a los buckets de Amazon S3 mediante políticas de buckets

Configuración de un bucket de Amazon S3 como un sitio web