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:
-
Install the Google Cloud CLI.
-
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
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 theserviceusage.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.
-
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
).
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 ContentOs 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
).
-
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.
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 ContentOs 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.
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çãoiam.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.
- O principal que quer usar para realizar a representação tem de ter a autorização
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
- 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:
- Compute Engine
- Ambiente padrão do App Engine
- Ambiente flexível do App Engine
- Funções do Cloud Run
- Cloud Run
- Google Kubernetes Engine
- Cloud Build
Usa uma ferramenta de linha de comandos, como curl
, para obter um token de acesso e, em seguida, insere-o no seu pedido REST.
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" }
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?
- Veja uma vista geral da autenticação.
- Saiba como fazer a autenticação com bibliotecas de cliente.
- Compreenda a configuração de autenticação da CLI gcloud e a configuração do ADC .