Transição do gsutil para o gcloud storage

gcloud storage (disponibilidade geral) é a ferramenta de linha de comandos recomendada para interagir com o Cloud Storage. Esta página ajuda a fazer a transição de gsutil para gcloud storage, descrevendo as principais diferenças e mapeamentos de comandos entre as duas ferramentas. Para uma descrição detalhada da ferramenta gcloud storage, consulte a gcloud storagedocumentação de referência.

Para saber como instalar e começar a usar a CLI do Google Cloud, consulte o artigo Instale a CLI do Google Cloud.

Diferenças comportamentais

As secções seguintes descrevem as diferenças comportamentais entre o gsutil e o gcloud storage.

Invocações paralelas

gcloud storage não suporta a execução de várias instâncias da CLI a partir de diferentes terminais em simultâneo.

Processamento paralelo

O gcloud storage suporta o processamento em paralelo.

Processamento de carateres universais

gcloud storage simplifica vários asteriscos. Se usar três ou mais asteriscos seguidos (***), o sistema trata-os como um único asterisco (*).

Processamento de contentores de espaço de nomes hierárquicos

gcloud storage pode ser usado para criar e gerir contentores com o espaço de nomes hierárquico ativado.

Formatação da saída

Os comandos gcloud storage e gsutil formatam a respetiva saída de forma diferente. Embora as alterações menores, como o formato de registo, possam não afetar a sua conta, as diferenças mais significativas nas mensagens de erro e nas fichas de dados podem interromper os scripts automatizados.

Se tiver scripts que dependam da análise da saída do comando gsutil, deve revê-los e atualizá-los para o formato gcloud storage antes de os transitar.

Equivalentes de comandos gcloud

Todos os comandos gsutil existentes têm comandos equivalentes em gcloud storage, com algumas exceções. Pode consultar uma lista completa dos comandos gcloud storagevisitando a documentação de referência ou executando gcloud storage --help. A tabela seguinte descreve resumidamente as alterações dos comandos populares do gsutil.

Operação comando gsutil comando gcloud storage
Faça a gestão das listas de controlo de acesso (LCAs) 
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
Concatene objetos e apresente o conteúdo do objeto 
gsutil cat
 
gcloud storage cat
Operação comando gsutil comando gcloud storage
Concatene objetos combinando-os num novo objeto 
gsutil compose
 
gcloud storage objects compose
Notas
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
Copie objetos e outros recursos 
gsutil cp
 
gcloud storage cp
Notas

As pastas simuladas criadas através da consola são reconhecidas como objetos de marcador de posição de 0 bytes. Google Cloud gcloud storage cp pode ser usado para copiar pastas simuladas, enquanto gsutil cp não pode.

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

Quando transfere um objeto, o gcloud storage cp cria todos os diretórios locais em falta especificados no caminho de destino. gsutil cp falha se o diretório de destino não existir.
Operação comando gsutil comando gcloud storage
Apresentar o espaço em disco total usado por objetos 
gsutil du
 
gcloud storage du
Operação comando gsutil comando gcloud storage
Calcule hashes de ficheiros 
gsutil hash
 
gcloud storage hash
Notas

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
Faça a gestão das etiquetas de contentores 
gsutil label get
gsutil label set
gsutil label ch

gcloud storage buckets describe
gcloud storage buckets update
gcloud storage buckets update
Notas

A combinação de adicionar, atualizar e remover etiquetas num único comando gsutil label ch pode comportar-se de forma diferente das operações equivalentes com gcloud storage buckets update. Os scripts que dependem de um comportamento de leitura-modificação-escrita específico de gsutil devem ser testados cuidadosamente após a transição para gcloud storage.
Operação comando gsutil comando gcloud storage
Liste contentores, objetos e pastas 
gsutil ls
 
gcloud storage ls
Notas

Quando um caráter universal é usado para listar objetos num projeto, gsutil ls devolve uma lista simples de objetos, enquanto gcloud storage ls devolve objetos agrupados por nome do contentor.

Quando usa gcloud storage ls -L para devolver fichas detalhadas como resultado, aplicam-se os seguintes comportamentos:

  • As etiquetas de cada parte dos metadados (também conhecidas 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 omite essa linha da saída.

gcloud storage produz sempre datas/horas em UTC.

gcloud storage devolve quaisquer mensagens de erro no final da saída do comando.
Operação comando gsutil comando gcloud storage
Mova e mude o nome de objetos ou diretórios 
gsutil mv
 
gcloud storage mv
Operação comando gsutil comando gcloud storage
Reescreva objetos no lugar 
gsutil rewrite
 
gcloud storage objects update
Notas

Se um encryption_key estiver definido no seu ficheiro de configuração do boto, gsutil rewrite -k aplica a chave aos objetos. Se encryption_key não estiver definido, o equivalente de gsutil rewrite -k é gcloud storage objects update --clear-encryption-key. Isto remove todas as chaves de encriptação fornecidas pelos clientes (CSEK) ou chaves de encriptação geridas pelo cliente (CMEK) do objeto. Em seguida, o objeto é encriptado com a chave KMS predefinida do contentor ou com a encriptação gerida pela Google.

gsutil rewrite inclui lógica para ignorar a reescrita de um objeto se a transformação pedida não alterar o respetivo estado (por exemplo, se o objeto já estiver numa 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
Remova objetos ou contentores 
gsutil rm
 
gcloud storage rm
Notas

Os alias gsutil, del e delete não são suportados.remove

Existe um problema conhecido em que gsutil e gcloud storage têm um comportamento diferente quando as flags -l e -r são usadas em conjunto. Os scripts que transmitem uma lista de diretórios a serem eliminados recursivamente devem ser testados exaustivamente antes da transição da utilização de gsutil para gcloud storage.
Operação comando gsutil comando gcloud storage
Sincronize o conteúdo de dois contentores ou diretórios 
gsutil rsync
 
gcloud storage rsync
Notas

Por predefinição, o gsutil rsync considera um objeto inalterado se o respetivo tamanho e hora da última modificação corresponderem entre a origem e o destino. Só faz uma comparação de soma de verificação mais exaustiva se um objeto não tiver a hora de modificação ou se a forçar manualmente com a flag -c. gcloud storage rsync também começa por verificar o tamanho de um ficheiro e a hora da última modificação. No entanto, se os tamanhos dos objetos corresponderem, mas as horas de modificação forem diferentes ou estiverem em falta, realiza automaticamente uma comparação de soma de verificação.

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

Por predefinição, o gsutil rsync segue links simbólicos. gcloud storage rsync ignora-os por predefinição, a menos que seja usada a flag --no-ignore-symlinks.
Operação comando gsutil comando gcloud storage
Defina metadados em objetos carregados 
gsutil setmeta
 
gcloud storage objects update
Notas

gsutil setmeta usa uma sinalização -h única e repetível para especificar os metadados a 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 em alternativa 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
Apresente o estado do objeto 
gsutil stat
 
gcloud storage objects list --stat --fetch-encrypted-object-hashes
Notas

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