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 de 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 do 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 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 oferece suporte ao processamento paralelo.

Processamento de caracteres curinga

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

Processamento de buckets de namespace hierárquicos

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

Suporte para cópia de arquivos local para local

O gcloud storage foi projetado exclusivamente para interagir com o Cloud Storage e não é compatível com a 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. Mudanças pequenas, como o formato de registro, podem não afetar você, mas diferenças mais significativas nas mensagens de erro e nas listas 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 gcloud

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

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í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 Cloud de Confiance são reconhecidas como objetos marcadores de posição de 0 byte. O gcloud storage cp pode ser usado para copiar pastas simuladas, mas o gsutil cp não.

Ao processar erros, o 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, gcloud storage cp cria 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

O gsutil hash usa flags aditivas para incluir hashes específicos, como -c ou -m. O 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 identificadores 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 de um 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 informações detalhadas como saída, os seguintes comportamentos se aplicam:

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

gcloud storage sempre gera datas e horas em UTC.

O gcloud storage retorna 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 lugar 
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 todas as chaves de criptografia fornecidas pelo cliente (CSEK) ou gerenciadas pelo cliente (CMEK) do objeto. Em seguida, o objeto é criptografado com a chave padrão do KMS do bucket ou com a criptografia gerenciada pelo S3NS.

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 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 transmitem 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 a hora da última modificação forem iguais entre a origem e o 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 e a data da última modificação de um arquivo. No entanto, se os tamanhos dos objetos forem iguais, mas as datas de modificação forem diferentes ou estiverem ausentes, ele vai realizar automaticamente uma comparação de somas de verificação.

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

O 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. O 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 recebe 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 a espaçamento inconsistente. Scripts criados para analisar a saída de gsutil stat podem precisar de 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 gsutil do GitHub.