Instalar o gsutil

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 pode ser executada no Linux/Unix, no Mac OS e no Windows (XP ou posterior).

  • Se você pretende usar objetos compostos, precisará instalar o crcmod compilado. No Windows, ele está disponível apenas para o Python de 32 bits.

Como instalar o gsutil

O método de instalação e atualização do gsutil com suporte oficial faz parte do SDK do Google Cloud.

Como instalar o gsutil como parte do SDK do Google Cloud

Siga as instruções do seu sistema operacional para instalar o gsutil como parte do SDK do Google Cloud:

Linux
  1. Digite o comando a seguir no prompt:
    curl https://sdk.cloud.google.com | bash
  2. Quando solicitado, escolha um local no seu sistema de arquivos (geralmente o diretório principal) para criar o subdiretório google-cloud-sdk.
  3. Se você quiser adicionar ferramentas de linha de comando do SDK do Cloud ao seu PATH e ativar o preenchimento do comando, responda y quando solicitado.
  4. Reinicie o shell:
    exec -l $SHELL
  5. Execute gcloud init para inicializar o ambiente gcloud:
    gcloud init
Debian/Ubuntu

Conteúdo do pacote

O SDK do Cloud 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 conforme descrito mais adiante nesta seção.

Pré-requisitos

Antes de instalar o SDK do Cloud, verifique se o sistema operacional é um dos seguintes:

Instalação
  1. Adicione o URI de distribuição do SDK do Cloud como a origem do pacote:
    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
    verifique se apt-transport-https (em inglês) está instalado:
    sudo apt-get install apt-transport-https ca-certificates gnupg

    Dica para solução de problema: se a distribuição não for compatível com a opção "assinado por", execute este comando:

    echo "deb https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list

    Dica para solução de problema: verifique se não há entradas duplicadas para o repositório cloud-sdk.

  2. Importe a chave pública do Google Cloud:
    curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key --keyring /usr/share/keyrings/cloud.google.gpg add -

    Dica para solução de problemas: se você não estiver recebendo as atualizações mais recentes devido a uma chave expirada, consiga o arquivo de chave apt-get.gpg mais recente.

    Dica para solução de problema: se o comando apt-key da sua distribuição não for compatível com o argumento --keyring, execute este comando:

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

  3. Atualize e instale o SDK do Cloud:
    sudo apt-get update && sudo apt-get install google-cloud-sdk
    Para mais opções de apt-get, como desativação de prompts ou simulações, consulte as páginas de manual de apt-get (em inglês).

    Dica do Docker: se você estiver instalando o SDK do Cloud dentro de uma imagem do Docker, use uma única etapa RUN:

    RUN echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] http://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-sdk -y
          

  4. Se preferir, instale qualquer um destes componentes extras:
    • google-cloud-sdk-app-engine-python
    • google-cloud-sdk-app-engine-python-extras
    • google-cloud-sdk-app-engine-java
    • google-cloud-sdk-app-engine-go
    • google-cloud-sdk-bigtable-emulator
    • google-cloud-sdk-cbt
    • google-cloud-sdk-cloud-build-local
    • google-cloud-sdk-datalab
    • google-cloud-sdk-datastore-emulator
    • google-cloud-sdk-firestore-emulator
    • google-cloud-sdk-pubsub-emulator
    • kubectl

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

    sudo apt-get install google-cloud-sdk-app-engine-java
  5. Execute gcloud init para começar:
    gcloud init

Como fazer downgrade das versões do SDK do Cloud

Se você quiser reverter para uma versão específica do SDK do Cloud, em que "VERSION" esteja no formato "123.0.0", execute: sudo apt-get update && sudo apt-get install google-cloud-sdk=123.0.0-0

macOS
  1. Digite o comando a seguir no prompt:
    curl https://sdk.cloud.google.com | bash
  2. Quando solicitado, escolha um local no seu sistema de arquivos (geralmente o diretório principal) para criar o subdiretório google-cloud-sdk.
  3. Se você quiser adicionar ferramentas de linha de comando do SDK do Cloud ao seu PATH e ativar o preenchimento do comando, responda y quando solicitado.
  4. Reinicie o shell:
    exec -l $SHELL
  5. Execute gcloud init para inicializar o ambiente gcloud:
    gcloud init
Windows
  1. Faça o download do Instalador do SDK do 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
          

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

    O SDK do Cloud requer o Python. As versões compatíveis são 3.5 a 3.7 e 2.7.9 ou mais recentes.

    O instalador implantará todas as dependências necessárias, incluindo a versão necessária do Python. Mesmo que o SDK do Cloud use atualmente o Python 3 por padrão, é possível usar uma instalação atual do Python ao desmarcar a opção "Instalar Bundled Python", se necessário.

  3. Depois que a instalação for concluída, o instalador apresentará várias opções:

    Prompts do instalador do Windows

    Verifique se as opções abaixo estão selecionadas:

    • Start Google Cloud SDK Shell (Iniciar Shell do SDK do Google Cloud)
    • Run 'gcloud init' (Executar 'gcloud init')

    O instalador inicia uma janela de terminal e executa o comando gcloud init.

  4. 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 do SDK do Cloud.
Dicas de solução de problemas:
  • Se o SDK do Cloud não funcionar depois de instalar a versão 274.0.0, consulte este rastreamento de erros (em inglês) para acessar soluções alternativas.
  • Se a instalação não for bem-sucedida porque o comando find não foi reconhecido, verifique se a variável de ambiente "PATH" está definida para incluir a pasta que contém "find". Normalmente, é C:\WINDOWS\system32;.
  • Se você acabou de desinstalar o SDK do Cloud, precisará reinicializar o sistema antes de instalá-lo novamente.

Execute as atualizações com o comando components update: gcloud components update.

Para saber como usar o gsutil, consulte o Guia de início rápido: como usar a ferramenta gsutil ou execute gsutil help.

Métodos alternativos de instalação

Há várias maneiras de instalar o gsutil como um produto independente. Talvez você prefira um desses métodos se não quiser nenhum dos outros componentes fornecidos com o SDK do Cloud ou se estiver gerenciando pacotes com o PyPI.

Se você estiver instalando o gsutil como uma ferramenta independente, um outro requisito de sistema é que o Python seja instalado em seu computador. O gsutil aceita oficialmente as versões secundárias 2.7.x a 3.7.x. Por padrão, o Python é instalado na maioria das distribuições do Linux e do macOS, mas não no Windows. Para executar o gsutil no Windows, primeiro é preciso instalar o Python.

Expanda o método pretendido para ver as instruções.

Como configurar credenciais para acessar dados protegidos

A instalação da gsutil permite acessar e fazer o download de objetos acessíveis publicamente. No entanto, para acessar dados protegidos ou gravar em um bloco 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.

Se você instalou o gsutil como parte do SDK do Google Cloud, siga as instruções abaixo. Caso contrário, consulte a seção Autenticar o gsutil independente.

Autenticar o SDK do Google Cloud

Ao usar o gsutil como parte do SDK do Google Cloud, o acesso é autenticado e autorizado por meio do OAuth2 (em inglês). Talvez você já tenha realizado as etapas abaixo se tiver seguido a seção Como instalar o gsutil como parte do SDK do Google Cloud acima. Se você já executou gcloud init, será perguntado se quer reinicializar a configuração ou criar uma nova.

  1. Abra uma instância do prompt de comando.

  2. Execute gcloud init no prompt de comando.

    Será gerada a seguinte saída:

    Welcome! This command will take you through the configuration of gcloud.
     
    Your current configuration has been set to: [default]
     
    To continue, you must login. Would you like to login (Y/n)?
    

  3. Digite "Y" e pressione Enter para fazer login.

    • O comando imprime um URL e tenta abrir uma janela do navegador para solicitar o acesso ao projeto. Se uma janela do navegador for aberta, você receberá a saída a seguir:

      Your browser has been opened to visit:
       
      https://accounts.google.com/o/oauth2/auth?redirect_uri=http%3A%2F%2F...
      

      Vá para a próxima etapa.

    • Se você estiver trabalhando em uma máquina local e seu navegador não carregar automaticamente o URL, tente executar novamente o comando gcloud init com a sinalização --console-only:

      gcloud init --console-only
      

      Se você usar esse comando ou se o SDK do Cloud detectar que um navegador não pode ser aberto (por exemplo, se você estiver trabalhando em uma máquina remota), será gerada a saída a seguir:

      Go to the following link in your browser:
       
      https://accounts.google.com/o/oauth2/auth?redirect_uri=urn%3Aietf%3Awg%3A...
       
      Enter verification code:
      

      Abra um navegador e navegue até o URL fornecido.

  4. Se solicitado, faça login com a Conta do Google associada aos seus dados do Cloud Storage na janela do navegador.

  5. Conceda acesso.

    • Se a janela do navegador abrir automaticamente, revise as permissões do aplicativo e clique em Aceitar quando estiver pronto. O código de verificação é enviado automaticamente para a ferramenta de linha de comando.

    • Se você estiver trabalhando em uma máquina remota ou usou a sinalização --console-only, copie o código de verificação do URL e cole-o na linha de comando do terminal, após Digite o código de verificação:.

  6. Escolha o projeto padrão para essa configuração.

    Depois de configurar suas credenciais, a ferramenta de linha de comando gcloud solicitará que você informe um projeto padrão para essa configuração e fornecerá uma lista de projetos disponíveis. Selecione um ID do projeto da lista.

    Quando você define essa propriedade, os comandos gsutil que exigem um projeto, como gsutil mb, usam o ID do projeto padrão, a menos que você os modifique com a sinalização -p ou defina a variável de ambiente CLOUDSDK_CORE_PROJECT.

Pronto. Já é possível acessar os dados protegidos. Para ver uma lista de comandos gsutil, digite gsutil no prompt de comando.

Autenticar o gsutil independente

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 a sinalização -a no comando gsutil config:

gsutil config -a

Ao usar esse comando, você passa por um processo semelhante à autenticação do gsutil independente (consulte a seção anterior). No entanto, será solicitado que você informe o ID de acesso e o secret associados à chave HMAC.

Se você estiver usando o SDK do Google Cloud, também precisará desativar a passagem de credenciais usando este comando:

gcloud config set pass_credentials_to_gsutil false