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.
[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.
[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.
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.
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:
AdGroupIdde123+~+AdGroupAdIdde45678= ID do anúncio do grupo de anúncios composto de123~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.
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.
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 (contaB).customer-id: a conta do Google Ads para a qual os dados são enviados (contaA).- Cabeçalho
login-customer-ideAuthorization: uma combinação de valores para identificar um usuário que tem acesso à contaB.
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.