Estrutura de chamada de API

Este guia descreve a estrutura comum de todas as chamadas de API.

Se você usa uma biblioteca de cliente para interagir com a API, não precisa se preocupar com os detalhes da solicitação. No entanto, saber um pouco sobre elas pode ser útil ao testar e depurar.

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

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

2. [Opcional] Crie o corpo da solicitação como um objeto JSON, envie-o para o 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 como usar o 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 por suas strings de nome de recurso. Essas strings também servem como URLs ao usar a interface REST. Consulte a Estrutura de nomes de recursos da interface REST.

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

IDs compostos

Se o código de um objeto não for exclusivo globalmente, um código composto para esse objeto será criado adicionando o código pai e um til (~).

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

• AdGroupId de 123 + ~ + AdGroupAdId de 45678 = código 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 na forma de Authorization: Bearer YOUR_ACCESS_TOKEN que identifique uma conta de administrador atuando em nome de um cliente ou um anunciante gerenciando diretamente a própria conta. Instruções para recuperar um token de acesso estão disponíveis no Guia do OAuth2. Um token de acesso é válido por uma hora depois de adquirido. Quando ele expirar, atualize o token de acesso para recuperar um novo. Observe que nossas bibliotecas de cliente atualizam automaticamente os tokens expirados.

token de desenvolvedor

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

ID de cliente de login

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

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

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

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

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

ID de cliente vinculado

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

Considere o cenário em que os usuários na conta A fornecem acesso de leitura e edição às entidades para a conta B com um ThirdPartyAppAnalyticsLink. Após a vinculação, um usuário da conta B pode fazer chamadas de API com base na conta A, de acordo com as 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 do relacionamento de conta de administrador usado 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 aplicativos 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 rolling-metadata) são retornados com o corpo da resposta. Recomendamos que você registre esses valores para fins de depuração.

ID da solicitação

O request-id é uma string que identifica exclusivamente essa solicitação.