Fazer upload de arquivos e diretórios Fazer download de arquivos ou diretórios Copiar objetos Aguardar a conclusão de uma transferência Obter status da transferência e progresso Mais informações

Usar o TransferManager em operações do Amazon S3

Você pode usar a classe TransferManager do AWS SDK for Java para transferir arquivos de maneira confiável do ambiente local para Amazon S3 e copiar objetos de um local do S3 para outro. O TransferManager pode saber o andamento de uma transferência e pausar ou retomar uploads e downloads.

nota

Melhor prática

Recomendamos habilitar a regra de ciclo de vida AbortIncompleteMultipartUpload nos buckets do Amazon S3.

Essa regra leva o Amazon S3 a anular multipart uploads que não sejam concluídos dentro de um número específico de dias depois de serem iniciados. Quando o limite de tempo definido é excedido, o Amazon S3 anula o upload e exclui os dados de uploads incompletos.

Para obter mais informações, consulte Configuração do ciclo de vida de um bucket com versionamento no Guia do usuário do Amazon S3.

nota

Esses exemplos de código pressupõem que você entenda o material em Usar o AWS SDK for Java e tenha configurado credenciais da AWS padrão usando as informações em Configurar credenciais e região da AWS para desenvolvimento.

Fazer upload de arquivos e diretórios

O TransferManager pode fazer upload de arquivos, listas de arquivos e diretórios para todos os buckets do Amazon S3 criados anteriormente.

Fazer upload de um único arquivo

Chame o método upload do TransferManager, fornecendo um nome de bucket do Amazon S3, um nome de chave (objeto) e um objeto File do Java padrão que represente o arquivo para upload.

Importações


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;

Código


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();

O método upload retorna imediatamente, fornecendo um objeto Upload a ser usado para verificar o estado de transferência ou aguardar a conclusão.

Consulte Aguardar a conclusão de uma transferência para obter informações sobre como usar waitForCompletion para concluir com êxito uma transferência antes de chamar o método shutdownNow do TransferManager. Enquanto aguarda a conclusão da transferência, você pode sondar ou escutar atualizações sobre o status e o progresso. Consulte Obter status de transferência e progresso para obter mais informações.

Veja o exemplo completo no GitHub.

Fazer upload de uma lista de arquivos

Para fazer upload de vários arquivos em uma única operação, chame o método uploadFileList do TransferManager, fornecendo o seguinte:

Um nome do bucket do Amazon S3
Um prefixo de chaves a ser acrescentado aos nomes dos objetos criados (o caminho dentro do bucket no qual colocar os objetos)
Um objeto File que representa o diretório relativo do qual criar caminhos de arquivo
Um objeto List contendo um conjunto de objetos File para upload

Importações


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;

Código


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();

O objeto MultipleFileUpload retornado por uploadFileList pode ser usado para consultar o estado da transferência ou o progresso. Consulte Sondar o progresso atual de uma transferência e Obter o progresso da transferência com um ProgressListener para obter mais informações.

Você também pode usar o método getSubTransfers de MultipleFileUpload para obter os objetos Upload individuais de cada arquivo transferido. Para obter mais informações, consulte Obter o progresso de subtransferências.

Veja o exemplo completo no GitHub.

Fazer upload de um diretório

É possível usar o método uploadDirectory do TransferManager para fazer upload de um diretório de arquivos inteiro, com a opção de copiar arquivos em subdiretórios de maneira recursiva. Você fornece um nome de bucket do Amazon S3, um prefixo de chaves do S3, um objeto File representando o diretório local para cópia e um valor boolean que indica se deseja copiar subdiretórios de maneira recursiva (verdadeiro ou falso).

Importações


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;

Código


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();

Veja o exemplo completo no GitHub.

Fazer download de arquivos ou diretórios

Use a classe TransferManager para fazer download de um único arquivo (objeto do Amazon S3) ou de um diretório (um nome de bucket do Amazon S3 seguido de um prefixo de objeto) do Amazon S3.

Tópicos

Fazer download de um único arquivo
Fazer download de um diretório

Fazer download de um único arquivo

Use o método download do TransferManager, fornecendo o nome de bucket do Amazon S3 que contém o objeto cujo download você deseja fazer, o nome da chave (objeto) e um objeto File que representa o arquivo a ser criado no sistema local.

Importações


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;

Código


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();

Veja o exemplo completo no GitHub.

Fazer download de um diretório

Para fazer download de um conjunto de arquivos que compartilham um mesmo prefixo de chaves (semelhante a um diretório em um sistema de arquivos) do Amazon S3, use o método downloadDirectory do TransferManager. O método utiliza o nome de bucket do Amazon S3 que contém os objetos cujo download você deseja fazer, o prefixo do objeto compartilhado por todos os objetos e um objeto File que representa o diretório para fazer download dos arquivos no sistema local. Se ainda não existir, o diretório nomeado será criado.

Importações


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;

Código


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();

Veja o exemplo completo no GitHub.

Copiar objetos

Para copiar um objeto de um bucket do S3 para outro, use o método copy do TransferManager.

Importações


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;

Código


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();

Veja o exemplo completo no GitHub.

Aguardar a conclusão de uma transferência

Se o aplicativo (ou thread) puder bloquear até a conclusão da transferência, você poderá usar o método waitForCompletion da interface Transfer para bloquear até a transferência estar concluída ou ocorrer uma exceção.


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);
}

Você obterá o progresso de transferências se sondar eventos antes de chamar waitForCompletion, implementar um mecanismo de sondagem em um thread separado ou receber atualizações de progresso de maneira assíncrona usando um ProgressListener.

Veja o exemplo completo no GitHub.

Obter status da transferência e progresso

Cada uma das classes retornadas pelos métodos upload*, download* e copy do TransferManager retorna uma instância de uma das classes a seguir, dependendo da operação ser de arquivo único ou de vários arquivos.


Classe	Retornado por
Copiar	`copy`
Baixar	`download`
MultipleFileDownload	`downloadDirectory`
Carregar	`upload`
MultipleFileUpload	`uploadFileList`, `uploadDirectory`

Todas essas classes implementam a interface Transfer. O Transfer oferece métodos úteis para obter o progresso de uma transferência, pausar ou retomar a transferência, além de obter o status atual ou final da transferência.

Tópicos

Sondar o progresso atual de uma transferência
Obter o progresso da transferência com um ProgressListener
Obter o progresso de subtransferências

Sondar o progresso atual de uma transferência

Este loop imprime o progresso de uma transferência, examina o progresso atual durante a execução e, quando concluído, imprime o estado final.

Importações


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;

Código


// 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);

Veja o exemplo completo no GitHub.

Obter o progresso da transferência com um ProgressListener

Você pode anexar um ProgressListener a qualquer transferência usando o método addProgressListener da interface Transfer.

Um ProgressListener exige somente um método, progressChanged, que utiliza um objeto ProgressEvent. Você pode usar o objeto para obter o total de bytes da operação chamando o método getBytes e o número de bytes transferidos até o momento chamando getBytesTransferred.

Importações


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;

Código


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();

Veja o exemplo completo no GitHub.

Obter o progresso de subtransferências

A classe MultipleFileUpload pode retornar informações sobre as subtransferências chamando o método getSubTransfers. Isso retorna um Conjunto de objetos Upload que fornecem o status de transferência individual e o progresso de cada subtransferência.

Importações


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;

Código


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);

Veja o exemplo completo no GitHub.

Mais informações

Chaves de objeto no Guia do usuário do Amazon Simple Storage Service

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

Gerenciar acesso a buckets do Amazon S3 usando políticas de bucket

Configurar um bucket do Amazon S3 como um site