Instale o gsutil

Esta página descreve a instalação e a configuração do gsutil, uma ferramenta que lhe permite aceder ao Cloud Storage a partir da linha de comandos através de HTTPS.

A instalação do gsutil oferece acesso imediato a dados públicos, o que lhe permite ler e escrever conforme permitido. Para interagir com os dados protegidos partilhados consigo, é necessária a autenticação com o serviço Cloud Storage. A ativação da faturação permite-lhe criar e gerir os seus próprios depósitos.

Requisitos de sistema

  • A ferramenta gsutil é executada no Linux/Unix, Mac OS e Windows (XP ou posterior).

  • As versões 5.35 ou posteriores do gsutil requerem o Python 3.9 a 3.13, que pode obter através do gestor de versões do Python ou instalando uma versão adequada.

As instruções seguintes mostram como gerir as versões do Python:

Linux

Pré-requisitos: instale um gestor de versões do Python (pyenv) e instale uma versão adequada do Python.

  1. Defina a versão global do Python:
    • Para definir o Python 3.13 como a versão global: 
      pyenv global 3.13
    • Em alternativa, defina a versão do Python localmente para uma pasta de projeto específica: 
      pyenv local 3.13
  2. Confirme que está a usar a versão correta do Python: 
    python --version

    Deve ver:

    Python 3.13
macOS

Método 1: usar o Homebrew (brew)

Pré-requisitos: instale o Homebrew e instale uma versão adequada do Python através do Homebrew.

  1. Defina uma versão específica do Python como predefinição:
    • Adicione a versão que quer ao seu $PATH. Por exemplo, para usar o Python 3.13: 
      export PATH="/usr/local/opt/python@3.13/bin:$PATH"
    • Para tornar esta alteração permanente, adicione o caminho ao ficheiro de configuração da shell (~/.bash_profile, ~/.zshrc ou ~/.bashrc).
  2. Confirme que está a usar a versão correta do Python: 
    python --version

    Deve ver:

    Python 3.13

Método 2: usar o pyenv

Pré-requisitos: instale o gestor de versões do Python (pyenv) e instale uma versão adequada do Python através do pyenv.

  1. Defina a versão global do Python:
    • Para definir a versão do Python globalmente (para todos os terminais): 
      pyenv global 3.13
    • Em alternativa, defina a versão do Python localmente para uma pasta de projeto específica: 
      pyenv local 3.13
  2. Confirme que está a usar a versão correta do Python: 
    python --version

    Deve ver:

    Python 3.13
Windows

Pré-requisitos: instale o gestor de versões do Python (pyenv-win) e instale uma versão adequada do Python através do pyenv.

  1. Defina a versão global do Python:
    • Para definir o Python 3.13 como a versão global: 
      pyenv global 3.13
    • Em alternativa, defina a versão do Python localmente para uma pasta de projeto específica: 
      pyenv local 3.13
  2. Confirme que está a usar a versão correta do Python: 
    python --version

    Deve ver:

    Python 3.13
  • Se planeia usar objetos compostos, tem de instalar o crcmod compilado. No Windows, esta opção só está disponível para Python de 32 bits. Para mais informações sobre o crcmod, instale o gsutil e consulte o tópico de ajuda através do comando gsutil help crc32c.

Instalar o gsutil

O método de instalação e atualização oficialmente suportado para o gsutil é como parte da CLI Google Cloud.

Antes de começar

A CLI Google Cloud e o gsutil têm dependências da versão do Python que podem causar problemas de compatibilidade. A CLI do Google Cloud requer o Python 3.9 a 3.14, enquanto o gsutil requer o Python 3.9 a 3.13.

Para instalar o gsutil, recomendamos que o instale como parte da CLI Google Cloud. Se optar por instalar o gsutil diretamente, use o Python 3.9 a 3.13 para evitar problemas de compatibilidade.

Instalar o gsutil como parte da CLI Google Cloud

Siga as instruções para o seu sistema operativo para instalar o gsutil como parte da CLI Google Cloud:

Linux
  1. Confirme que tem uma versão suportada do Python. A CLI gcloud requer o Python 3.9 a 3.14. O pacote Linux x86_64 inclui um intérprete Python integrado que é preferido por predefinição. Para informações sobre como escolher e configurar o seu intérprete Python, consulte a gcloud topic startup documentação.
  2. Transfira uma das seguintes opções:
    Plataforma Nome do pacote Tamanho Soma de verificação SHA256
    Linux (64 bits)

    (x86_64)

    		 google-cloud-cli-linux-x86_64.tar.gz 203,0 MB 81320cc3042faadbff2875c8b55c6bdcf6ccd439599c6645c27a5a6f213b4736
    Linux (64 bits)

    (Arm)

    		 google-cloud-cli-linux-arm.tar.gz 57,9 MB 2fced601e0a494e6dcf6dbfb39130aefacabe541d5bcf0a5d53a8c44e71515e9
    Linux (32 bits)

    (x86)

    		 google-cloud-cli-linux-x86.tar.gz 57,9 MB 8fb22634022aa74d23e877279e034e56d4fed4b5883cbfc51b9dd7134a1b96f0

    Para transferir o ficheiro de arquivo do Linux, execute o seguinte comando: 

    curl -O https://storage.s3nsapis.fr/cloud-sdk-release/google-cloud-cli-linux-x86_64.tar.gz

    Consulte a tabela acima e substitua google-cloud-cli-linux-x86_64.tar.gz pelo nome do pacote *.tar.gz que se aplica à sua configuração.

  3. Para extrair o conteúdo do ficheiro para o seu sistema de ficheiros, execute o seguinte comando: 
    tar -xf google-cloud-cli-linux-x86_64.tar.gz
     Para substituir uma instalação existente, elimine o diretório google-cloud-sdk existente e, em seguida, extraia o arquivo para a mesma localização.
  4. Execute o script de instalação a partir da raiz da pasta que extraiu: 
    ./google-cloud-sdk/install.sh
     O script pede-lhe que execute as seguintes ações de configuração. Para aceitar, responda Y quando lhe for pedido. Também pode realizar a instalação de forma não interativa através de flags. Para ver as flags disponíveis, execute o seguinte comando: 
    ./google-cloud-sdk/install.sh --help
  5. Opcional: se atualizou o PATH no passo anterior, abra um novo terminal para que as alterações tenham efeito.
Debian/Ubuntu

Conteúdo da embalagem

A CLI gcloud está disponível no formato de pacote para instalação em sistemas Debian e Ubuntu. Este pacote contém apenas as ferramentas de linhas de comando gcloud, gcloud alpha, gcloud beta, gsutil e bq. Não inclui kubectl nem as extensões do App Engine necessárias para implementar uma aplicação através de comandos gcloud. Se quiser estes componentes, tem de os instalar separadamente.

Antes de começar

Antes de instalar a CLI gcloud, certifique-se de que o seu sistema operativo cumpre os seguintes requisitos:

  • É um lançamento do Ubuntu que não atingiu o fim de vida ou um lançamento estável do Debian que não atingiu o fim de vida.
  • Atualizou recentemente os respetivos pacotes. Para o fazer agora, execute o seguinte comando: 
    sudo apt-get update
  • Tem o apt-transport-https, o ca-certificates, o gnupg e o curl instalados. Para instalar estes pacotes, execute o seguinte comando: 
    sudo apt-get install apt-transport-https ca-certificates gnupg curl

Instalação

  1. Importe a Cloud de Confiance by S3NS chave pública.

    • Para distribuições mais recentes (Debian 9 ou superior, ou Ubuntu 18.04 ou superior), execute o seguinte comando:

      curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
    • Para distribuições mais antigas, execute o seguinte comando: 
      curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key --keyring /usr/share/keyrings/cloud.google.gpg add -

    • Se o comando apt-key da sua distribuição não suportar o argumento --keyring, execute o seguinte comando:

      curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -

    • Se não conseguir obter as atualizações mais recentes devido a uma chave expirada, obtenha o ficheiro de chave apt-get.gpg mais recente.

  2. Adicione o URI de distribuição da CLI gcloud como uma origem de pacotes.
    • Para distribuições mais recentes (Debian 9 ou superior, ou Ubuntu 18.04 ou superior), execute o seguinte comando: 
      echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list

    • Para distribuições mais antigas que não suportam a opção signed-by, execute o seguinte comando:

      echo "deb https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list
  3. Atualize e instale a CLI gcloud: 
    sudo apt-get update && sudo apt-get install google-cloud-cli
     Para opções apt-get adicionais, como desativar comandos ou testes de execução, consulte as páginas de manual apt-get.

    Sugestão do Docker: se instalar a CLI gcloud numa imagem do Docker, use um único passo RUN em alternativa:

    RUN echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | tee -a /etc/apt/sources.list.d/google-cloud-sdk.list && curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg && apt-get update -y && apt-get install google-cloud-cli -y
    Para imagens base mais antigas que não suportam o comando gpg --dearmor: 
    RUN echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | tee -a /etc/apt/sources.list.d/google-cloud-sdk.list && curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | apt-key --keyring /usr/share/keyrings/cloud.google.gpg  add - && apt-get update -y && apt-get install google-cloud-cli -y
  4. Opcional: instale qualquer um dos seguintes componentes adicionais:
    • google-cloud-cli-anthos-auth
    • google-cloud-cli-app-engine-go
    • google-cloud-cli-app-engine-grpc
    • google-cloud-cli-app-engine-java
    • google-cloud-cli-app-engine-python
    • google-cloud-cli-app-engine-python-extras
    • google-cloud-cli-bigtable-emulator
    • google-cloud-cli-cbt
    • google-cloud-cli-cloud-build-local
    • google-cloud-cli-cloud-run-proxy
    • google-cloud-cli-config-connector
    • google-cloud-cli-datastore-emulator
    • google-cloud-cli-firestore-emulator
    • google-cloud-cli-gke-gcloud-auth-plugin
    • google-cloud-cli-kpt
    • google-cloud-cli-kubectl-oidc
    • google-cloud-cli-local-extract
    • google-cloud-cli-minikube
    • google-cloud-cli-nomos
    • google-cloud-cli-pubsub-emulator
    • google-cloud-cli-skaffold
    • google-cloud-cli-spanner-emulator
    • google-cloud-cli-terraform-validator
    • google-cloud-cli-tests
    • kubectl

    Por exemplo, o componente google-cloud-cli-app-engine-java pode ser instalado da seguinte forma: 

    sudo apt-get install google-cloud-cli-app-engine-java
  5. Execute gcloud init para inicializar, autorizar e configurar a CLI gcloud.

Altere para versões anteriores da CLI gcloud

Para reverter para uma versão específica da CLI gcloud, em que VERSION tem o formato 123.0.0, execute o seguinte comando:

sudo apt-get update && sudo apt-get install google-cloud-cli=123.0.0-0

As dez versões mais recentes estão sempre disponíveis no repositório. Para versões anteriores a 371.0.0, o nome do pacote é google-cloud-sdk

Red Hat/Fedora/CentOS

Conteúdo da embalagem

A CLI gcloud está disponível no formato de pacote para instalação em sistemas Red Hat Enterprise Linux 7, 8, 9 e 10; Fedora 41 e 42; e CentOS 7 e 8. Este pacote contém apenas os comandos gcloud, gcloud alpha, gcloud beta, gsutil e bq. Não inclui o kubectl nem as extensões do App Engine necessárias para implementar uma aplicação através de comandos gcloud, que podem ser instaladas separadamente, conforme descrito mais adiante nesta secção.

Instalação

  1. Atualize o DNF com as informações do repositório da CLI gcloud.

    • O seguinte comando de exemplo destina-se a instalações compatíveis com o Red Hat Enterprise Linux 7, 8 ou 9, mas certifique-se de que atualiza as definições conforme necessário para a sua configuração:

      sudo tee -a /etc/yum.repos.d/google-cloud-sdk.repo << EOM
[google-cloud-cli]
name=Google Cloud CLI
baseurl=https://packages.cloud.google.com/yum/repos/cloud-sdk-el9-x86_64
enabled=1
gpgcheck=1
repo_gpgcheck=0
gpgkey=https://packages.cloud.google.com/yum/doc/rpm-package-key.gpg
EOM

    • Para instalações compatíveis com o RHEL 10, use o seguinte comando com o gpgkey atualizado:

      sudo tee -a /etc/yum.repos.d/google-cloud-sdk.repo << EOM
[google-cloud-cli]
name=Google Cloud CLI
baseurl=https://packages.cloud.google.com/yum/repos/cloud-sdk-el10-x86_64
enabled=1
gpgcheck=1
repo_gpgcheck=0
gpgkey=https://packages.cloud.google.com/yum/doc/rpm-package-key-v10.gpg
EOM
  2. Instale libxcrypt-compat.x86_64. 
    sudo dnf install libxcrypt-compat.x86_64
  3. Instale a CLI gcloud: 
    sudo dnf install google-cloud-cli
  4. Opcional: instale qualquer um dos seguintes componentes adicionais:
    • google-cloud-cli-anthos-auth
    • google-cloud-cli-app-engine-go
    • google-cloud-cli-app-engine-grpc
    • google-cloud-cli-app-engine-java
    • google-cloud-cli-app-engine-python
    • google-cloud-cli-app-engine-python-extras
    • google-cloud-cli-bigtable-emulator
    • google-cloud-cli-cbt
    • google-cloud-cli-cloud-build-local
    • google-cloud-cli-cloud-run-proxy
    • google-cloud-cli-config-connector
    • google-cloud-cli-datastore-emulator
    • google-cloud-cli-firestore-emulator
    • google-cloud-cli-gke-gcloud-auth-plugin
    • google-cloud-cli-kpt
    • google-cloud-cli-kubectl-oidc
    • google-cloud-cli-local-extract
    • google-cloud-cli-minikube
    • google-cloud-cli-nomos
    • google-cloud-cli-pubsub-emulator
    • google-cloud-cli-skaffold
    • google-cloud-cli-spanner-emulator
    • google-cloud-cli-terraform-validator
    • google-cloud-cli-tests
    • kubectl

    Por exemplo, para instalar o componente google-cloud-cli-app-engine-java, execute o seguinte comando: 

    sudo dnf install google-cloud-cli-app-engine-java
  5. Execute gcloud init para inicializar, autorizar e configurar a CLI gcloud.

Altere para versões anteriores da CLI gcloud

Para reverter para uma versão específica da CLI gcloud, execute o seguinte comando. Substitua 123.0.0 pela versão que quer instalar: 

sudo dnf downgrade google-cloud-cli-123.0.0

As dez versões mais recentes estão disponíveis no repositório. Para versões anteriores à 371.0.0, use google-cloud-sdk como nome do pacote.

macOS
  1. Confirme que tem uma versão suportada do Python. A CLI gcloud requer o Python 3.9 a 3.14.

    Para verificar a versão do Python, execute python3 -V ou python -V.

    O script de instalação pode instalar o Python por si, se necessário. Isto requer as ferramentas de linha de comandos do Xcode. Para os instalar, execute sudo xcode-select --install. Em alternativa, pode instalar uma versão do Python suportada a partir de python.org.

    Para mais informações sobre a configuração do seu intérprete Python, especialmente se tiver várias versões instaladas, consulte a gcloud topic startupdocumentação.

  2. Transfira uma das seguintes opções:
    Plataforma Pacote Tamanho Soma de verificação SHA256
    macOS de 64 bits

    (x86_64)

    		 google-cloud-cli-darwin-x86_64.tar.gz 58,0 MB 9f4b289e4545d146410e87363489d11ce30c1326eae0930cd77c81a499336682
    macOS de 64 bits

    (ARM64, Apple silicon)

    		 google-cloud-cli-darwin-arm.tar.gz 57,9 MB 20aa219e61d7ac2b4bf78f9080c0fcf2c0b79d48ce47b9833d4087a468d749d9
    macOS de 32 bits

    (x86)

    		 google-cloud-cli-darwin-x86.tar.gz 56,4 MB 979b7f6e4014d41222b8354495d4e89285021c1b69bf07f751aecdf929024422

    Em alternativa, pode transferir o arquivo a partir da linha de comandos. Substitua FILE_NAME pelo nome do pacote da sua plataforma na tabela acima. 

    curl -O https://storage.s3nsapis.fr/cloud-sdk-release/FILE_NAME
  3. Extraia o conteúdo do ficheiro para a localização preferida no seu sistema de ficheiros. Uma prática comum é extraí-lo para o seu diretório inicial.

    No macOS, pode fazê-lo abrindo o ficheiro .tar.gz transferido na sua localização preferida. Em alternativa, na linha de comandos, execute: 

    tar -xf FILE_NAME

    Para substituir uma instalação existente, elimine o diretório google-cloud-sdk existente e, em seguida, extraia o arquivo para a mesma localização.

  4. Execute o script de instalação a partir da raiz da pasta que extraiu: 
    ./google-cloud-sdk/install.sh
     O script pede-lhe que execute as seguintes ações de configuração. Para aceitar, responda Y quando lhe for pedido.
    • Instale o Python 3.13 e os módulos recomendados, se necessário.
    • Adicione a CLI gcloud ao seu PATH e ative a conclusão de comandos.
    • Ative o envio de estatísticas de utilização anónimas para ajudar a melhorar a CLI gcloud.
    Também pode realizar a instalação de forma não interativa através de flags. Para ver as flags disponíveis, execute o seguinte comando: 
    ./google-cloud-sdk/install.sh --help
     Para executar o script de instalação com o modo de leitor de ecrã ativado: 
    ./google-cloud-sdk/install.sh --screen-reader=true
  5. Opcional: se atualizou o PATH no passo anterior, abra um novo terminal para que as alterações tenham efeito.
Windows

A CLI Google Cloud no Windows requer o Windows 8.1 e posterior ou o Windows Server 2012 e posterior.

  1. Transfira o instalador da CLI do Google Cloud.

    Em alternativa, abra um terminal do PowerShell e execute os seguintes comandos do PowerShell: 

    (New-Object Net.WebClient).DownloadFile("https://storage.s3nsapis.fr/cloud-sdk-release/GoogleCloudSDKInstaller.exe", "$env:Temp\GoogleCloudSDKInstaller.exe")

& $env:Temp\GoogleCloudSDKInstaller.exe

  2. Inicie o instalador e siga as instruções. O instalador está assinado pela Google LLC.

    • Se estiver a usar um leitor de ecrã, selecione a caixa de verificação Ativar modo de leitor de ecrã. Esta opção configura o gcloud para usar indicadores de estado em vez de ícones de carregamento Unicode, apresentar o progresso como uma percentagem e simplificar as tabelas. Para mais informações, consulte o guia de funcionalidades de acessibilidade.
    • A CLI gcloud requer o Python. As versões suportadas são o Python 3.9 a 3.14. Por predefinição, a versão do Windows da CLI do Google Cloud é fornecida com o Python 3. Para usar a Google Cloud CLI, o seu sistema operativo tem de conseguir executar uma versão suportada do Python.
    • O instalador instala todas as dependências necessárias, incluindo a versão do Python necessária. Embora a Google Cloud CLI instale e faça a gestão do Python 3 por predefinição, pode usar uma instalação do Python existente, se necessário, desmarcando a opção para instalar o Python integrado. Consulte gcloud topic startup para saber como usar uma instalação do Python existente.
  3. Após a conclusão da instalação, o instalador dá-lhe a opção de criar atalhos no menu Iniciar e no ambiente de trabalho, iniciar a shell da CLI gcloud e configurar a CLI gcloud. Deixe as opções para iniciar a shell e configurar a instalação selecionadas. O instalador inicia uma janela de terminal e executa o comando gcloud init para inicializar, autorizar e configurar a CLI gcloud.
  4. A instalação predefinida não inclui as extensões do App Engine necessárias para implementar uma aplicação através de comandos gcloud. Estes componentes podem ser instalados através do gestor de componentes da CLI gcloud.

Sugestões de resolução de problemas

  • Se a instalação não for bem-sucedida porque o comando find não é reconhecido, certifique-se de que a variável de ambiente PATH está definida para incluir a pasta que contém find. Normalmente, este valor é C:\WINDOWS\system32;.
  • Se desinstalou a CLI gcloud, tem de reiniciar o sistema antes de instalar novamente a CLI gcloud.
  • Se a descompressão falhar, execute o instalador como administrador.

Como parte da instalação do gsutil, tem de definir a variável de ambiente CLOUDSDK_PYTHON para usar a versão correta do Python. Para mais detalhes, consulte o gcloud startup topic.

Faça atualizações com o comando components update: gcloud components update.

Configurar credenciais para aceder a dados protegidos

Para aceder a dados protegidos ou escrever num contentor protegido, tem de configurar credenciais (autenticar). Por exemplo, se outra pessoa tiver criado uma conta do Cloud Storage e carregado dados que só são acessíveis a si ou a outros indivíduos específicos, tem de configurar as suas credenciais para o serviço Cloud Storage para poder aceder a estes dados.

Quando usa o gsutil como parte da CLI Google Cloud, o OAuth2 é usado para autenticar e autorizar o acesso aos seus recursos do Cloud Storage. Para estabelecer acesso, execute o comando gcloud init e siga as instruções fornecidas na linha de comandos, que incluem iniciar sessão na sua conta de utilizador. Tenha em atenção que provavelmente já realizou esta configuração se seguiu os passos de instalação. Se executou gcloud init anteriormente, quando executar o comando novamente, é-lhe perguntado se quer reinicializar a configuração ou criar uma nova. Para mais informações, consulte o artigo Inicialize a CLI Google Cloud.

É tudo. Tem tudo pronto para aceder aos dados protegidos. Para ver uma lista de comandos gsutil, escreva gsutil na linha de comandos.

Resolução de problemas

Se tentar autenticar o gsutil através do comando gcloud init, mas continuar a não conseguir aceder aos objetos ou aos contentores esperados, o seu sistema pode ter a versão autónoma antiga do gsutil e a versão do gsutil incluída na CLI do Google Cloud instaladas. Execute o comando gsutil version -l e verifique o valor de using cloud sdk. Se False, o seu sistema está a usar a versão autónoma do gsutil quando executa comandos. Recomendamos que remova a versão autónoma do gsutil do seu sistema. No entanto, em alternativa, pode fazer a autenticação através do gsutil config -a ou do gsutil config -e.

Autentique com HMAC

Embora o OAuth 2.0 seja a forma recomendada de autenticar o gsutil, também pode usar chaves HMAC para as suas credenciais. Para autenticar com HMAC, use o seguinte comando: 

gsutil config -a

A utilização deste comando orienta-o através de um processo de autenticação no qual lhe é pedido o ID de acesso e o segredo associados à sua chave HMAC.

Quando se autentica com chaves HMAC, deve desativar a transmissão de credenciais a partir da CLI do Google Cloud com o comando: gcloud config set pass_credentials_to_gsutil false.

Ative o mTLS

Também pode ativar o TLS mútuo (mTLS). Quando o mTLS está ativado no seu dispositivo, o dispositivo tenta estabelecer ligação ao ponto final do pedido mTLS para a API JSON. Antes de a ligação ser permitida, o armazenamento na nuvem valida o certificado no seu dispositivo.

A forma mais simples de obter um certificado é através da CLI do Google Cloud. Pode definir um manualmente no ficheiro .boto definindo os seguintes valores em "Credenciais":

  1. use_client_certificate: um indicador que controla se deve ou não usar o mTLS.
  2. cert_provider_command: Um comando de shell que imprime um certificado para stdout para o gsutil ler.