Autentique-se para usar a REST

Esta página descreve como fazer a autenticação quando faz um pedido REST a uma API Google.

Para obter informações sobre como fazer a autenticação quando usa bibliotecas cliente Google, consulte o artigo Autenticação através de bibliotecas cliente.

Antes de começar

Para executar os exemplos nesta página, conclua os seguintes passos:

  1. Install the Google Cloud CLI.

  2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  3. To initialize the gcloud CLI, run the following command: 

    gcloud init

  4. Enable the Cloud Resource Manager and Identity and Access Management (IAM) APIs:

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles. 

    gcloud services enable cloudresourcemanager.googleapis.com iam.googleapis.com

Se não quiser usar a CLI gcloud, pode ignorar estes passos e usar a representação da conta de serviço ou o servidor de metadados para gerar um token.

Tipos de credenciais

Pode usar os seguintes tipos de credenciais para autenticar uma chamada REST:

  • As suas credenciais da CLI gcloud.

    Esta abordagem é a forma mais fácil e segura de fornecer credenciais a um método REST num ambiente de desenvolvimento local. Se a sua conta de utilizador tiver as autorizações de gestão de identidade e de acesso (IAM) necessárias para o método que quer chamar, esta é a abordagem preferencial.

    As suas credenciais do gcloud não são as mesmas que as credenciais que fornece ao ADC através da CLI gcloud. Para mais informações, consulte o artigo Configuração de autenticação da CLI gcloud e configuração do ADC.

  • As credenciais fornecidas às Credenciais padrão da aplicação (ADC).

    Este método é a opção preferencial para autenticar uma chamada REST num ambiente de produção, porque o ADC encontra credenciais a partir do recurso onde o seu código está a ser executado (como uma máquina virtual do Compute Engine). Também pode usar o ADC para autenticar num ambiente de desenvolvimento local. Neste cenário, a CLI gcloud cria um ficheiro que contém as suas credenciais no sistema de ficheiros local.

  • As credenciais fornecidas através da utilização da identidade de uma conta de serviço.

    Este método requer mais configuração. Se quiser usar as suas credenciais existentes para obter credenciais de curta duração para outra conta de serviço, como testar com uma conta de serviço localmente ou pedir privilégios elevados temporários, use esta abordagem.

  • As credenciais devolvidas pelo servidor de metadados.

    Este método só funciona em ambientes com acesso a um servidor de metadados. As credenciais devolvidas pelo servidor de metadados são as mesmas que as credenciais que seriam encontradas pelas credenciais predefinidas da aplicação através da conta de serviço anexada, mas pede explicitamente o token de acesso ao servidor de metadados e, em seguida, fornece-o com o pedido REST. A consulta do servidor de metadados para credenciais requer um pedido HTTP GET. Este método não depende da CLI gcloud.

  • Chaves de API

    Pode usar uma chave da API com um pedido REST apenas para APIs que aceitem chaves da API. Além disso, a chave da API não pode estar restrita para impedir a sua utilização com a API.

Credenciais da CLI gcloud

Para executar o exemplo seguinte, precisa da autorização resourcemanager.projects.get no projeto. A autorização resourcemanager.projects.get está incluída numa variedade de funções, por exemplo, a função de navegador (roles/browser).

  1. Use o comando gcloud auth print-access-token para inserir uma chave de acesso gerada a partir das suas credenciais de utilizador.

    O exemplo seguinte obtém detalhes do projeto especificado. Pode usar o mesmo padrão para qualquer pedido REST.

    Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

    • PROJECT_ID: o ID ou o nome do seu projeto Google Cloud .

    Para enviar o seu pedido, escolha uma destas opções:

    curl

    Execute o seguinte comando: 

    curl -X GET \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

    PowerShell

    Execute o seguinte comando: 

    $cred = gcloud auth print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method GET `
        -Headers $headers `
        -Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand Content

    Os detalhes do seu projeto são devolvidos.

Para APIs que requerem um projeto de quota, tem de definir um explicitamente para o pedido. Para mais informações, consulte a secção Defina o projeto de quota com um pedido REST nesta página.

Credenciais padrão da aplicação

Para executar o exemplo seguinte, o principal associado às credenciais que faculta ao ADC precisa da autorização resourcemanager.projects.get no projeto. A autorização resourcemanager.projects.get está incluída numa variedade de funções, por exemplo, a função de navegador (roles/browser).

  1. Forneça credenciais ao ADC.

    Se estiver a executar num Google Cloud recurso de computação, não deve fornecer as suas credenciais de utilizador ao ADC. Em alternativa, use a conta de serviço anexada para fornecer credenciais. Para mais informações, consulte o artigo Configure o ADC para um recurso com uma conta de serviço anexada.

  2. Use o comando gcloud auth application-default print-access-token para inserir o token de acesso devolvido pela ADC no seu pedido REST.

    O exemplo seguinte obtém detalhes do projeto especificado. Pode usar o mesmo padrão para qualquer pedido REST.

    Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

    • PROJECT_ID: o ID ou o nome do seu projeto Google Cloud .

    Para enviar o seu pedido, escolha uma destas opções:

    curl

    Execute o seguinte comando: 

    curl -X GET \
         -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
         "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

    PowerShell

    Execute o seguinte comando: 

    $cred = gcloud auth application-default print-access-token
    $headers = @{ "Authorization" = "Bearer $cred" }

    Invoke-WebRequest `
        -Method GET `
        -Headers $headers `
        -Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand Content

    Os detalhes do seu projeto são devolvidos.

    Se o seu pedido devolver uma mensagem de erro sobre as credenciais do utilizador final não serem suportadas por esta API, consulte o artigo Defina o projeto de quota com um pedido REST nesta página.

Conta de serviço simulada

A forma mais simples de se fazer passar por uma conta de serviço para gerar um token de acesso é usar a CLI gcloud. No entanto, se precisar de gerar o token programaticamente ou não quiser usar a CLI gcloud, pode usar a representação para gerar um token de curta duração.

Para mais informações sobre a simulação de uma conta de serviço, consulte o artigo Use a simulação de conta de serviço.

  1. Reveja as autorizações necessárias.

    • O principal que quer usar para realizar a representação tem de ter a autorização iam.serviceAccounts.getAccessToken na conta de serviço representada (também denominada conta de serviço com privilégios). A autorização iam.serviceAccounts.getAccessToken está incluída na função Criador de tokens de contas de serviço (roles/iam.serviceAccountTokenCreator). Se estiver a usar a sua conta de utilizador, tem de adicionar esta autorização, mesmo que tenha a função Proprietário (roles/owner) no projeto. Para mais informações, consulte o artigo Definir autorizações necessárias.

  2. Identifique ou crie a conta de serviço com privilégios, ou seja, a conta de serviço cuja identidade vai usar.

    A conta de serviço com privilégios tem de ter as autorizações necessárias para fazer a chamada do método API.

gcloud

  1. Use o comando gcloud auth print-access-token com a flag --impersonate-service-account para inserir um token de acesso para a conta de serviço com privilégios no seu pedido REST.

O exemplo seguinte obtém detalhes do projeto especificado. Pode usar o mesmo padrão para qualquer pedido REST.

Para executar este exemplo, a conta de serviço cuja identidade está a usar precisa da autorização resourcemanager.projects.get. A autorização resourcemanager.projects.get está incluída numa variedade de funções, por exemplo, a função de navegador (roles/browser).

Faça as seguintes substituições:

  • PRIV_SA: o endereço de email da conta de serviço com privilégios. Por exemplo, my-sa@my-project.iam.gserviceaccount.com.

  • PROJECT_ID: o ID ou o nome do seu projeto Google Cloud .

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token --impersonate-service-account=PRIV_SA)" \
    "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

Token de curta duração

Para gerar um token de curta duração através da representação da conta de serviço, siga as instruções fornecidas em Crie um token de acesso de curta duração.

Servidor de metadados

Para obter um token de acesso do servidor de metadados, tem de fazer a chamada REST usando um dos serviços que tem acesso a um servidor de metadados:

Usa uma ferramenta de linha de comandos, como curl, para obter um token de acesso e, em seguida, insere-o no seu pedido REST.

  1. Consultar o servidor de metadados para obter um token de acesso:

    curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" \
    -H "Metadata-Flavor: Google"

    O pedido devolve uma resposta semelhante ao seguinte exemplo:

    {
      "access_token":"ya29.AHES6ZRN3-HlhAPya30GnW_bHSb_QtAi85nHq39HE3C2LTrCARA",
      "expires_in":3599,
      "token_type":"Bearer"
 }

  2. Insira o token de acesso no seu pedido REST, fazendo as seguintes substituições:

    • ACCESS_TOKEN: o token de acesso devolvido no passo anterior.
    • PROJECT_ID: o ID ou o nome do seu projeto Google Cloud .
    curl -X GET \
    -H "Authorization: Bearer ACCESS_TOKEN" \
    "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

Chaves da API

Para incluir uma chave da API com uma chamada da API REST, use o cabeçalho x-goog-api-key HTTP, conforme mostrado no exemplo seguinte:

curl -X POST \
    -H "X-goog-api-key: API_KEY" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://translation.googleapis.com/language/translate/v2"

Se não puder usar o cabeçalho HTTP, pode usar o parâmetro de consulta key. No entanto, este método inclui a sua chave da API no URL, expondo-a a roubo através de análises de URLs.

O exemplo seguinte mostra como usar o parâmetro de consulta key com um pedido da API Cloud Natural Language para documents.analyzeEntities. Substitua API_KEY pela string da chave da API.

POST https://language.googleapis.com/v1/documents:analyzeEntities?key=API_KEY

Defina o projeto de quota com um pedido REST

Para chamar algumas APIs com credenciais de utilizador, também tem de definir o projeto que é faturado pela sua utilização e usado para acompanhar a quota. Se a chamada API devolver uma mensagem de erro a indicar que as credenciais do utilizador não são suportadas ou que o projeto de quota não está definido, tem de definir explicitamente o projeto de quota para o pedido. Para definir o projeto de quota, inclua o cabeçalho x-goog-user-project no seu pedido.

Para mais informações sobre quando pode encontrar este problema, consulte o artigo As credenciais do utilizador não estão a funcionar.

Tem de ter a autorização do IAM serviceusage.services.use para poder designar um projeto como o seu projeto de faturação. A autorização serviceusage.services.use está incluída na função do IAM Service Usage Consumer. Se não tiver a serviceusage.services.use autorização para nenhum projeto, contacte o administrador de segurança ou o proprietário do projeto que lhe pode atribuir a função de consumidor de utilização de serviços no projeto.

O exemplo seguinte usa a API Cloud Translation para traduzir a palavra "hello" para espanhol. A Cloud Translation API é uma API que requer a especificação de um projeto de quota. Para executar o exemplo, crie um ficheiro denominado request.json com o conteúdo do corpo do pedido.

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • PROJECT_ID: o ID ou o nome do projeto Google Cloud a usar como projeto de faturação.

Corpo JSON do pedido: 

{
  "q": "hello",
  "source": "en",
  "target": "es"
}

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://translation.googleapis.com/language/translate/v2"

PowerShell

Guarde o corpo do pedido num ficheiro com o nome request.json, e execute o seguinte comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://translation.googleapis.com/language/translate/v2" | Select-Object -Expand Content

O pedido de tradução é bem-sucedido. Pode experimentar o comando sem o cabeçalho HTTP x-goog-user-project para ver o que acontece quando não especifica o projeto de faturação.

O que se segue?