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:
Pré-requisitos: instale um gestor de versões do Python (pyenv) e instale uma versão adequada do Python.
-
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
-
Para definir o Python 3.13 como a versão global:
-
Confirme se está a usar a versão correta do Python:
python --version
Deve ver:
Python 3.13
Método 1: usar o Homebrew (brew)
Pré-requisitos: instale o Homebrew e instale uma versão adequada do Python através do Homebrew.
-
Defina uma versão específica do Python como predefinição:
-
Adicione a versão pretendida ao
$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
).
-
Adicione a versão pretendida ao
-
Confirme se 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.
-
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
-
Para definir a versão do Python globalmente (para todos os terminais):
-
Confirme se está a usar a versão correta do Python:
python --version
Deve ver:
Python 3.13
Pré-requisitos: instale o gestor de versões do Python (pyenv-win) e instale uma versão adequada do Python através do pyenv.
-
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
-
Para definir o Python 3.13 como a versão global:
-
Confirme se 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 o 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
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:
- Confirme que tem uma versão suportada do Python. A CLI do Google Cloud requer o Python 3.9 a 3.13. Tenha em atenção que o pacote Linux x86_64 inclui um intérprete Python integrado que é o preferido por predefinição. Para
informações sobre como escolher e configurar o seu intérprete Python, consulte
gcloud topic startup
. - 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 150,3 MB 128aaaf6ef1bcf9ca84d227202f92ab30e51c5ff5b1b44dfa4bcdd4b65f2ba46 Linux (64 bits) (Arm)
google-cloud-cli-linux-arm.tar.gz 56,9 MB c7c0ae1a4b9757eed63e7c96c99eefbb0be7c79b3614177fbb13980007bac22e Linux (32 bits) (x86)
google-cloud-cli-linux-x86.tar.gz 56,9 MB 159a757178daa9e1a53166ec62b70ff476cc15a18d4d9a36d3e60b8a850c9a52 Para transferir o ficheiro de 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 ficheiro para o seu sistema de ficheiros (de preferência, para o diretório principal), execute o seguinte comando:
Opcional: para substituir uma instalação existente, remova o diretóriotar -xf google-cloud-cli-linux-x86_64.tar.gz
google-cloud-sdk
existente e, em seguida, extraia o arquivo para a mesma localização. - (Opcional) Adicione a CLI gcloud ao seu
PATH
. Também pode optar pela conclusão de comandos para a recolha de estatísticas de utilização e do shell. Execute o script de instalação (a partir da raiz da pasta que extraiu no último passo) através do seguinte comando: Isto também pode ser feito de forma não interativa (por exemplo, através de um script) e fornecendo preferências como flags. Para ver as flags disponíveis, execute o seguinte comando:./google-cloud-sdk/install.sh
./google-cloud-sdk/install.sh --help
- Para enviar estatísticas de utilização anónimas
para ajudar a melhorar a CLI gcloud, responda
Y
quando lhe for pedido. -
Para adicionar a CLI gcloud ao seu
PATH
e ativar a conclusão de comandos, respondaY
quando lhe for pedido.
- Para enviar estatísticas de utilização anónimas
para ajudar a melhorar a CLI gcloud, responda
- Se atualizou o
PATH
no passo anterior, abra um novo terminal para que as alterações tenham efeito. - Para inicializar a CLI gcloud, execute
gcloud init
: - Opcional: instale componentes adicionais através do gestor de componentes.
./google-cloud-sdk/bin/gcloud init
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 os comandos 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 instalar a CLI gcloud, certifique-se de que o seu sistema operativo cumpre os seguintes requisitos:
- É uma versão do Ubuntu que não atingiu o fim de vida ou uma versão estável do Debian que não atingiu o fim de vida
- Atualizou recentemente os respetivos pacotes:
sudo apt-get update
- Tem
apt-transport-https
ecurl
instaladas:sudo apt-get install apt-transport-https ca-certificates gnupg curl
- Importe a Google Cloud 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 receber as atualizações mais recentes devido a uma chave expirada, obtenha o ficheiro de chave apt-get.gpg mais recente.
- 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
- Para distribuições mais recentes (Debian 9 ou superior, ou Ubuntu 18.04 ou superior), execute o seguinte comando:
- Atualize e instale a CLI gcloud:
Para opçõessudo apt-get update && sudo apt-get install google-cloud-cli
apt-get
adicionais, como desativar comandos ou testes de execução, consulte as páginas de manualapt-get
.Sugestão do Docker: se estiver a instalar a CLI gcloud numa imagem do Docker, use um único passo RUN em alternativa:
Para imagens base mais antigas que não suportam 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 forma:sudo apt-get install google-cloud-cli-app-engine-java
- Execute
gcloud init
para começar:gcloud init
Reduzir a versão 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.
NOTA: para lançamentos anteriores a 371.0.0, o nome do pacote é google-cloud-sdk
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 e 9; 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.
- Atualize o DNF com as informações do repositório da CLI gcloud.
O comando de exemplo seguinte destina-se a uma instalação compatível com o Red Hat Enterprise Linux 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
-
Instale
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 forma:sudo dnf install google-cloud-cli-app-engine-java
- Execute
gcloud init
para começar:gcloud init
Reduzir a versão da CLI gcloud
Se quiser reverter para uma versão específica da CLI gcloud, em que VERSION
tem o formato 123.0.0
, execute o seguinte:
sudo dnf downgrade google-cloud-cli-VERSION
As dez versões mais recentes estão sempre disponíveis no repositório.
NOTA: para lançamentos anteriores a 371.0.0, o nome do pacote é google-cloud-sdk
-
Confirme que tem uma versão suportada do Python:
-
Para verificar a sua versão atual do Python, execute
python3 -V
oupython -V
. As versões suportadas são Python 3.9 a 3.13. -
O script de instalação principal oferece a instalação do Python 3.12 do CPython.
- As ferramentas de linha de comandos do Xcode são necessárias para instalar o Python.
- Verifique se as ferramentas de linha de comandos do Xcode estão instaladas executando:
xcode-select -p
. - Se as ferramentas de linha de comandos do Xcode não estiverem instaladas, instale-as executando:
sudo xcode-select --install
.
- Caso contrário, para instalar uma versão do Python suportada, visite a página Python Releases for macOS em Python.org.
- Se tiver vários intérpretes Python instalados no seu computador, defina a variável de ambiente CLOUDSDK_PYTHON no shell para apontar para o caminho do seu intérprete preferencial.
-
Para mais informações sobre como escolher e configurar o seu intérprete Python, consulte
gcloud topic startup
.
-
Para verificar a sua versão atual do Python, execute
- Transfira uma das seguintes opções:
-
Extraia o arquivo para qualquer localização no seu sistema de ficheiros (de preferência, o diretório inicial). No
macOS, isto pode ser feito abrindo o ficheiro de arquivo
.tar.gz
transferido na localização preferida. Em alternativa, execute o seguinte comando:tar -xf google-cloud-cli-darwin-arm.tar.gz
Opcional: para substituir uma instalação existente, remova o diretório
google-cloud-sdk
existente e, em seguida, extraia o arquivo para a mesma localização. - Execute o script de instalação (a partir da raiz da pasta que extraiu no último passo)
com o seguinte comando:
./google-cloud-sdk/install.sh
O script pede-lhe que instale o Python 3.12 e determinados módulos recomendados.
A instalação também pode ser feita de forma não interativa (por exemplo, através de um script) fornecendo preferências como flags. Para descrever as flags disponíveis, execute o seguinte comando: Para executar o script de instalação com o modo de leitor de ecrã ativado:./google-cloud-sdk/install.sh --help
Opcional:./google-cloud-sdk/install.sh --screen-reader=true
- Para enviar estatísticas de utilização anónimas
para ajudar a melhorar a CLI gcloud, responda
Y
quando lhe for pedido. -
Para adicionar a CLI gcloud ao seu
PATH
e ativar a conclusão de comandos, respondaY
quando lhe for pedido.
- Para enviar estatísticas de utilização anónimas
para ajudar a melhorar a CLI gcloud, responda
- Se atualizou o
PATH
no passo anterior, abra um novo terminal para que as alterações tenham efeito. -
Para inicializar a CLI gcloud, execute o comando
gcloud init
: - Opcional. Instale componentes adicionais através do gestor de componentes.
Plataforma | Pacote | Tamanho | Soma de verificação SHA256 |
---|---|---|---|
macOS de 64 bits
(x86_64) |
google-cloud-cli-darwin-x86_64.tar.gz | 56,9 MB | cc0f5d2f660889a399435a218bffebdb43d056b5d37a69142cf7dc2395c18f7d |
macOS de 64 bits
(ARM64, Apple silicon) |
google-cloud-cli-darwin-arm.tar.gz | 56,9 MB | 4fa417f74a2e0a8839907e36d11e05731d8b4ba4445d300d2b7155060c0dcc8e |
macOS de 32 bits
(x86) |
google-cloud-cli-darwin-x86.tar.gz | 55,4 MB | 4af66400e2bbe20c05602c92cdde9e85c5f12818404e15aa4398b0bc580bc4ea |
./google-cloud-sdk/bin/gcloud init
-
A CLI do Google Cloud funciona no Windows 8.1 e posterior, e no Windows Server 2012 e posterior.
-
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://dl.google.com/dl/cloudsdk/channels/rapid/GoogleCloudSDKInstaller.exe", "$env:Temp\GoogleCloudSDKInstaller.exe") & $env:Temp\GoogleCloudSDKInstaller.exe
-
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.13. 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. 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. Certifique-se de que deixa selecionadas as opções para iniciar a shell e configurar a instalação. O instalador inicia uma janela de terminal e executa o comando
gcloud init
.- 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.
- Se a instalação não for bem-sucedida
porque o comando
find
não é reconhecido, certifique-se de que a variável de ambientePATH
está definida para incluir a pasta que contémfind
. 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":
-
use_client_certificate
: um indicador que controla se deve ou não usar o mTLS. -
cert_provider_command
: Um comando de shell que imprime um certificado para stdout para o gsutil ler.
Experimente
Se está a usar o Google Cloud pela primeira vez, crie uma conta para avaliar o desempenho do Cloud Storage em cenários reais. Os novos clientes também recebem 300 USD em créditos gratuitos para executar, testar e implementar cargas de trabalho.
Experimentar o Cloud Storage gratuitamente