O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

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, 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.

Recomendável:

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

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

Opcional:

Crie o corpo da solicitação como um objeto JSON.
Envie para o servidor usando HTTP 1.1.
Desserializar a resposta como um objeto JSON.
Interprete os resultados.

Consulte o guia da interface REST para mais informações sobre como usar 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 por strings de nome de recurso. Essas strings também servem como URLs ao usar a interface REST. Consulte a interface REST Nomes de recursos para conferir a estrutura.

IDs compostos

Se o ID de um objeto não for globalmente exclusivo, um ID composto será criado adicionando o ID do 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 principal (ad_group.id) e o ID do anúncio subjacente (ad_group_ad.ad.id), adicionamos o ID do grupo de anúncios antes do ID do anúncio:

AdGroupId de 123 + ~ + AdId de 45678 = grupo de anúncios composto ID do anúncio 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 OAuth 2.0 na forma de 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 depois de ser adquirido. Quando ele expira, atualize o token de acesso para recuperar um novo. As 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 vai 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 mais detalhes sobre o gerenciamento de permissões.

login-customer-id

É o ID do cliente autorizado a ser usado na solicitação, sem hífens (-). Se o acesso à conta de cliente for por uma conta de administrador, esse cabeçalho será obrigatório e precisará ser definido como o ID do cliente da conta de administrador. Se você não incluir login-customer-id ao fazer a autenticação por uma conta de administrador, isso vai 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 Modelo de acesso do OAuth.

https://googleads.googleapis.com/v25/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.

linked-customer-id

O 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 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 gerenciada ou atualizada pela chamada de API. O ID da conta do anunciante é especificado na solicitação. Em REST, esse é o parâmetro de caminho customerId (por exemplo, customers/1111111111/...). Em 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 com acesso à conta de parceiro faz chamadas de API para agir 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 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 Partner.
login-customer-id: o ID de cliente da conta de 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 da conta ao produto com o parceiro.

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

Se a conta do Anunciante tiver um link direto de produto com a conta do Parceiro, a Conta vinculada será Anunciante, e linked-customer-id precisará ser definido como o ID do 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 vínculo direto com a conta do parceiro 2222222222 e a chamada de API segmentar customers/1111111111/...:

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

Exemplo 2: link do gerente

Se a conta do anunciante 1111111111 for gerenciada pela conta de administrador 3333333333, a conta de administrador 3333333333 terá um vínculo com a conta do parceiro 2222222222, e a chamada de API vai segmentar customers/1111111111/...:

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

Cabeçalhos de resposta

Os seguintes cabeçalhos (ou gRPC trailing-metadata) 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 exclusivamente essa solicitação. 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.

Metadados de recursos