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 das 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 por suas strings de nome de recurso. Esses 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 é 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:
AdGroupIdde123+~+AdGroupAdIdde45678= 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 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/v17/customers/1234567890/campaignBudgets:mutate
A configuração de login-customer-id é equivalente à escolha de uma conta na
interface do Google Ads após fazer login ou clicar na imagem do perfil no canto
superior direito. 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 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-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 after-metadata) são retornadas 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 maneira exclusiva.