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, você não se preocupar com os detalhes subjacentes da solicitação. No entanto, saber um pouco sobre eles 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 à API.

1. [Preferencial] Crie o corpo da solicitação como um buffer de protocolo, envie-o ao servidor usando HTTP/2, desserializar a resposta a um protocolo armazenar em buffer e interpretar os resultados. A maior parte de nossa documentação descreve o uso gRPC.

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

.

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

Nomes de recursos

A maioria dos objetos na API é identificada pelas strings de nome de recurso. Esses strings também servem como URLs ao usar a interface REST. Consulte a REST Resource Names da interface do usuário para na estrutura dos preços.

Importante :confira a documentação de recursos. para todos os recursos compatíveis e a representação de 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 é construído adicionando seu ID pai e um til (~).

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

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

Cabeçalhos de solicitação

Estes são os cabeçalhos HTTP (ou grpc metadados) que acompanham o corpo da solicitação:

Autorização

Você precisa incluir um token de acesso OAuth2 na forma de Authorization: Bearer YOUR_ACCESS_TOKEN, que identifica um conta de administrador atuando em nome de um cliente ou anunciante diretamente gerenciar suas próprias contas. Instruções para recuperar um token de acesso pode ser encontrado no guia do OAuth2. Um token de acesso é válido por uma hora após sua aquisição; quando expirar, atualize o token de acesso para recuperar 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 exclusivamente um desenvolvedor da API Google Ads. Um exemplo de string de token de desenvolvedor é ABcdeFGH93KL-NOPQ_STUv: O token de desenvolvedor deve ser incluído de developer-token : ABcdeFGH93KL-NOPQ_STUv.

login-customer-id

Esse é o ID do cliente autorizado a usar na solicitação. sem hifens (-). Caso seu acesso à conta do cliente seja feito por meio de uma conta de administrador, esse cabeçalho é obrigatório e precisa ser definido como o ID de cliente da a conta de administrador.

Termo-chave :o cliente operacional é o ID de cliente no payload da solicitação. Por exemplo, o cliente operacional no A solicitação de CampaignBudgetService está 1234567890:

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

Definir o login-customer-id equivale a escolher uma conta no Interface do Google Ads depois de fazer login ou clicar na imagem do perfil na parte de cima certas. Se você não incluir esse cabeçalho, o padrão será a configuração operacional cliente.

Observação: você pode recuperar a lista de contas que podem ser acessadas diretamente com o suas credenciais do OAuth emitindo uma CustomerService.ListAccessibleCustomers solicitação. O login-customer-id não é obrigatório para esse tipo de solicitação. não afeta a lista de clientes retornados.

linked-customer-id

Esse cabeçalho só é usado por provedores de análise de aplicativos de terceiros quando fazendo o upload de conversões para uma conta do Google Ads vinculada padrão.

Considere o cenário em que os usuários da conta A dão acesso de leitura e edição às entidades para contabilizar B por meio de uma ThirdPartyAppAnalyticsLink. Após a vinculação, um usuário da conta B poderá fazer chamadas de API com base na conta A, sujeito às permissões fornecidas pelo link. Nesse caso, a chamada de API as permissões da conta A são determinadas pelo link de terceiros com a conta B, e não o 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 upload dados (conta B).
• customer-id: a conta do Google Ads para a qual os dados são enviados (conta A).
• Cabeçalhos 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 after-metadata) são retornadas com o corpo da resposta. Recomendamos que você registre essas valores para fins de depuração.

ID da solicitação

O request-id é uma string que identifica essa solicitação de maneira exclusiva.