Transição do gsutil para o gcloud storage

A CLI do Google Cloud é a ferramenta de linha de comando recomendada para interagir com o Cloud Storage. Nesta página, você vai aprender a fazer a transição de gsutil para os comandos gcloud storage da CLI gcloud. Para isso, vamos descrever as principais diferenças e os mapeamentos de comandos entre as duas ferramentas. Se você tiver scripts que usam gsutil, use as informações nesta página para atualizar seus scripts com os comandos gcloud storage comparáveis.

Para saber como começar a usar a CLI gcloud, consulte Instalar a Google Cloud CLI.

Para uma descrição detalhada dos comandos gcloud storage, consulte a documentação de referência de gcloud storage.

Diferenças de comportamento

As seções a seguir descrevem as diferenças comportamentais entre o gsutil e o gcloud storage.

Invocações paralelas

O gcloud storage não é compatível com invocações paralelas usando vários terminais na mesma máquina.

Processamento paralelo

O gcloud storage é compatível com o processamento paralelo.

Processamento de caracteres curinga

gcloud storage simplifica vários asteriscos. Se você usar três ou mais asteriscos em uma linha (***), eles serão tratados como um único asterisco (*).

Processamento de buckets de namespace hierárquicos

gcloud storage pode ser usado para criar e gerenciar buckets com o namespace hierárquico ativado.

Suporte para cópia de arquivos de local para local

A gcloud storage foi projetada exclusivamente para interagir com o Cloud Storage e não é compatível com a cópia de arquivos de local para local. Para mover dados usando o gcloud storage, pelo menos um argumento (origem ou destino) precisa ser um URI de recurso do Cloud Storage. Por exemplo: gs://my-bucket.

Formatação de saída

Os comandos gcloud storage e gsutil formatam a saída de maneira diferente. Embora mudanças menores, como o formato de registro, possam não afetar você, diferenças mais significativas em mensagens de erro e listagens de dados podem corromper scripts automatizados.

Se você tiver scripts que dependem da análise da resposta ao comando gsutil, revise e atualize-os para o formato gcloud storage antes de fazer a transição.

Comandos equivalentes da gcloud

Todos os comandos gsutil atuais têm comandos equivalentes em gcloud storage, com algumas exceções. Para ver uma lista completa dos comandos gcloud storage, acesse a documentação de referência ou execute gcloud storage --help. A tabela a seguir descreve brevemente as mudanças nos comandos gsutil mais usados.

Operação Comando gsutil Comando gcloud storage
Gerenciar listas de controle de acesso (ACLs) 
gsutil acl get
gsutil acl set
gsutil acl ch

gcloud storage RESOURCE describe --format="multi(acl:format=json)"
gcloud storage RESOURCE update --acl-file=ACL_FILE_PATH
gcloud storage RESOURCE update --add-acl-grant=GRANT
gcloud storage RESOURCE update --remove-acl-grant=GRANT
Operação Comando gsutil Comando gcloud storage
Concatenar objetos e exibir o conteúdo deles 
gsutil cat
 
gcloud storage cat
Operação Comando gsutil Comando gcloud storage
Concatenar objetos combinando-os em um novo objeto 
gsutil compose
 
gcloud storage objects compose
Observações
Para aplicar condições prévias em gcloud storage objects compose, use flags específicas, como --if-generation-match ou --if-metageneration-match.
Operação Comando gsutil Comando gcloud storage
Copiar objetos e outros recursos 
gsutil cp
 
gcloud storage cp
Observações

As pastas simuladas criadas usando o console do Google Cloud são reconhecidas como objetos de marcador de posição de 0 byte. gcloud storage cp pode ser usado para copiar pastas simuladas, mas gsutil cp não.

Ao processar erros, gcloud storage cp tenta copiar todos os recursos, mesmo que um deles seja inválido ou não exista. O gsutil cp pode interromper toda a operação assim que encontrar um recurso inválido.

Ao fazer o download de um objeto, o gcloud storage cp cria todos os diretórios locais ausentes que são especificados no caminho de destino. gsutil cp falhará se o diretório de destino não existir.
Operação Comando gsutil Comando gcloud storage
Mostrar o espaço total em disco usado por objetos 
gsutil du
 
gcloud storage du
Operação Comando gsutil Comando gcloud storage
Calcular hashes de arquivos 
gsutil hash
 
gcloud storage hash
Observações

gsutil hash usa flags aditivas para incluir hashes específicos, como -c ou -m. gcloud storage hash usa flags de subtração para excluir hashes, como --skip-md5 ou --skip-crc32c.
Operação Comando gsutil Comando gcloud storage
Gerenciar rótulos de bucket 
gsutil label get
gsutil label set
gsutil label ch

gcloud storage buckets describe
gcloud storage buckets update
gcloud storage buckets update
Observações

A combinação de adicionar, atualizar e remover rótulos em um único comando gsutil label ch pode se comportar de maneira diferente das operações equivalentes usando gcloud storage buckets update. Os scripts que dependem do comportamento específico de leitura-modificação-gravação de gsutil precisam ser testados com cuidado após a transição para gcloud storage.
Operação Comando gsutil Comando gcloud storage
Listar buckets, objetos e pastas 
gsutil ls
 
gcloud storage ls
Observações

Quando um caractere curinga é usado para listar objetos em um projeto, gsutil ls retorna uma lista simples de objetos, enquanto gcloud storage ls retorna objetos agrupados por nome de bucket.

Ao usar gcloud storage ls -L para retornar listagens detalhadas como saída, os seguintes comportamentos se aplicam:

  • Os rótulos de cada metadado (também conhecido como "chave") têm a primeira letra de cada palavra em maiúscula.
  • Se um metadado de um objeto não tiver um valor, gcloud storage vai omitir essa linha da saída.

gcloud storage sempre gera datas e horas em UTC.

gcloud storage retorna todas as mensagens de erro no final da saída do comando.
Operação Comando gsutil Comando gcloud storage
Mover e renomear objetos ou diretórios 
gsutil mv
 
gcloud storage mv
Operação Comando gsutil Comando gcloud storage
Reescrever objetos no local 
gsutil rewrite
 
gcloud storage objects update
Observações

Se um encryption_key estiver definido no arquivo de configuração do boto, o gsutil rewrite -k vai aplicar a chave aos objetos. Se encryption_key não estiver definido, o equivalente de gsutil rewrite -k será gcloud storage objects update --clear-encryption-key. Isso remove do objeto todas as chaves de criptografia fornecidas pelo cliente (CSEK) ou gerenciadas pelo cliente (CMEK). Em seguida, o objeto é criptografado com a chave do KMS padrão do bucket ou com a criptografia gerenciada pelo Google.

gsutil rewrite inclui lógica para pular a regravação de um objeto se a transformação solicitada não mudar o estado dele (por exemplo, se o objeto já estiver em uma classe de armazenamento de destino). gcloud storage objects update pode não realizar as mesmas verificações, o que pode levar a operações desnecessárias.
Operação Comando gsutil Comando gcloud storage
Remover objetos ou buckets 
gsutil rm
 
gcloud storage rm
Observações

Os aliases del, delete e remove de gsutil não são compatíveis.

Há um problema conhecido em que gsutil e gcloud storage se comportam de maneira diferente quando as flags -l e -r são usadas juntas. Os scripts que canalizam uma lista de diretórios a serem excluídos de forma recursiva precisam ser testados minuciosamente antes da transição do uso de gsutil para gcloud storage.
Operação Comando gsutil Comando gcloud storage
Sincronizar o conteúdo de dois buckets ou diretórios 
gsutil rsync
 
gcloud storage rsync
Observações

Por padrão, o gsutil rsync considera um objeto inalterado se o tamanho e o horário da última modificação forem iguais na origem e no destino. Ele só realiza uma comparação de checksum mais completa se um objeto não tiver o horário de modificação ou se você forçar manualmente com a flag -c. O gcloud storage rsync também começa verificando o tamanho de um arquivo e o horário da última modificação. No entanto, se os tamanhos dos objetos forem iguais, mas os horários de modificação forem diferentes ou estiverem ausentes, ele vai realizar automaticamente uma comparação de checksum.

O gcloud storage rsync realiza operações em paralelo por padrão para melhorar o desempenho. gsutil rsync é executado sequencialmente, a menos que a flag -m de nível superior seja usada.

gsutil rsync segue links simbólicos por padrão. O gcloud storage rsync os ignora por padrão, a menos que a flag --no-ignore-symlinks seja usada.
Operação Comando gsutil Comando gcloud storage
Definir metadados em objetos enviados 
gsutil setmeta
 
gcloud storage objects update
Observações

O gsutil setmeta usa uma única flag -h repetível para especificar quais metadados definir ou remover. gcloud storage objects update usa flags distintas para cada campo de metadados (por exemplo: --content-type, --clear-cache-control ou --update-custom-metadata).

Em gsutil setmeta, a flag -h é usada para definir o nome completo do cabeçalho (por exemplo: -h "x-goog-meta-icecreamflavor:vanilla"). Em gcloud storage objects update, a flag --update-custom-metadata é usada e usa pares de chave-valor (por exemplo: --update-custom-metadata=icecreamflavor=vanilla). Para remover um campo de metadados personalizado, gsutil setmeta usa -h "x-goog-meta-icecreamflavor", enquanto gcloud storage objects update usa --remove-custom-metadata=icecreamflavor.
Operação Comando gsutil Comando gcloud storage
Mostrar status do objeto 
gsutil stat
 
gcloud storage objects list --stat --fetch-encrypted-object-hashes
Observações

O formato de saída de gcloud storage objects list --stat é diferente do formato de saída de gsutil stat, com problemas conhecidos relacionados ao espaçamento inconsistente. Os scripts que foram escritos para analisar a saída de gsutil stat podem exigir ajustes para processar o formato de saída de gcloud storage objects list --stat.

A seguir

Para mais detalhes sobre mapeamentos de comandos e flags, consulte a Referência de migração no repositório do GitHub gsutil.