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. No entanto, ter 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.

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

Identificadores de recursos

Os objetos na API Google Ads são tratados 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 Nomes de recursos da interface REST para conferir a estrutura deles.

Importante :consulte a documentação de recursos para conferir todos os recursos compatíveis e a representação do 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 adicionando 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 do anúncio subjacente (ad_group_ad.ad.id), adicionamos o ID do grupo de anúncios ao ID do anúncio:

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

Observação: não é permitido 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 da solicitação:

Autorização

Você precisa incluir um token de acesso do OAuth 2.0 no formato Authorization: Bearer YOUR_ACCESS_TOKEN que identifica uma conta de administrador agindo em nome de um cliente ou um anunciante que gerencia 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 expira, 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 do Google Cloud for aprovado apenas para acesso Test e você enviar uma solicitação direcionada a uma conta de produção, a API retornará AuthorizationError.CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION na v25 e versões mais recentes (ou AuthorizationError.ACTION_NOT_PERMITTED na v24 e versões anteriores). Consulte Níveis de acesso do Google Ads para detalhes sobre como gerenciar permissões.

login-customer-id

Esse é o ID de cliente do 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 OAuth.

Termo importante: O cliente operacional é o ID de cliente no payload da solicitação. Por exemplo, o cliente operacional na solicitação a seguir CampaignBudgetService é 1234567890:

https://googleads.googleapis.com/v26/customers/1234567890/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, o padrão será o cliente operacional.

Observação: é possível recuperar a lista de contas que podem ser acessadas diretamente com suas credenciais 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 retornados.

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 do parceiro 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 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 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 for direcionada a 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 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 com solicitações de API com falha ou inesperadas.