Nesta página, descrevemos a instalação e a configuração da gsutil, uma ferramenta que permite acessar o Cloud Storage pela linha de comando usando HTTPS.
A instalação do gsutil fornece acesso imediato aos dados públicos, permitindo a leitura e gravação conforme permitido. Para interagir com os dados protegidos compartilhados com você, é necessária a autenticação com o serviço Cloud Storage. Ao ativar o faturamento, você pode criar e gerenciar seus próprios buckets.
Requisitos do sistema
A ferramenta gsutil é executada em Linux/Unix, Mac OS e Windows (XP ou posterior).
As versões 5.32 e mais recentes do gsutil exigem o Python 3.8 a 3.12, que pode ser obtido usando o gerenciador de versões do Python ou instalando uma versão adequada.
As instruções a seguir mostram como gerenciar as versões do Python:
Pré-requisitos: instale um gerenciador de versões do Python (pyenv) e uma versão adequada do Python.
-
Defina a versão global do Python:
-
Para definir o Python 3.12.x como a versão global:
pyenv global 3.12.x
-
Ou defina a versão do Python localmente para uma pasta de projeto específica:
pyenv local 3.12.x
-
Para definir o Python 3.12.x como a versão global:
-
Confirme se a versão correta do Python está sendo usada:
python --version
Você verá:
Python 3.12.x
Método 1: usar o Homebrew (brew)
Pré-requisitos: instale o Homebrew e uma versão adequada do Python usando o Homebrew.
-
Defina uma versão específica do Python como padrão:
-
Adicione a versão que você quer ao
$PATH
. Por exemplo, para usar o Python 3.12:export PATH="/usr/local/opt/python@3.12/bin:$PATH"
-
Para tornar essa mudança permanente, adicione o caminho ao arquivo de configuração do shell
(
~/.bash_profile
,~/.zshrc
ou~/.bashrc
).
-
Adicione a versão que você quer ao
-
Confirme se a versão correta do Python está sendo usada:
python --version
Você verá:
Python 3.12.x
Método 2: usar o pyenv
Pré-requisitos: instale o gerenciador de versões do Python (pyenv) e uma versão adequada do Python usando o pyenv.
-
Defina a versão global do Python:
-
Para definir a versão do Python globalmente (para todos os terminais):
pyenv global 3.12.x
-
Ou defina a versão do Python localmente para uma pasta de projeto específica:
pyenv local 3.12.x
-
Para definir a versão do Python globalmente (para todos os terminais):
-
Confirme se a versão correta do Python está sendo usada:
python --version
Você verá:
Python 3.12.x
Pré-requisitos: instale o gerenciador de versões do Python (pyenv-win) e uma versão adequada do Python usando o pyenv.
-
Defina a versão global do Python:
-
Para definir o Python 3.12.x como a versão global:
pyenv global 3.12.x
-
Ou defina a versão do Python localmente para uma pasta de projeto específica:
pyenv local 3.12.x
-
Para definir o Python 3.12.x como a versão global:
-
Confirme se a versão correta do Python está sendo usada:
python --version
Você verá:
Python 3.12.x
- Se você pretende usar objetos compostos, precisará instalar o crcmod compilado. No Windows, ele está disponível apenas para o Python de 32 bits. Para mais
informações sobre o crcmod, instale o gsutil e consulte o tópico de ajuda usando o
comando
gsutil help crc32c
.
Como instalar o gsutil
O método de instalação e atualização do gsutil com suporte oficial faz parte da CLI do Google Cloud.
Antes de começar
A CLI do Google Cloud e o gsutil têm dependências de versão do Python que podem causar problemas de compatibilidade. A CLI do Google Cloud requer o Python 3.8 a 3.13, enquanto a gsutil requer o Python 3.8 a 3.12.
Para instalar o gsutil, recomendamos que você faça isso como parte da CLI do Google Cloud. Se você optar por instalar o gsutil diretamente, use o Python 3.8 a 3.12 para evitar problemas de compatibilidade.
Como instalar o gsutil como parte da CLI do Google Cloud
Siga as instruções do seu sistema operacional para instalar o gsutil como parte da CLI do Google Cloud:
- Confirme se você tem uma versão compatível do Python. A CLI do Google Cloud requer
o Python de 3.8 a 3.13. O pacote Linux x86_64 inclui
um intérprete de Python em pacote que terá preferência por padrão. Para
informações sobre como escolher e configurar o interpretador do Python, consulte
gcloud topic startup
. - Faça o download de um dos seguintes itens:
Plataforma Nome do pacote Tamanho Soma de verificação SHA256 Linux de 64 bits (x86_64)
google-cloud-cli-linux-x86_64.tar.gz 148,5 MB b9c0c9c2a913a2cc65cc2e288413d089d47771208107dff90cd6467bcd36b9c8 Linux de 64 bits (Arm)
google-cloud-cli-linux-arm.tar.gz 55,1 MB e7e271a7202bcaa7986ecbf93942921ed59be2f5c37127b6527e8357d1554ad2 Linux de 32 bits (x86)
google-cloud-cli-linux-x86.tar.gz 55,2 MB 2cbd4b38f9a0bd8131d8b14455fe1016ad33de812924c8b61e8819acece84e47 Para fazer o download do arquivo do Linux, execute o seguinte comando:
curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/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. - Para extrair o conteúdo do arquivo para o sistema de arquivos (preferencialmente para
seu diretório inicial), execute o seguinte comando:
Opcional: para substituir uma instalação, remova o diretóriotar -xf google-cloud-cli-linux-x86_64.tar.gz
google-cloud-sdk
e extraia o arquivo para o mesmo local. - (Opcional) Adicione a CLI gcloud ao
PATH
. Também é possível ativar a conclusão do comando para o shell e a coleta de estatísticas de uso. Execute o script de instalação (na raiz da pasta extraída na última etapa) usando o seguinte comando: Isso também pode ser feito de maneira não interativa (por exemplo, usando um script) e fornecendo preferências como sinalizações. Para ver as flags disponíveis, execute:./google-cloud-sdk/install.sh
./google-cloud-sdk/install.sh --help
- (Opcional) Para enviar estatísticas de uso anônimas para ajudar a melhorar a CLI gcloud, responda
Y
quando solicitado. -
Para adicionar a CLI gcloud ao
PATH
e ativar o preenchimento do comando, respondaY
quando solicitado.
- (Opcional) Para enviar estatísticas de uso anônimas para ajudar a melhorar a CLI gcloud, responda
- Se você atualizou o
PATH
na etapa anterior, abra um novo terminal para que as mudanças entrem em vigor. - Para inicializar a CLI gcloud, execute o comando
gcloud init
: - Opcional: instale componentes extras usando o gerenciador de componentes.
./google-cloud-sdk/bin/gcloud init
Conteúdo do pacote
A CLI gcloud está disponível no formato de pacote para instalação em sistemas Debian e Ubuntu.
O pacote contém apenas os comandos gcloud
, gcloud alpha
, gcloud beta
, gsutil
e bq
. Ele não inclui kubectl
ou as extensões do App Engine necessárias para implantar um aplicativo usando os comandos gcloud
. Se você quiser esses componentes, instale-os separadamente.
Antes de instalar a CLI gcloud, verifique se o sistema operacional atende aos seguintes requisitos:
- É uma versão do Ubuntu que não atingiu o fim da vida útil ou uma versão estável do Debian que não atingiu o fim da vida útil
- Recentemente, os pacotes foram atualizados:
sudo apt-get update
- Inclui o
apt-transport-https
e ocurl
instalados:sudo apt-get install apt-transport-https ca-certificates gnupg curl
- Importe a chave pública Google Cloud .
Para distribuições mais recentes (Debian 9+ ou Ubuntu 18.04+), 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 for compatível com 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 for possível receber as atualizações mais recentes devido a uma chave expirada, consiga o arquivo de chave apt-get.gpg mais recente.
- Adicione o URI de distribuição da CLI gcloud como uma origem de pacote.
- Para distribuições mais recentes (Debian 9+ ou Ubuntu 18.04+), 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 são compatíveis com a opção "assinado por", 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
- Para distribuições mais recentes (Debian 9+ ou Ubuntu 18.04+), execute o seguinte comando:
- Atualize e instale a gcloud CLI:
Para mais opções desudo apt-get update && sudo apt-get install google-cloud-cli
apt-get
, como desativar prompts ou simulações, consulte asapt-get
páginas do manual de.Dica do Docker: se você estiver instalando a gcloud CLI dentro de uma imagem Docker, use uma única etapa RUN:
Para imagens de base mais antigas que não são compatíveis com o comandoRUN 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
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
- (Opcional) Instale qualquer um dos seguintes
componentes adicionais:
google-cloud-cli
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 maneira:sudo apt-get install google-cloud-cli-app-engine-java
- Execute
gcloud init
para começar:gcloud init
Como fazer downgrade das versões da CLI gcloud
Para reverter para uma versão específica da CLI gcloud, em que VERSION
é do
formulário 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.
OBSERVAÇÃO: para versões anteriores a 371.0.0, o nome do pacote é google-cloud-sdk
Conteúdo do pacote
A CLI gcloud está disponível no formato de pacote para instalação no Red Hat Enterprise Linux 7, 8 e 9. Fedora 33 e 34; e CentOS 7 e 8.
O pacote contém apenas os comandos gcloud
, gcloud alpha
, gcloud beta
, gsutil
e bq
. Ele não inclui kubectl
ou as extensões do App Engine
necessárias para implantar um aplicativo usando comandos gcloud
, que podem ser
instalados separadamente conforme descrito posteriormente nesta seção.
- Atualize o DNF com informações de repositório da gcloud CLI.
O comando de exemplo a seguir é para uma instalação compatível com o Red Hat Enterprise Linux 9, mas certifique-se de atualizar as definições conforme necessário para 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
-
Se você estiver instalando no Fedora 34 ou 35, instale o
libxcrypt-compat.x86_64
.sudo dnf install libxcrypt-compat.x86_64
- Instale a CLI gcloud.
sudo dnf install google-cloud-cli
- (Opcional) Instale qualquer um dos seguintes
componentes adicionais:
google-cloud-cli
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 maneira:sudo dnf install google-cloud-cli-app-engine-java
- Execute
gcloud init
para começar:gcloud init
Como fazer downgrade das versões da CLI gcloud
Se você quiser reverter para uma versão específica da gcloud CLI, em que VERSION
seja do formulário 123.0.0
, execute: sudo dnf downgrade google-cloud-cli-VERSION
. Os dez lançamentos mais recentes sempre estarão disponíveis no repositório.
OBSERVAÇÃO: para versões anteriores a 371.0.0, o nome do pacote é google-cloud-sdk
-
Confirme se você tem uma versão compatível do Python:
-
Para verificar a versão atual do Python, execute
python3 -V
oupython -V
. As versões compatíveis são o Python 3.8 a 3.13. - O script de instalação principal oferece a instalação do Python 3.12 do CPython.
- Caso contrário, para instalar uma versão compatível do Python, acesse as versões do Python para macOS (link em inglês) do Python.org.
- Se você tem vários intérpretes de Python instalados na sua máquina, defina a variável de ambiente CLOUDSDK_PYTHON no shell para apontar para o caminho do intérprete preferido.
-
Para informações sobre como escolher e
configurar o interpretador do Python, consulte
gcloud topic startup
.
-
Para verificar a versão atual do Python, execute
- Faça o download de um dos seguintes itens:
-
Extraia o arquivo para qualquer local no seu sistema de arquivos, de preferência no diretório principal. No
macOS, isso pode ser feito abrindo o arquivo
.tar.gz
salvo no local de preferência.Para substituir uma instalação, remova o diretório
google-cloud-sdk
e extraia o arquivo para o mesmo local. - Execute o script de instalação (na raiz da pasta extraída na última etapa)
usando o seguinte comando:
./google-cloud-sdk/install.sh
O script vai solicitar a instalação do Python 3.12 e de alguns módulos recomendados.
A instalação também pode ser feita de maneira não interativa (por exemplo, usando um script) fornecendo preferências como flags. Para descrever as sinalizações disponíveis, execute: Para executar o script de instalação com o modo de leitor de tela ativado:./google-cloud-sdk/install.sh --help
Opcional:./google-cloud-sdk/install.sh --screen-reader=true
- (Opcional) Para enviar estatísticas de uso anônimas para ajudar a melhorar a gcloud CLI, responda
Y
quando solicitado. -
Para adicionar a CLI gcloud ao
PATH
e ativar o preenchimento do comando, respondaY
quando solicitado.
- (Opcional) Para enviar estatísticas de uso anônimas para ajudar a melhorar a gcloud CLI, responda
- Se você atualizou o
PATH
na etapa anterior, abra um novo terminal para que as mudanças entrem em vigor. -
Para inicializar a CLI gcloud, execute
gcloud init
: - Opcional. Instale componentes extras usando o gerenciador de componentes.
Plataforma | Pacote | Tamanho | Soma de verificação SHA256 |
---|---|---|---|
macOS de 64 bits
(x86_64) |
google-cloud-cli-darwin-x86_64.tar.gz | 55,2 MB | e3e9a49cf9c08336c88281b32c4114ab15a6ba21bcf8689eee2e9de2b263c816 |
macOS de 64 bits
(ARM64, Apple silicon) |
google-cloud-cli-darwin-arm.tar.gz | 55,2 MB | 1e42e364a7d6d7ead4486ba4edd811b19f91662740442c24a98700348947d5f2 |
macOS de 32 bits
(x86) |
google-cloud-cli-darwin-x86.tar.gz | 53,8 MB | e829d7a7c0516c37f373c7d6e985b6352284c9d4aea7fd9fe5fb550275cdd44c |
./google-cloud-sdk/bin/gcloud init
-
A Google Cloud CLI funciona no Windows 8.1 e versões mais recentes e no Windows Server 2012 e versões mais recentes.
-
Faça o download do Instalador da CLI do Google Cloud.
Se preferir, abra um terminal do PowerShell e execute os comandos a seguir:
(New-Object Net.WebClient).DownloadFile("https://dl.google.com/dl/cloudsdk/channels/rapid/GoogleCloudSDKInstaller.exe", "$env:Temp\GoogleCloudSDKInstaller.exe") & $env:Temp\GoogleCloudSDKInstaller.exe
-
Inicie o instalador e siga os prompts. O instalador é assinado pela Google LLC.
Se você estiver usando um leitor de tela, marque a caixa de seleção Ativar modo leitor de tela. Essa opção configura
gcloud
para usar rastreadores de status em vez de spinners unicode, exibir o progresso como uma porcentagem e nivelar tabelas. Para mais informações, consulte o Guia de recursos de acessibilidade. -
A CLI do Google Cloud requer Python. As versões compatíveis são o Python 3.8 a 3.13. Por padrão, a versão para Windows da CLI do Google Cloud vem com o Python 3. Para usar a CLI do Google Cloud, seu sistema operacional precisa executar uma versão compatível do Python.
O instalador instala todas as dependências necessárias, incluindo a versão necessária do Python. Embora o SDK da CLI do Google Cloud instale e gerencie o Python 3 por padrão, é possível usar uma instalação atual do Python ao desmarcar a opção de instalar o Bundled Python, se necessário. Consulte
gcloud topic startup
para saber como usar uma instalação existente do Python. Depois que a instalação for concluída, o instalador oferecerá a opção de criar os atalhos do menu e da área de trabalho, iniciar o shell da CLI do Google Cloud e configurar a CLI gcloud. Deixe as opções para iniciar o shell e configurar a instalação selecionadas. O instalador inicia uma janela de terminal e executa o comando
gcloud init
.- A instalação padrão não inclui as extensões do App Engine necessárias para implantar um aplicativo usando comandos
gcloud
. Para instalar esses componentes, use o gerenciador de componentes da CLI gcloud.
- Se a instalação não for bem-sucedida devido ao comando
find
não ter sido reconhecido, verifique se sua variável de ambientePATH
está definida para incluir a pasta que contémfind
. Geralmente, isso éC:\WINDOWS\system32;
. - Se você desinstalou a CLI gcloud, é necessário reinicializar o sistema antes de instalá-la novamente.
- Se a descompactação falhar, execute o instalador como um administrador.
Como parte da instalação do gsutil
, defina a
variável de ambiente CLOUDSDK_PYTHON
para usar a versão
correta do Python. Para mais detalhes, consulte gcloud startup topic
.
Execute as atualizações com o comando components update
: gcloud components update
.
Como configurar credenciais para acessar dados protegidos
Para acessar dados protegidos ou gravar em um bucket protegido, é necessário configurar as credenciais (autenticar). Por exemplo, se outra pessoa criou uma conta do Cloud Storage e fez upload de dados que só podem ser acessados por você ou por outras pessoas específicas, configure suas credenciais para que o serviço do Cloud Storage consiga acessar esses dados.
Ao usar o gsutil como parte da CLI do Google Cloud, o OAuth2 é usado para autenticar e autorizar o acesso aos recursos do Cloud Storage. Para estabelecer o acesso, execute o comando gcloud init
e siga as instruções fornecidas na linha de comando, que incluem o login na sua conta de usuário. Se você seguiu as
etapas de instalação, provavelmente já fez essa configuração. Se você executou gcloud init
anteriormente, ao executar o comando novamente, será perguntado se quer reinicializar a configuração ou criar uma nova. Para mais informações, consulte Inicializar a Google Cloud CLI.
Isso é tudo! Já é possível acessar os dados protegidos. Para ver uma lista de comandos gsutil, digite gsutil
no prompt de comando.
Solução de problemas
Se você tentar autenticar o gsutil usando o comando gcloud init
, mas ainda não
conseguir acessar os buckets ou objetos esperados,
seu sistema poderá ter a versão legada e autônoma do gsutil e o
Google Versão do pacote da CLI do Cloud gsutil instalada. Execute o comando gsutil version -l
e
verifique o valor de using cloud sdk
. Se for False
, seu sistema estará usando a
versão autônoma da gsutil ao executar comandos. É recomendável
remover a versão autônoma da gsutil do sistema. No entanto, você também pode autenticar usando
gsutil config -a
ou gsutil config -e
.
Autenticar com HMAC
O OAuth 2.0 é o meio de autenticação recomendado para o gsutil. No entanto, também é possível usar chaves HMAC como credenciais. Para autenticar com HMAC, use o seguinte comando:
gsutil config -a
Esse comando direciona você para um processo de autenticação em que é solicitado o ID de acesso e o secret associados à sua chave HMAC.
Ao autenticar com chaves HMAC, desative a transmissão de credenciais da CLI do Google Cloud usando o comando: gcloud config set pass_credentials_to_gsutil false
.
Ativar o mTLS
Também é possível ativar o TLS mútuo (mTLS). Quando o mTLS está ativado no dispositivo, ele tenta se conectar ao endpoint de solicitação de mTLS da API JSON. Antes que a conexão seja permitida, o Cloud Storage verifica o certificado no dispositivo.
A maneira mais simples de conseguir um certificado é pela CLI do Google Cloud. É possível definir um manualmente no arquivo .boto definindo os seguintes valores em "Credentials":
-
use_client_certificate
: uma sinalização que controla se o mTLS será usado ou não -
cert_provider_command
: um comando de shell que imprime um certificado no stdout para que a gsutil leia.
Faça um teste
Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho do Cloud Storage em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.
Faça uma avaliação gratuita do Cloud Storage