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
aws s3
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.
Tópicos
Pré-requisitos
Para executar os comandos s3
, você precisa:
Instale e configure a AWS CLI. Para ter mais informações, consulte Instalar ou atualizar a versão mais recente da AWS CLI e Autenticação e credenciais de acesso para a AWS CLI.
-
O perfil utilizado deve ter permissões que garantem as operações da AWS realizadas pelos exemplos.
-
Entenda estes termos do Amazon S3:
-
Bucket: uma pasta de nível superior do Amazon S3.
-
Prefixo: uma pasta do Amazon S3 em um bucket.
-
Objeto: qualquer item hospedado em um bucket do Amazon S3.
-
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
emetadata
. -
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
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
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
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
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
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
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
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
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
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
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
es3 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 valoresprivate
,public-read
epublic-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
ous3 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
ous3 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
es3 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. SubstituaPermission
,Grantee_Type
eGrantee_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 comoread
,readacl
,writeacl
oufull
. -
Grantee_Type
(Tipo de favorecido): especifica como identificar o favorecido. Pode ser definido comouri
,emailaddress
ouid
. -
Grantee_ID
– Especifica o favorecido com base emGrantee_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õesfull
(read
,readacl
ewriteacl
) à conta associada auser@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
ouSTANDARD_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:
-
Como trabalhar com buckets do Amazon S3 no Guia do desenvolvedor do Amazon S3
-
Como trabalhar com objetos do Amazon S3 no Guia do usuário do Amazon S3
-
Para listar chaves hierarquicamente usando um prefixo e delimitador no Guia do usuário do Amazon S3
-
Anular carregamentos fracionados para um bucket do S3 usando o AWS SDK for .NET (nível baixo) no Guia do usuário do Amazon S3