Nesta página, descrevemos a instalação e a configuração da gsutil, uma ferramenta que permite acessar o Cloud Storage a partir da linha de comando usando HTTPS.
Basta instalar o gsutil para ter acesso imediato de gravação e/ou leitura a dados públicos. A autenticação no serviço Cloud Storage permite que você leia e/ou grave acesso a dados protegidos que foram compartilhados com você. 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-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.
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 131.6 MB beb7c8ef61c46ede9295bf68bfb331fbd158575cc3343db585d37b891c890336 Linux de 64 bits (Arm)
google-cloud-cli-linux-arm.tar.gz 53,9 MB 44eb95fd169f92c197f88df527c3aa27d5db9aa977c2fa2d28fa1cf506b00c9f Linux de 32 bits (x86)
google-cloud-cli-linux-x86.tar.gz 53,9 MB 10303f55226fac633761ae52e1dbcbcaf7c59fe11232f8196e6e361fc38e2e77 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. - Adicione a gcloud CLI ao caminho. Execute o script de instalação na raiz da pasta extraída 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
Opcional:./google-cloud-sdk/install.sh --help
- (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
- Abra um novo terminal para as alterações entrarem 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 do 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 | sudo 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.11 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. -
(Opcional) Use o script de instalação para adicionar ferramentas da CLI gcloud a
PATH
. Também é possível ativar a conclusão do comando no shell, coletar estatísticas de uso e instalar o Python 3.11.Execute o script (na raiz da pasta extraída na última etapa) usando este 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 descrever as sinalizações disponíveis, execute:./google-cloud-sdk/install.sh
Para executar o script de instalação com o modo de leitor de tela ativado:./google-cloud-sdk/install.sh --help
Abra um novo terminal para as alterações entrarem em vigor../google-cloud-sdk/install.sh --screen-reader=true
-
Para inicializar a gcloud CLI, execute o comando
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 | 53,9 MB | 9d1af0d2b5e7c8a30145831b99ce46272fc0aba754d7d23dcd3ede414b9ff75a |
macOS de 64 bits
(ARM64, Apple M1 silicon) |
google-cloud-cli-darwin-arm.tar.gz | 53,9 MB | d986d0c6531be038b71218f8e7e666c5b4d18ef580d6a063550406ed07e460f9 |
macOS de 32 bits
(x86) |
google-cloud-cli-darwin-x86.tar.gz | 52,6 MB | e98b4bf6449b9207ff5c4bd3df12a1b38ffa0f498274b26f2d80cfe7fb124f81 |
./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 Google Cloud CLI 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
, é necessário definir 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 acima, 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