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á se preocupar com os detalhes da solicitação subjacente. No entanto, saber um pouco sobre eles pode ser útil durante os testes e a depuração.

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

1. [Preferível] Crie o corpo da solicitação como um buffer de protocolo, envie-o ao servidor usando HTTP/2, desserialize a resposta para um buffer de protocolo e interprete os resultados. A maior parte da nossa documentação descreve o uso do gRPC.

2. [Opcional] Crie o corpo da solicitação como um objeto JSON, envie-o ao servidor usando HTTP 1.1, desserialize a resposta como um objeto JSON e interprete os resultados. Consulte o guia da interface REST para mais informações sobre o uso da REST.

Observação: este guia descreve a estrutura e os cabeçalhos de transporte comuns aos protocolos gRPC e 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.

Importante: confira a documentação de recursos para saber quais recursos são 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á criado precedido pelo ID pai e um til (~).

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

• AdGroupId de 123 + ~ + AdGroupAdId de 45678 = ID do anúncio do grupo de anúncios composto 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

É necessário incluir um token de acesso OAuth2 no formato de Authorization: Bearer YOUR_ACCESS_TOKEN que identifique 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 OAuth2. Um token de acesso vale por uma hora depois de ser recebido. Quando ele expirar, atualize-o para conseguir um novo. Observe que nossas bibliotecas de cliente atualizam automaticamente os tokens expirados.

developer-token

Um token de desenvolvedor é uma string de 22 caracteres que identifica de forma exclusiva um desenvolvedor da API Google Ads. Um exemplo de string de token de desenvolvedor é ABcdeFGH93KL-NOPQ_STUv. O token do desenvolvedor precisa ser incluído no formato developer-token : ABcdeFGH93KL-NOPQ_STUv.

login-customer-id

É o ID do cliente autorizado a usar na solicitação, sem hifen (-). Se o acesso à conta do cliente for feito por uma conta de administrador, esse cabeçalho será obrigatório e precisará ser definido como o ID do cliente da conta de administrador.

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

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

Configurar 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 são diretamente acessíveis com suas credenciais OAuth emitindo uma solicitação CustomerService.ListAccessibleCustomers. O login-customer-id não é necessário para esse tipo de solicitação e não afeta a lista de clientes retornados.

linked-customer-id

Esse cabeçalho só é usado por fornecedores de análise de aplicativos de terceiros ao fazer upload de conversões para uma conta vinculada do Google Ads.

Considere o cenário em que os usuários da conta A concedem acesso de leitura e edição às entidades da conta B por meio de um ThirdPartyAppAnalyticsLink. Depois da vinculação, um usuário na conta B pode fazer chamadas de API na conta A, sujeito às permissões fornecidas pelo link. Nesse caso, as permissões de chamada de API para a conta A são determinadas pelo link de terceiros para a conta B, em vez da relação de administrador-conta usada em outras chamadas de API.

O provedor de análise de aplicativos de terceiros faz uma chamada de API da seguinte maneira:

• linked-customer-id: a conta de análise de apps de terceiros que faz o upload dos dados (conta B).
• customer-id: a conta do Google Ads para a qual os dados são enviados (conta A).
• Cabeçalho login-customer-id e Authorization: uma combinação de valores para identificar um usuário que tem acesso à conta B.

Cabeçalhos de resposta

Os cabeçalhos a seguir (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 essa solicitação de forma exclusiva.