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. Esta página ajuda você a fazer a transição do gsutil para os comandos gcloud storage da CLI gcloud, descrevendo as principais diferenças e mapeamentos de comandos entre as duas ferramentas. Para uma descrição detalhada dos comandos gcloud storage, consulte a documentação de referência gcloud storage.

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

Diferenças de comportamento

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

Invocações paralelas

gcloud storage não oferece suporte a invocações paralelas usando vários terminais na mesma máquina.

Processamento paralelo

gcloud storage oferece suporte a 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 à cópia de arquivos local para local

gcloud storage foi projetado exclusivamente para interagir com o Cloud Storage e não oferece suporte à cópia de arquivos local para local. Para mover dados com sucesso usando 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 pequenas mudanças, como o formato de geração de registros, não afetem você, diferenças mais significativas nas mensagens de erro e nas listagens de dados podem interromper 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.

Equivalentes de comandos do gcloud

Todos os comandos gsutil atuais têm comandos equivalentes em gcloud storage, com algumas exceções. Você pode acessar uma lista completa dos gcloud storage comandos na documentação de referência ou executando gcloud storage --help. A tabela a seguir descreve brevemente as mudanças nos comandos gsutil mais conhecidos.

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 mostrar 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 pré-condições em gcloud storage objects compose, use flags específicos, 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

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

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

Ao fazer o download de um objeto, gcloud storage cp cria todos os diretórios locais ausentes especificados no caminho de destino. gsutil cp falha 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 subtrativas para excluir hashes, como --skip-md5 ou --skip-crc32c.
Operação comando gsutil comando gcloud storage
Gerenciar marcadores 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 marcadores 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 do 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 são aplicados:

  • Os marcadores de cada metadado (também conhecidos como "chave") têm a primeira letra de cada palavra em maiúsculas.
  • 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 horários 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 uma encryption_key estiver definida no arquivo de configuração do boto, 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 todas as chaves de criptografia fornecidas pelo cliente (CSEK) ou chaves de criptografia gerenciadas pelo cliente (CMEK) do objeto. O objeto é criptografado com a chave KMS padrão do bucket ou com a criptografia gerenciada. Google

gsutil rewrite inclui lógica para pular a reescrita 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 gsutil del, delete e remove não são aceitos.

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 recursivamente precisam ser testados completamente 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, gsutil rsync considera um objeto inalterado se o tamanho e o horário da última modificação corresponderem entre a origem e o destino. Ele só realiza uma comparação de soma de verificação mais completa se um objeto não tiver o horário de modificação ou se você forçar manualmente com a flag -c. gcloud storage rsync também começa verificando o tamanho e o horário da última modificação de um arquivo. No entanto, se os tamanhos dos objetos corresponderem, mas os horários de modificação forem diferentes ou estiverem ausentes, ele vai realizar automaticamente uma comparação de soma de verificaçã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. 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

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 --update-custom-metadata flag é usada e aceita pares de chave-valor (por exemplo: --update-custom-metadata=icecreamflavor=vanilla). Para remover um campo de metadados personalizados, 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 o 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 comandos e mapeamentos de flags, consulte a referência de migração no repositório do GitHub gsutil.