Como usar comandos de alto nível (s3) na AWS CLI - AWS Command Line Interface
Pré-requisitosAntes de começarCriar um bucketListar buckets e objetosExcluir bucketsExcluir objetosMover objetosCopiar objetosSincronizar objetosOpções usadas com frequência para comandos s3Recursos

Como usar comandos de alto nível (s3) na AWS CLI

Este tópico descreve alguns dos comandos que você pode utilizar para gerenciar buckets e objetos do Amazon S3 usando os comandos aws s3 na AWS CLI. Para comandos não abordados neste tópico e exemplos de comandos adicionais, consulte os comandos aws s3 na Referência da AWS CLI.

Os comandos aws s3 de alto nível simplificam o gerenciamento de objetos do Amazon S3. Esses comandos permitem a você gerenciar o conteúdo do Amazon S3 dentro dele mesmo e com diretórios locais.

Pré-requisitos

Para executar os comandos s3, você precisa:

Antes de começar

Esta seção descreve algumas coisas a serem observadas antes de usar comandos da aws s3.

Carregamentos de objetos grandes

Quando você usa comandos da aws s3 para fazer upload de objetos grandes em um bucket do Amazon S3, a AWS CLI executa automaticamente um upload fracionado. Quando esses comandos da aws s3 são usados, não é possível continuar uploads que falharam.

Se o upload fracionado falhar devido a um tempo limite excedido, ou se você o cancelou manualmente na AWS CLI, a AWS CLI interromperá o upload e limpará todos os arquivos que foram criados. Esse processo pode levar alguns minutos.

Se o processo de upload fracionado ou limpeza for cancelado por um comando kill ou uma falha do sistema, os arquivos criados permanecerão no bucket do Amazon S3. Para limpar o carregamento fracionado, use o comando s3api abort-multipart-upload

Propriedades e tags de arquivos em cópias com várias partes

Quando você usa a versão da AWS CLI versão 1 dos comandos no namespace do aws s3 para copiar um arquivo de um local de bucket do Amazon S3 para outro local de bucket do Amazon S3 e essa operação usa a cópia fracionada, nenhuma propriedade de arquivo do objeto de origem é copiada para o objeto de destino.

Por padrão, os comandos da AWS CLI versão 2 no namespace do s3 que executam cópias de várias partes agora transferem todas as etiquetas e o seguinte conjunto de propriedades da cópia de origem para a cópia de destino: content-type, content-language, content-encoding, content-disposition, cache-control, expires e metadata.

Isso pode resultar em chamadas de API da AWS adicionais para o endpoint do Amazon S3 que não teriam sido feitas se você tivesse usado a AWS CLI versão 1. Elas podem incluir: HeadObject, GetObjectTagging e PutObjectTagging.

Se você precisar alterar esse comportamento padrão em comandos da AWS CLI versão 2, use o parâmetro --copy-props para especificar uma das seguintes opções:

  • default: o valor padrão. Especifica que a cópia inclui todas as tags anexadas ao objeto de origem e as propriedades englobadas pelo parâmetro --metadata-directive usado para cópias que não são multipart: content-type, content-language, content-encoding, content-disposition, cache-control, expires e metadata.

  • metadata-directive: especifica que a cópia inclui apenas as propriedades que são englobadas pelo parâmetro --metadata-directive usado para cópias não fracionadas. Não copia nenhuma etiqueta.

  • none: especifica que a cópia não inclui nenhuma das propriedades do objeto de origem.

Criar um bucket

Use o comando s3 mb para criar um bucket. Os nomes de bucket devem ser globalmente exclusivos (únicos em todo o Amazon S3) e devem ser compatíveis com o DNS.

Nomes de bucket podem conter letras minúsculas, números, hífens e pontos. Os nomes de bucket podem iniciar e terminar apenas com uma letra ou número e não podem conter um ponto ao lado de um hífen ou outro ponto.

Sintaxe

$ aws s3 mb <target> [--options]

O exemplo a seguir cria o bucket s3://amzn-s3-demo-bucket.

$ aws s3 mb s3://amzn-s3-demo-bucket

Listar buckets e objetos

Para listar seus buckets, pastas ou objetos, use o comando s3 ls. O uso do comando sem um destino ou opções lista todos os buckets.

Sintaxe

$ aws s3 ls <target> [--options]

Para ver algumas opções comuns que podem ser usadas com este comando e exemplos, consulte Opções usadas com frequência para comandos s3. Para obter uma lista completa de opções disponíveis, consulte s3 ls na Referência de comandos da AWS CLI.

O exemplo a seguir lista todos os seus buckets do Amazon S3.

$ aws s3 ls
2018-12-11 17:08:50 amzn-s3-demo-bucket1
2018-12-14 14:55:44 amzn-s3-demo-bucket2

O comando a seguir lista todos os objetos e prefixos em um bucket. Neste exemplo de saída, o prefixo example/ tem um arquivo chamado MyFile1.txt.

$ aws s3 ls s3://amzn-s3-demo-bucket
                           PRE example/
2018-12-04 19:05:48          3 MyFile1.txt

Você pode filtrar a saída para um prefixo específico, incluindo-o no comando. O comando a seguir relaciona os objetos em bucket-name/example (ou seja, objetos em bucket-name filtrados pelo prefixo example/).

$ aws s3 ls s3://amzn-s3-demo-bucket/example/
2018-12-06 18:59:32          3 MyFile1.txt

Para exibir somente os buckets e objetos em uma região específica, use as opções --region

$ aws s3 ls --region us-east-2
2018-12-06 18:59:32          3 MyFile1.txt

Se tiver uma lista extensa de buckets e objetos, você poderá paginar os resultados usando as opções --max-items ou --page-size. A opção --max-items limita o total de buckets e objetos retornados em uma chamada e a opção --page-size limita quantos deles são listados em uma página.

$ aws s3 ls --max-items 100 --page-size 10

Consulte mais informações sobre paginação em Como usar o parâmetro --page-size e Como usar o parâmetro --max-items.

Excluir buckets

Para excluir um bucket, use o comando s3 rb.

Sintaxe

$ aws s3 rb <target> [--options]

O exemplo a seguir remove o bucket s3://amzn-s3-demo-bucket.

$ aws s3 rb s3://amzn-s3-demo-bucket

Por padrão, o bucket deve estar vazio para a operação ser bem-sucedida. Para remover um bucket que não está vazio, é necessário incluir a opção --force. Se você estiver usando um bucket com versionamento que contém objetos anteriormente excluídos, mas ainda retidos, esse comando não permitirá que você remova o bucket. Você deve primeiro remover todo o conteúdo.

O exemplo de comando a seguir exclui todos os objetos no bucket e, em seguida, exclui o bucket.

$ aws s3 rb s3://amzn-s3-demo-bucket --force

Excluir objetos

Para excluir objetos em um bucket ou seu diretório local, use o comando s3 rm.

Sintaxe

$ aws s3 rm  <target> [--options]

Para ver algumas opções comuns que podem ser usadas com este comando e exemplos, consulte Opções usadas com frequência para comandos s3. Para obter uma lista completa de opções, consulte s3 rm na Referência de comandos da AWS CLI.

O exemplo a seguir exclui filename.txt de s3://amzn-s3-demo-bucket/example.

$ aws s3 rm s3://amzn-s3-demo-bucket/example/filename.txt

O exemplo a seguir exclui todos os objetos de s3://amzn-s3-demo-bucket/example usando a opção --recursive.

$ aws s3 rm s3://amzn-s3-demo-bucket/example --recursive

Mover objetos

Use o comando s3 mv para mover objetos de um bucket ou diretório local. O comando s3 mv copia o objeto ou arquivo de origem para o destino especificado e, em seguida, exclui o objeto ou o arquivo de origem.

Sintaxe

$ aws s3 mv <source> <target> [--options]

Para ver algumas opções comuns que podem ser usadas com este comando e exemplos, consulte Opções usadas com frequência para comandos s3. Para obter uma lista completa de opções disponíveis, consulte s3 mv na Referência de comandos da AWS CLI.

Atenção

Se você estiver usando quaisquer tipos de ARNs de ponto de acesso ou aliases de ponto de acesso em seus URIs de origem ou destino do Amazon S3, você deve tomar cuidado extra para que seus URIs do Amazon S3 de origem e destino sejam resolvidos em diferentes buckets subjacentes. Se os buckets de origem e destino forem iguais, o arquivo ou objeto de origem poderá ser movido para si mesmo, o que pode resultar na exclusão acidental do arquivo ou objeto de origem. Para verificar se os buckets de origem e destino não são iguais, use o parâmetro --validate-same-s3-paths ou defina a variável de ambiente AWS_CLI_S3_MV_VALIDATE_SAME_S3_PATHS como true.

O exemplo a seguir move todos os objetos de s3://amzn-s3-demo-bucket/example para s3://amzn-s3-demo-bucket/.

$ aws s3 mv s3://amzn-s3-demo-bucket/example s3://amzn-s3-demo-bucket/

O exemplo a seguir move um arquivo local do diretório de trabalho atual para o bucket do Amazon S3 com o comando s3 mv.

$ aws s3 mv filename.txt s3://amzn-s3-demo-bucket

O exemplo a seguir move um arquivo do bucket do Amazon S3 para o diretório de trabalho atual, onde ./ especifica o diretório de trabalho atual.

$ aws s3 mv s3://amzn-s3-demo-bucket/filename.txt ./

Copiar objetos

Use o comando s3 cp para copiar objetos de um bucket ou diretório local.

Sintaxe

$ aws s3 cp <source> <target> [--options]

Você pode usar o parâmetro dash para transmitir arquivos para entrada padrão (stdin) ou saída padrão (stdout).

Atenção

Se estiver usando o PowerShell, o shell poderá alterar a codificação de um CRLF ou adicionar um CRLF à entrada ou saída encadeada ou à saída redirecionada.

O comando s3 cp usa a sintaxe a seguir para fazer upload de um fluxo de arquivos do stdin para um bucket especificado.

Sintaxe

$ aws s3 cp - <target> [--options]

O comando s3 cp usa a sintaxe a seguir para baixar um fluxo de arquivos do Amazon S3 para stdout.

Sintaxe

$ aws s3 cp <target> [--options] -

Para ver algumas opções comuns que podem ser usadas com este comando e exemplos, consulte Opções usadas com frequência para comandos s3. Para obter a lista completa de opções, consulte s3 cp na Referência de comandos da AWS CLI.

O exemplo a seguir copia todos os objetos de s3://amzn-s3-demo-bucket/example para s3://amzn-s3-demo-bucket/.

$ aws s3 cp s3://amzn-s3-demo-bucket/example s3://amzn-s3-demo-bucket/

O exemplo a seguir copia um arquivo local do diretório de trabalho atual para o bucket do Amazon S3 com o comando s3 cp.

$ aws s3 cp filename.txt s3://amzn-s3-demo-bucket

O exemplo a seguir copia um arquivo do bucket do Amazon S3 para o diretório de trabalho atual, onde ./ especifica o diretório de trabalho atual.

$ aws s3 cp s3://amzn-s3-demo-bucket/filename.txt ./

O exemplo a seguir usa echo para transmitir o texto “hello world” para o arquivo s3://bucket-name/filename.txt.

$ echo "hello world" | aws s3 cp - s3://amzn-s3-demo-bucket/filename.txt

O exemplo a seguir transmite o arquivo s3://amzn-s3-demo-bucket/filename.txt para stdout e imprime o conteúdo no console.

$ aws s3 cp s3://amzn-s3-demo-bucket/filename.txt -
hello world

O exemplo a seguir transmite o conteúdo de s3://bucket-name/pre parastdout, usa o comando bzip2 para comprimir os arquivos e faz upload do novo arquivo compactado chamado key.bz2 para s3://bucket-name.

$ aws s3 cp s3://amzn-s3-demo-bucket/pre - | bzip2 --best | aws s3 cp - s3://amzn-s3-demo-bucket/key.bz2

Sincronizar objetos

O comando s3 sync sincroniza o conteúdo de um bucket e um diretório ou o conteúdo de dois buckets. Normalmente, s3 sync copia arquivos que estão faltando ou desatualizadas ou objetos entre a origem e o destino. No entanto, você também pode fornecer a opção --delete para remover arquivos ou objetos do destino que não estão presentes na origem.

Sintaxe

$ aws s3 sync <source> <target> [--options]

Para ver algumas opções comuns que podem ser usadas com este comando e exemplos, consulte Opções usadas com frequência para comandos s3. Para obter uma lista completa de opções, consulte s3 sync na Referência de comandos da AWS CLI.

O exemplo a seguir sincroniza o conteúdo de um prefixo do Amazon S3 chamado path no bucket chamado amzn-s3-demo-bucket com o diretório de trabalho atual.

s3 sync atualiza todos os arquivos que têm tamanho ou hora de modificação diferentes dos arquivos com o mesmo nome no destino. A saída exibe operações específicas executadas durante a sincronização. Observe que a operação sincroniza recursivamente o subdiretório MySubdirectory e seu conteúdo com s3://amzn-s3-demo-bucket/path/MySubdirectory.

$ aws s3 sync . s3://amzn-s3-demo-bucket/path
upload: MySubdirectory\MyFile3.txt to s3://amzn-s3-demo-bucket/path/MySubdirectory/MyFile3.txt
upload: MyFile2.txt to s3://amzn-s3-demo-bucket/path/MyFile2.txt
upload: MyFile1.txt to s3://amzn-s3-demo-bucket/path/MyFile1.txt

O exemplo a seguir, uma extensão do exemplo anterior, mostra como usar a opção --delete.

// Delete local file
$ rm ./MyFile1.txt

// Attempt sync without --delete option - nothing happens
$ aws s3 sync . s3://amzn-s3-demo-bucket/path

// Sync with deletion - object is deleted from bucket
$ aws s3 sync . s3://amzn-s3-demo-bucket/path --delete
delete: s3://amzn-s3-demo-bucket/path/MyFile1.txt

// Delete object from bucket
$ aws s3 rm s3://amzn-s3-demo-bucket/path/MySubdirectory/MyFile3.txt
delete: s3://amzn-s3-demo-bucket/path/MySubdirectory/MyFile3.txt

// Sync with deletion - local file is deleted
$ aws s3 sync s3://amzn-s3-demo-bucket/path . --delete
delete: MySubdirectory\MyFile3.txt

// Sync with Infrequent Access storage class
$ aws s3 sync . s3://amzn-s3-demo-bucket/path --storage-class STANDARD_IA

Quando a opção --delete é usada, as opções --exclude e --include podem filtrar arquivos ou objetos a serem excluídos durante uma operação s3 sync. Nesse caso, a sequência de parâmetro deve especificar os arquivos a serem excluídos ou incluídos, a exclusão no contexto do diretório de destino ou bucket. Por exemplo:

Assume local directory and s3://amzn-s3-demo-bucket/path currently in sync and each contains 3 files:
MyFile1.txt
MyFile2.rtf
MyFile88.txt
'''

// Sync with delete, excluding files that match a pattern. MyFile88.txt is deleted, while remote MyFile1.txt is not.
$ aws s3 sync . s3://amzn-s3-demo-bucket/path --delete --exclude "path/MyFile?.txt"
delete: s3://amzn-s3-demo-bucket/path/MyFile88.txt
'''

// Sync with delete, excluding MyFile2.rtf - local file is NOT deleted
$ aws s3 sync s3://amzn-s3-demo-bucket/path . --delete --exclude "./MyFile2.rtf"
download: s3://amzn-s3-demo-bucket/path/MyFile1.txt to MyFile1.txt
'''

// Sync with delete, local copy of MyFile2.rtf is deleted
$ aws s3 sync s3://amzn-s3-demo-bucket/path . --delete
delete: MyFile2.rtf

Opções usadas com frequência para comandos s3

As opções a seguir são usadas frequentemente para os comandos descritos neste tópico. Para obter uma lista completa de opções que você pode usar em um comando, consulte o comando específico no AWS CLI versão 2.

acl

s3 sync e s3 cp podem usar a opção --acl. Isso permite definir as permissões de acesso para arquivos copiados para o Amazon S3. A opção --acl aceita os valores private, public-reade public-read-write. Para obter mais informações, consulte ACL pré-configurada no Guia do usuário do Amazon S3.

$ aws s3 sync . s3://amzn-s3-demo-bucket/path --acl public-read
exclude

Ao usar o comando s3 cp, s3 mv, s3 sync ou s3 rm, você pode filtrar os resultados usando a opção --exclude ou --include. A opção --exclude define regras para excluir apenas objetos do comando, e as opções se aplicam na ordem especificada. Isso é mostrado no exemplo a seguir.

Local directory contains 3 files:
MyFile1.txt
MyFile2.rtf
MyFile88.txt

// Exclude all .txt files, resulting in only MyFile2.rtf being copied
$ aws s3 cp . s3://amzn-s3-demo-bucket/path --exclude "*.txt"

// Exclude all .txt files but include all files with the "MyFile*.txt" format, resulting in, MyFile1.txt, MyFile2.rtf, MyFile88.txt being copied
$ aws s3 cp . s3://amzn-s3-demo-bucket/path --exclude "*.txt" --include "MyFile*.txt"

// Exclude all .txt files, but include all files with the "MyFile*.txt" format, but exclude all files with the "MyFile?.txt" format resulting in, MyFile2.rtf and MyFile88.txt being copied
$ aws s3 cp . s3://amzn-s3-demo-bucket/path --exclude "*.txt" --include "MyFile*.txt" --exclude "MyFile?.txt"
include

Ao usar o comando s3 cp, s3 mv, s3 sync ou s3 rm, você pode filtrar os resultados usando a opção --exclude ou --include. A opção --include define regras para incluir apenas objetos especificados para o comando, e as opções se aplicam na ordem especificada. Isso é mostrado no exemplo a seguir.

Local directory contains 3 files:
MyFile1.txt
MyFile2.rtf
MyFile88.txt

// Include all .txt files, resulting in MyFile1.txt and MyFile88.txt being copied
$ aws s3 cp . s3://amzn-s3-demo-bucket/path --include "*.txt"

// Include all .txt files but exclude all files with the "MyFile*.txt" format, resulting in no files being copied
$ aws s3 cp . s3://amzn-s3-demo-bucket/path --include "*.txt" --exclude "MyFile*.txt"

// Include all .txt files, but exclude all files with the "MyFile*.txt" format, but include all files with the "MyFile?.txt" format resulting in MyFile1.txt being copied

$ aws s3 cp . s3://amzn-s3-demo-bucket/path --include "*.txt" --exclude "MyFile*.txt" --include "MyFile?.txt"
grant (conceder)

Os comandos s3 cp, s3 mv e s3 sync incluem uma opção --grants que pode ser usada para conceder permissões referentes a esse objeto para usuários ou grupos específicos. Defina a opção --grants como uma lista de permissões usando a sintaxe a seguir. Substitua Permission, Grantee_Type e Grantee_ID pelos seus próprios valores.

Sintaxe

--grants Permission=Grantee_Type=Grantee_ID
         [Permission=Grantee_Type=Grantee_ID ...]

Cada valor contém os seguintes elementos:

  • Permission (Permissão): especifica as permissões concedidas. Pode ser definida como read, readacl, writeacl ou full.

  • Grantee_Type (Tipo de favorecido): especifica como identificar o favorecido. Pode ser definido como uri, emailaddress ou id.

  • Grantee_ID – Especifica o favorecido com base em Grantee_Type.

    • uri: o URI do grupo. Para obter mais informações, consulte Quem é o favorecido?

    • emailaddress - O endereço de e-mail da conta.

    • id - O ID canônico da conta

Para obter mais informações sobre controle de acesso do Amazon S3, consulte Controle de acesso.

O exemplo a seguir copia um objeto em um bucket. Ele concede permissões read sobre o objeto a todos os usuários e permissões full (read, readacl e writeacl) à conta associada a user@example.com. 

$ aws s3 cp file.txt s3://amzn-s3-demo-bucket/ --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers full=emailaddress=user@example.com

Também será possível especificar uma classe de armazenamento não padrão (REDUCED_REDUNDANCY ou STANDARD_IA) para objetos cujo upload você fizer no Amazon S3. Para fazer isso, use a opção --storage-class.

$ aws s3 cp file.txt s3://amzn-s3-demo-bucket/ --storage-class REDUCED_REDUNDANCY
recursive

Quando você usa essa opção, o comando é executado em todos os arquivos ou objetos sob o diretório ou prefixo especificado. O exemplo a seguir exclui s3://amzn-s3-demo-bucket/path e todo o seu conteúdo.

$ aws s3 rm s3://amzn-s3-demo-bucket/path --recursive

Recursos

Referência da AWS CLI:

Referência do serviço: