Estrutura de chamada de API

Este guia descreve a estrutura comum de todas as chamadas de API.

Se você estiver usando uma biblioteca de cliente para interagir com a API, não precisará saber os detalhes da solicitação subjacente. No entanto, algum conhecimento sobre a estrutura de chamada de API pode ser útil ao testar e depurar.

A API Google Ads é uma API gRPC com vinculações REST. Isso significa que há duas maneiras de fazer chamadas para a API.

Preferencial:

  1. Crie o corpo da solicitação como um buffer de protocolo.
  2. Envie-o ao servidor usando HTTP/2.
  3. Desserialize a resposta para um buffer de protocolo.
  4. Interprete os resultados.

A maior parte da nossa documentação descreve o uso do gRPC.

Opcional:

  1. Crie o corpo da solicitação como um objeto JSON.
  2. Envie-o ao servidor usando HTTP 1.1.
  3. Desserialize a resposta como um objeto JSON.
  4. Interprete os resultados.

Consulte o guia da interface REST para mais informações sobre como usar o REST.

Nomes de recursos

A maioria dos objetos na API é identificada pelas strings de nome de recurso. Essas strings também servem como URLs ao usar a interface REST. Consulte os nomes de recursos da interface REST para conferir a estrutura deles.

IDs compostos

Se o ID de um objeto não for globalmente exclusivo, um ID composto para esse objeto será construído anexando o ID pai e um til (~).

Por exemplo, como um ID de anúncio do grupo de anúncios não é globalmente exclusivo, anexamos o ID do objeto pai (grupo de anúncios) para criar um ID composto exclusivo:

  • AdGroupId de 123 + ~ + AdGroupAdId de 45678 = ID composto do anúncio do grupo de anúncios de 123~45678.

Cabeçalhos de solicitação

Estes são os cabeçalhos HTTP (ou metadados grpc) que acompanham o corpo na solicitação:

Autorização

Você precisa incluir um token de acesso do OAuth 2.0 no formato Authorization: Bearer YOUR_ACCESS_TOKEN que identifique uma conta de administrador agindo em nome de um cliente ou um anunciante gerenciando diretamente a própria conta. As instruções para recuperar um token de acesso podem ser encontradas no guia do OAuth2. Um token de acesso é válido por uma hora após a aquisição. Quando ele expirar, atualize-o para conseguir um novo. Nossas bibliotecas de cliente atualizam automaticamente os tokens expirados.

Se você encontrar erros de autorização, verifique se está usando as credenciais corretas e se tem permissões suficientes. Um erro USER_PERMISSION_DENIED indica que o usuário autenticado pode não ter acesso à conta de cliente especificada na solicitação. Consulte os níveis de acesso do Google Ads para mais detalhes sobre como gerenciar permissões.

login-customer-id

Esse é o ID de cliente autorizado a ser usado na solicitação, sem hifens (-). Se o acesso à conta de cliente for por meio de uma conta de administrador, esse cabeçalho será obrigatório e precisará ser definido como o ID de cliente da conta de administrador. Se você não incluir login-customer-id ao fazer a autenticação por uma conta de administrador, isso resultará em um erro AuthorizationError.USER_PERMISSION_DENIED. Consulte erros comuns para mais informações sobre esse tipo de erro. Para uma explicação detalhada de como o acesso à conta é resolvido, consulte o guia do modelo de acesso do OAuth.

https://googleads.googleapis.com/v25/customers/CUSTOMER_ID/campaignBudgets:mutate

Definir o login-customer-id é equivalente a escolher uma conta na interface do Google Ads depois de fazer login ou clicar na imagem do perfil no canto superior direito. Se você não incluir esse cabeçalho, ele será definido como o cliente operacional.

linked-customer-id

Esse cabeçalho é obrigatório e usado por parceiros (como provedores de análise de apps de terceiros ou parceiros de dados) ao agir em uma conta vinculada do Google Ads. Esse cabeçalho precisa especificar o ID de cliente da conta do Google Ads que tem o link do produto.

Considere o cenário em que um parceiro precisa fazer chamadas de API para uma conta do Google Ads com base em um link de produto.

  • Anunciante: a conta do Google Ads que está sendo gerenciada ou atualizada pela chamada de API. O ID da conta do anunciante é especificado na solicitação. No REST, esse é o parâmetro de caminho customerId (por exemplo, customers/1111111111/...) e, no gRPC, esse é o campo customer_id na solicitação.
  • Parceiro: a conta de parceiro (por exemplo, um provedor de análise de apps de terceiros ou parceiro de dados).
  • Conta vinculada: a conta do Google Ads que tem um link de produto estabelecido com o parceiro, concedendo acesso ao anunciante.

Um usuário que tem acesso à conta do parceiro faz chamadas de API para agir em entidades na conta do anunciante (por exemplo, para fazer upload de conversões ou gerenciar listas de usuários). A conta vinculada pode ser a própria conta do anunciante ou uma conta de administrador da conta do anunciante.

Os cabeçalhos de solicitação precisam ser definidos da seguinte maneira:

  • Authorization: um token de acesso do OAuth 2.0 para um usuário que tem acesso ao parceiro.
  • login-customer-id: o ID de cliente do parceiro. O usuário autenticado precisa ter acesso a essa conta.
  • linked-customer-id: o ID de cliente da conta vinculada. Esse cabeçalho indica que a autorização para essa solicitação depende do link de produto da conta vinculada com o parceiro.

Há dois cenários de vinculação:

  • Se a conta do anunciante tiver um link de produto direto com a conta do parceiro, a conta vinculada será o anunciante, e linked-customer-id precisará ser definido como o ID de cliente da conta do anunciante.
  • Se a conta do anunciante for gerenciada por uma conta de administrador que tenha um link de produto com a conta do parceiro, a conta vinculada será a conta de administrador, e linked-customer-id precisará ser definido como o ID de cliente do administrador.

Exemplo 1: link direto

Se a conta do anunciante 1111111111 tiver um link direto com a conta do parceiro 2222222222 e a chamada de API estiver segmentando customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111

Exemplo 2: link de administrador

Se a conta do anunciante 1111111111 for gerenciada pela conta de administrador 3333333333, a conta de administrador 3333333333 tiver um link com a conta do parceiro 2222222222 e a chamada de API estiver segmentando customers/1111111111/...:

Authorization: Bearer YOUR_ACCESS_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333

Cabeçalhos de resposta

Os cabeçalhos a seguir (ou metadados finais do grpc) são retornados com o corpo da resposta. Recomendamos que você registre esses valores para fins de depuração.

request-id

O request-id é uma string que identifica essa solicitação de forma exclusiva.

Anterior
Metadados de recursos