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.
[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.
[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.
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.
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
de123
+~
+AdGroupAdId
de45678
= anúncio composto ID de anúncio do grupo de123~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.
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.
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 (contaB
).customer-id
: a conta do Google Ads para a qual os dados são enviados (contaA
).- Cabeçalhos
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 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.