Ferramenta gsutil

O gsutil é um aplicativo em Python que permite acessar o Cloud Storage da linha de comando. É possível usar o gsutil para executar uma ampla gama de tarefas de gerenciamento de bucket e de objeto, incluindo:

  • criar e excluir buckets;
  • fazer upload, download e exclusão de objetos;
  • listar buckets e objetos;
  • mover, copiar e renomear objetos;
  • editar ACLs de objetos e buckets.

A gsutil executa todas as operações, incluindo uploads e downloads, usando HTTPS e TLS (Transport Layer Security).

Você precisa usar a gsutil?

Geralmente, é preciso usar comandos gcloud storage em vez de gsutil:

  • A ferramenta gsutil é uma CLI legada do Cloud Storage com manutenção mínima.

  • A ferramenta gsutil não é compatível com os recursos mais recentes do Cloud Storage, como a exclusão reversível e as pastas gerenciadas.

  • Os comandos gcloud storage exigem menos otimização manual para atingir as taxas de upload e download mais rápidas.

Como migrar para a CLI gcloud

Se você é um usuário do gsutil que quer migrar para a CLI gcloud, primeiro deve verificar se está usando uma versão independente do gsutil executando o seguinte comando:

gsutil version -l

  • Quando o resultado do comando inclui using cloud sdk: False, isso significa que você está usando uma versão independente do gsutil. Para migrar para a CLI gcloud, acesse Como instalar a CLI gcloud.

  • Quando o resultado do comando inclui using cloud sdk: True, isso significa que você já tem a CLI gcloud instalada.

Depois que a CLI gcloud for instalada, será possível usar comandos gcloud storage da mesma forma que comandos gsutil. Estes recursos podem ajudar você a começar:

Sintaxe para acessar recursos

gsutil usa o prefixo gs://para indicar um recurso no Cloud Storage.

gs://BUCKET_NAME/OBJECT_NAME

Além de especificar recursos exatos, o gsutil é compatível com o uso de curingas nos seus comandos.

Como acessar uma lista de arquivos

Para operações que envolvem um grande número de arquivos, é possível transmitir uma lista de arquivos de origem para gsutil usando a flag -I. Isso informa ao gsutil para ler a lista de arquivos ou URLs de objetos do stdin em vez dos argumentos de linha de comando.

A entrada precisa ser uma lista de caminhos de arquivos locais ou URLs de objetos do Cloud Storage, com um caminho por linha. Por exemplo, é possível criar um arquivo chamado example_file_list.txt que contenha os seguintes caminhos:

gs://example-source-bucket/data-01.csv
gs://example-source-bucket/images/logo.png
/local/logs/error_log_20251226.txt

Os comandos de exemplo a seguir leem os caminhos de arquivo de example_file_list.txt e os copiam para um bucket de destino chamado gs://example-destination-bucket:

cat example_file_list.txt | gsutil -m cp -I gs://example-destination-bucket/

Também é possível gerar a lista de caminhos em tempo real e transmiti-la diretamente para gsutil. Por exemplo, os comandos a seguir fazem o upload de todos os arquivos JPG encontrados no diretório atual e os copiam para gs://example-destination-bucket:

find . -name "*.jpg" | gsutil -m cp -I gs://example-destination-bucket

Ajuda integrada

O gsutil contém ajuda integrada completa sobre todos os comandos, além de diversos tópicos que você pode listar e conferir com o comando gsutil help.

Para informações sobre um comando ou tópico específico, use gsutil help seguido pelo nome do tópico ou comando pretendido. Por exemplo, gsutil help cp e gsutil help options são páginas de ajuda de comando e de tópico, respectivamente.

Para informações sobre a instalação do gsutil, use o comando gsutil version:

gsutil version -l

Estatísticas de uso

Durante o processo de instalação, é possível ativar o rastreamento das estatísticas de uso, o que ajuda a melhorar a ferramenta gsutil. Se você decidir desativá-las, consulte Estatísticas de uso.

Sobre o gsutil

O gsutil é um projeto de código aberto. Para fazer o download da versão do desenvolvedor do gsutil ou se voluntariar para ajudar a desenvolvê-lo, acesse o projeto do gsutil (em inglês) no GitHub.

Limitações

  • Ao usar a gsutil com o Windows, os comandos que usam a flag global -m não podem ser cancelados usando Ctrl-C.

A seguir