Estrutura de chamada de API

IDs compostos

Se o ID de um objeto não for globalmente exclusivo, um ID composto para esse objeto será construído adicionando o ID pai e um til (~).

Por exemplo, como um ID de anúncio do grupo de anúncios não é globalmente exclusivo, adicionamos o ID do objeto pai (grupo de anúncios) para criar um ID composto exclusivo:

• AdGroupId de 123 + ~ + AdGroupAdId de 45678 = ID composto do anúncio do grupo de anúncios de 123~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 do OAuth2 no formato Authorization: Bearer YOUR_ACCESS_TOKEN que identifica 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 do OAuth2. Um token de acesso é válido por uma hora após a aquisição. Quando ele expirar, atualize-o para conseguir um novo. 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 pode não ter acesso à conta de cliente especificada na solicitação. Consulte Níveis de acesso do Google Ads para 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 no formato 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 de cliente for por uma conta de administrador, esse cabeçalho será obrigatório e precisará ser definido como o ID de cliente da conta de administrador. Se você não incluir login-customer-id ao autenticar por uma conta de administrador, isso resultará em um erro AuthorizationError.USER_PERMISSION_DENIED. Consulte Erros comuns para mais informações sobre esse tipo de erro. Para uma explicação detalhada de como o acesso à conta é resolvido, consulte o guia do modelo de acesso do OAuth.

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, ele será definido como o cliente operacional por padrão.

linked-customer-id

Esse 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 um link de produto.

• Anunciante: a conta do Google Ads que está sendo gerenciada ou atualizada pela chamada de API. O ID da conta do anunciante é especificado na solicitação. No REST, esse é o parâmetro de caminho customerId (por exemplo, customers/1111111111/...) e, no gRPC, esse é o campo customer_id na solicitação.
• Parceiro: a conta de parceiro (por exemplo, um provedor de análise de apps de terceiros ou parceiro de dados).
• Conta vinculada: a conta do Google Ads que tem um link de produto estabelecido com o parceiro, concedendo acesso ao anunciante.

Um usuário que tem 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 do anunciante.

Os cabeçalhos de solicitação precisam ser definidos da seguinte maneira:

• Authorization: um token do OAuth2 para um usuário que tem acesso ao parceiro.
• developer-token: o token de desenvolvedor do aplicativo da API, normalmente 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 para essa solicitação depende do link de produto da conta vinculada com o parceiro.

Há dois cenários de vinculação:

• Se o anunciante tiver um link de produto direto com o parceiro, a conta vinculada será o anunciante, e linked-customer-id precisará ser definido como o ID de cliente do anunciante.
• Se o anunciante for gerenciado por uma conta de administrador que tenha um link de produto com o parceiro, a conta vinculada será a conta de administrador, e linked-customer-id precisará 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 estiver segmentando 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 administrador 3333333333, o administrador 3333333333 tiver um link com o parceiro 2222222222 e a chamada de API estiver segmentando 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 cabeçalhos a seguir (ou metadados finais do gRPC) 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 exclusivamente essa solicitação.