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, algum conhecimento sobre a estrutura da chamada de 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:
Crie o corpo da solicitação como um buffer de protocolo.
Envie-o para o servidor usando HTTP/2.
Desserialize a resposta para um buffer de protocolo.
Interprete os resultados.
A maior parte da nossa documentação descreve como usar o gRPC.
Opcional:
Crie o corpo da solicitação como um objeto JSON.
Envie para o servidor usando HTTP 1.1.
Desserialize a resposta como um objeto JSON.
Interprete os resultados.
Consulte o guia da interface REST para mais informações sobre o uso do 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.
IDs compostos
Se o ID de um objeto não for globalmente exclusivo, um ID composto será criado adicionando o ID do pai e um til (~) antes.
Por exemplo, como um ID de anúncio de 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
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. 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.
Observe que nossas bibliotecas de cliente atualizam automaticamente os tokens expirados.
Se você encontrar erros de autorização, verifique se está usando as credenciais corretas e se tem permissões suficientes. Um erro USER_PERMISSION_DENIED indica que o usuário autenticado talvez não tenha acesso à conta do cliente especificada na solicitação. Consulte Níveis de acesso do Google Ads para mais detalhes sobre como gerenciar permissões.
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 hifens (-). 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. Se você não incluir login-customer-id ao
fazer a autenticação por uma conta de administrador, isso vai resultar em um
erro AuthorizationError.USER_PERMISSION_DENIED. Consulte Erros comuns para mais informações sobre esse tipo de erro.
https://googleads.googleapis.com/v24/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.
linked-customer-id
O cabeçalho é obrigatório e usado por parceiros (como provedores de análise de apps de terceiros ou parceiros de dados) ao agir em uma conta vinculada do Google Ads. Esse cabeçalho precisa especificar o ID de cliente da conta do Google Ads que tem o link do produto.
Considere o cenário em que um parceiro precisa fazer chamadas de API para uma conta do Google Ads com base em uma vinculação de produto.
- Anunciante: a conta do Google Ads gerenciada ou atualizada pela chamada de API. O ID da conta do anunciante é especificado na solicitação. Em REST, esse é o parâmetro de caminho
customerId(por exemplo,customers/1111111111/...). Em gRPC, esse é o campocustomer_idna solicitação. - Parceiro: a conta do parceiro (por exemplo, um provedor de análise de apps de terceiros ou um parceiro de dados).
- Conta vinculada: a conta do Google Ads que tem uma vinculação de produto estabelecida com o parceiro, concedendo a ele acesso ao anunciante.
Um usuário com acesso ao parceiro faz chamadas de API para agir em entidades no anunciante (por exemplo, para fazer upload de conversões ou gerenciar listas de usuários). A conta vinculada pode ser o próprio anunciante ou uma conta de administrador dele.
Os cabeçalhos de solicitação precisam ser definidos da seguinte maneira:
Authorization: um token OAuth2 para um usuário que tem acesso ao Partner.developer-token: o token de desenvolvedor do aplicativo da API, geralmente associado ao parceiro.login-customer-id: o ID de cliente do parceiro. O usuário autenticado precisa ter acesso a essa conta.linked-customer-id: o ID de cliente da conta vinculada. Esse cabeçalho indica que a autorização desta solicitação depende da vinculação de produtos da conta vinculada com o parceiro.
Há dois cenários de vinculação:
- Se o anunciante tiver um link direto de produto com o parceiro, a conta vinculada será o anunciante, e
linked-customer-idprecisará ser definido como o ID de cliente do anunciante. - Se o anunciante for gerenciado por uma conta de administrador que tenha uma vinculação de produto com o parceiro, a conta vinculada será a conta de administrador, e
linked-customer-idprecisará ser definido como o ID de cliente do administrador.
Exemplo 1: link direto
Se o anunciante 1111111111 tiver um link direto com o parceiro 2222222222 e a chamada de API segmentar customers/1111111111/...:
Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 1111111111
Exemplo 2: link do administrador
Se o anunciante 1111111111 for gerenciado pelo gerente 3333333333, o gerente 3333333333 terá um link com o parceiro 2222222222, e a chamada de API vai segmentar customers/1111111111/...:
Authorization: Bearer YOUR_ACCESS_TOKEN
developer-token: YOUR_DEVELOPER_TOKEN
login-customer-id: 2222222222
linked-customer-id: 3333333333
Cabeçalhos de resposta
Os seguintes cabeçalhos (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 a solicitação de forma exclusiva.