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 gcloud CLI

Se você é um usuário do gsutil que quer migrar para a gcloud CLI, 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 gcloud CLI, acesse Como instalar a gcloud CLI.

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

Depois que a gcloud CLI 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 a 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, você pode 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/

Você também pode gerar a lista de caminhos na hora e transmiti-la diretamente para o gsutil. Por exemplo, os comandos a seguir fazem 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 de 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