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á saber os detalhes da solicitação subjacente. No entanto, ter algum conhecimento sobre a estrutura de chamada da 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:

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 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 do REST.

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

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 os Nomes de recursos da interface REST para ver a estrutura deles.

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

Por exemplo, como um ID de anúncio do 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 composto do grupo de anúncios 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 do OAuth2 no formato Authorization: Bearer YOUR_ACCESS_TOKEN que identifica 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 recebido. Quando ele expirar, atualize-o 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 exclusivamente um desenvolvedor da API Google Ads. Um exemplo de string de token de desenvolvedor é ABcdeFGH93KL-NOPQ_STUv. O token de desenvolvedor precisa ser incluído na forma de developer-token : ABcdeFGH93KL-NOPQ_STUv.

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.

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

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

Observação: é possível recuperar a lista de contas que são acessíveis diretamente com suas credenciais do OAuth enviando 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 retornada.

linked-customer-id

Esse cabeçalho é usado apenas por [provedores de análise de apps 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 para a conta B usando um ThirdPartyAppAnalyticsLink. Depois de vinculada, um usuário da conta B pode fazer chamadas de API na conta A, sujeito às permissões fornecidas pela vinculação. Nesse caso, as permissões de chamada de API para a conta A são determinadas pela vinculação de terceiros à conta B, e não pela relação de conta de administrador usada em outras chamadas de API.

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

• linked-customer-id: a conta de análise de apps de terceiros que faz upload dos dados (conta B).
• customer-id: a conta do Google Ads em que 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 seguintes cabeçalhos (ou metadados finais do grpc) 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 a solicitação de forma exclusiva.