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 será preciso 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. Ou seja, há duas maneiras de fazer chamadas à API.
[Preferido] 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 de 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 Interface REST para ver mais informações sobre como usar o REST.
Nomes de recursos
A maioria dos objetos na API é identificada pelas respectivas 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.
IDs compostos
Se o ID de um objeto não for exclusivo globalmente, um ID composto para esse objeto será criado incluindo o ID pai e um til (~).
Por exemplo, como um ID de anúncio do grupo de anúncios não é exclusivo globalmente, anexamos seu ID do objeto pai (grupo de anúncios) a ele para criar um ID composto exclusivo:
AdGroupId
de123
+~
+AdGroupAdId
de45678
= ID composto do anúncio do grupo de anúncios 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
Você precisa incluir um token de acesso OAuth2 no formato Authorization: Bearer YOUR_ACCESS_TOKEN
que identifique uma conta de administrador agindo em nome de um cliente ou um anunciante gerenciando diretamente a própria conta. Instruções para recuperar um token de acesso
podem ser encontradas no Guia do OAuth2. Um token de acesso é válido por uma hora após sua aquisição. Quando ele expirar, atualize o token de acesso para recuperar um novo. 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 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
Esse é o ID de cliente autorizado a ser usado na solicitação, sem hifens (-
). Se o acesso à conta do cliente for feito por uma conta de administrador, esse cabeçalho é obrigatório e precisa ser definido como o ID de cliente da conta de administrador.
https://googleads.googleapis.com/v15/customers/1234567890/campaignBudgets:mutate
Definir o 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.
id-de-cliente-vinculado
Esse cabeçalho só é usado 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 suas entidades para a conta B
por meio de um
ThirdPartyAppAnalyticsLink
.
Após a vinculação, um usuário da conta B
pode fazer chamadas de API para a 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 pela vinculação de terceiros à conta B
, em vez da relação entre a conta de administrador 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 aplicativos de terceiros que faz upload dos dados (contaB
).customer-id
: a conta do Google Ads para a qual os dados são enviados (contaA
).- Cabeçalho
login-customer-id
eAuthorization
: uma combinação de valores para identificar um usuário que tem acesso à contaB
.
Cabeçalhos de resposta
Os cabeçalhos a seguir (ou metadados finais de gRPC) são retornados com o corpo da resposta. Recomendamos que você registre esses valores para fins de depuração.
request-id
A request-id
é uma string que identifica exclusivamente essa solicitação.