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á conhecer os detalhes da solicitação subjacente. No entanto, conhecer a estrutura de chamadas 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.

Recomendável:

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

A maior parte da nossa documentação descreve como usar o gRPC.

Opcional:

1. Crie o corpo da solicitação como um objeto JSON.
2. Envie-a 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 a REST.

Observação: este guia descreve a estrutura e os cabeçalhos de transporte comuns aos protocolos gRPC e REST.

Identificadores de recursos

Os objetos na API Google Ads são endereçados usando nomes de recursos estruturados e identificadores compostos.

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 ver a estrutura deles.

Importante: confira a documentação de recursos para ver todos os recursos compatíveis e a representação de caminho deles (resource_name). O mesmo formato é usado para outros serviços.

IDs compostos

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

Por exemplo, um AdGroupAd tem o padrão de nome de recurso customers/{customer_id}/adGroupAds/{ad_group_id}~{ad_id}. Como o identificador composto combina o ID do grupo de anúncios pai (ad_group.id) e o ID de anúncio subjacente (ad_group_ad.ad.id), adicionamos o ID do grupo de anúncios ao ID de anúncio:

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

Observação: é proibido compartilhar um AdId em vários grupos de anúncios. A criação de um novo AdGroupAd que faz referência a um AdId em outro grupo de anúncios falha com AdGroupAdError.AD_SHARING_NOT_ALLOWED.

Cabeçalhos das solicitações

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

Autorização

É preciso incluir um token de acesso do OAuth 2.0 na forma de Authorization: Bearer YOUR_ACCESS_TOKEN que identifique uma conta de administrador que atua em nome de um cliente ou um anunciante que gerencia diretamente a própria conta. As instruções para recuperar um token de acesso estão no guia do OAuth2. Um token de acesso é válido por uma hora após a aquisição. Quando ele expirar, atualize o token de acesso para recuperar 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. Se o projeto na nuvem do Google Cloud for aprovado apenas para acesso de Test e você enviar uma solicitação direcionada a uma conta de produção, a API vai retornar AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION na v25 e em versões mais recentes (ou AuthorizationError.ACTION_NOT_PERMITTED na v24 e em versões anteriores). Consulte os níveis de acesso do Google Ads para saber como gerenciar permissões.

login-customer-id

Esse é o ID do cliente autorizado a ser usado na solicitação, sem hifens (-). Se o acesso à conta de cliente for feito por 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 os 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.

Termo-chave: o cliente operacional é o ID de cliente no payload da solicitação. Por exemplo, o cliente operacional na seguinte solicitação CampaignBudgetService é 1234567890:

https://googleads.googleapis.com/v26/customers/1234567890/campaignBudgets:mutate

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

Observação: é possível recuperar a lista de contas que podem ser acessadas diretamente com suas credenciais do OAuth emitindo uma solicitação CustomerService.ListAccessibleCustomers. O login-customer-id não é obrigatório para esse tipo de solicitação e não tem efeito na lista de clientes retornada.

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 realizar ações em uma conta vinculada do Google Ads. Esse cabeçalho precisa especificar o ID de cliente da conta do Google Ads que tem a vinculação de produto.

Considere o cenário em que um parceiro precisa fazer chamadas de API para uma conta do Google Ads com base em uma vinculação 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 do parceiro (por exemplo, um provedor de análise de apps de terceiros ou um parceiro de dados).
• Conta vinculada: a conta do Google Ads que tem uma vinculação de produto estabelecida com o Parceiro, concedendo a ele acesso ao Anunciante.

Um usuário que tem acesso à conta de parceiro faz chamadas de API para atuar em entidades na conta de 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 da 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 da conta 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 da vinculação do produto da conta vinculada ao 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á 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 uma vinculação 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 de anunciante 1111111111 for gerenciada pela conta de administrador 3333333333, a conta de administrador 3333333333 tiver uma vinculação com a conta de parceiro 2222222222 e a chamada de API for direcionada a 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. Forneça esse valor ao entrar em contato com o suporte para ajudar a resolver problemas de solicitações de API com falha ou inesperadas.