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 precisa saber os detalhes da solicitação subjacente. No entanto, algum conhecimento sobre a estrutura de chamada de API pode ser útil durante o teste e 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.

Recomendado:

  1. Crie o corpo da solicitação como um buffer de protocolo.

  2. Envie-o para o 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 como usar o gRPC.

Opcional:

  1. Crie o corpo da solicitação como um objeto JSON.

  2. Envie para o servidor usando o 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 o uso da REST.

Nomes de recursos

A maioria dos objetos na API são identificados 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.

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 é válido por uma hora após ser adquirido. Quando ele expirar, atualize o token de acesso para conseguir um novo. Nossas bibliotecas 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.

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

Definir 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

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

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.

Anterior
Metadados do recurso