Caution: You are viewing documentation for the API's REST interface. Most of our official client libraries use gRPC. See the REST Introduction for details.

Autorização e cabeçalhos HTTP

Vídeo: autenticação

Você precisa de credenciais do aplicativo OAuth 2.0 e de um token de desenvolvedor ao chamar a API Google Ads. Se você estiver fazendo chamadas de API como uma conta de administrador do Google Ads, também precisará especificar um cabeçalho login-customer-id com cada solicitação. Nesta página, descrevemos como definir esses valores e documentos e vários cabeçalhos HTTP específicos da API que são enviados e recebidos ao usar a interface REST.

Credenciais do OAuth 2.0

A API Google Ads usa credenciais do aplicativo para identificar e autorizar solicitações de API. É possível configurar tanto os clientes OAuth 2.0 quanto as contas de serviço. Para mais detalhes sobre como configurar a autorização do lado do cliente, consulte OAuth2 na API Google Ads.

Se você está começando a usar as APIs do Google, use oauth2l ou o OAuth 2.0 Playground para testar credenciais de aplicativo e a API Google Ads antes de escrever o código do seu aplicativo.

Como usar fluxos de apps da Web ou de computadores

Siga as etapas para configurar um projeto do Console de APIs do Google para a API Google Ads. Registre o ID do cliente e a chave secreta do cliente e depois volte para esta página.

Depois de criar um cliente OAuth, siga as instruções de fluxo de app para computador ou as instruções de fluxo de apps da Web para gerar um token de atualização e um token de acesso.

Como usar contas de serviço

Siga as instruções comuns no guia Contas de serviço para configurar o acesso da conta de serviço à API Google Ads.

Depois de configurar uma conta de serviço para acessar sua conta do Google Ads, siga o guia Como usar o OAuth 2.0 para aplicativos de servidor para servidor, certificando-se de selecionar a guia HTTP/REST. O scope a ser usado para acesso à API Google Ads é https://www.googleapis.com/auth/adwords.

Como gerar novos tokens de acesso

Depois de ter um ID do cliente, uma chave secreta do cliente e um token de atualização, você pode gerar um novo token de acesso para usar em chamadas de API com a ferramenta de linha de comando curl:

curl \
  --data "grant_type=refresh_token" \
  --data "client_id=CLIENT_ID" \
  --data "client_secret=CLIENT_SECRET" \
  --data "refresh_token=REFRESH_TOKEN" \
  https://www.googleapis.com/oauth2/v3/token

Em seguida, use o token de acesso retornado pela solicitação curl no cabeçalho HTTP Authorization de cada chamada da API Google Ads:

GET /v11/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

Cabeçalhos de solicitação

Token de desenvolvedor

A API Google Ads também requer um token de desenvolvedor para fazer chamadas para a API. Você pode solicitar um token para sua conta de administrador diretamente na IU do Google Ads. Para mais detalhes sobre como fazer a configuração com um token de desenvolvedor, consulte Receber seu token de desenvolvedor.

É necessário incluir o valor do token de desenvolvedor no cabeçalho HTTP developer-token de cada chamada à API Google Ads:

GET /v11/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

ID de cliente do login

Para chamadas da API Google Ads feitas por um administrador a uma conta de cliente (ou seja, ao fazer login como administrador para fazer chamadas de API em uma das contas de cliente), você também precisa fornecer o cabeçalho HTTP login-customer-id. Esse valor representa o ID de cliente do Google Ads do administrador que faz a chamada de API.

Incluir esse cabeçalho é equivalente a escolher uma conta na IU do Google Ads depois de fazer login ou clicar na sua imagem de perfil no canto superior direito da página. Ao especificar o ID de cliente, remova todos os hifens (—), por exemplo: 1234567890, não 123-456-7890.

GET /v11/customers:listAccessibleCustomers HTTP/1.1
Host: googleads.googleapis.com
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
login-customer-id: MANAGER_CUSTOMER_ID

ID de cliente vinculado

Esse cabeçalho é usado somente por provedores de análise de aplicativos terceirizados ao fazer o upload de conversões para uma conta vinculada do Google Ads. Consulte o guia de estrutura da chamada de API para mais detalhes.

...
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN
login-customer-id: MANAGER_CUSTOMER_ID
linked-customer-id: LINKED_CUSTOMER_ID

Cabeçalhos de resposta

Os cabeçalhos a seguir são retornados em respostas HTTP da API.

ID da solicitação

O request-id é uma string que identifica exclusivamente a solicitação de API. Ao depurar ou solucionar problemas em chamadas de API específicas, o request-id é um identificador importante para entrar em contato com o suporte ao desenvolvedor do Google.

request-id: 2a5Cj89VV7CNhya1DZjjrC