Authentication

Neste documento, descrevemos como autenticar na API Ad Manager. A forma de autenticação depende da interface usada e do ambiente em que seu código está sendo executado, mas todas as solicitações de API precisam incluir um token de acesso com um escopo da API Ad Manager.

As bibliotecas de cliente do Ad Manager usam Application Default Credentials para gerar tokens de acesso com escopos da API Ad Manager. Este guia mostra como configurar o Application Default Credentials.

Se você não estiver usando uma biblioteca de cliente, ainda precisará criar credenciais e usá-las para autorizar suas solicitações.

Para mais informações sobre autenticação e autorização, consulte o guia Como usar o OAuth 2.0.

Determinar seu tipo de autenticação

Tipo de autenticação Descrição
Conta de serviço Escolha essa opção se quiser autenticar como uma conta dedicada, e não como uma pessoa específica.
Saiba mais.
Aplicativo da Web Escolha essa opção se quiser autenticar como qualquer usuário que conceda permissão ao seu aplicativo para acessar os dados do Ad Manager.
Saiba mais
Desenvolvimento local Escolha essa opção se quiser autenticar como sua própria Conta do Google ou uma conta de serviço do seu ambiente de desenvolvimento local.

Ativar a API Ad Manager

  1. Ative a API Ad Manager no seu projeto do Console de APIs do Google Cloud.

  2. Se for solicitado, selecione um projeto ou crie um novo.

Criar credenciais

Clique na guia do seu tipo de autenticação e siga as instruções para criar suas credenciais:

Conta de serviço

No Google Cloud

Para autenticar uma carga de trabalho em execução no Google Cloud, use as credenciais da conta de serviço anexada ao recurso de computação em que seu código está sendo executado.

Por exemplo, é possível anexar uma conta de serviço a uma instância de máquina virtual (VM) do Compute Engine, a um serviço do Cloud Run ou a um job do Dataflow. Essa abordagem é o método de autenticação preferencial para códigos em execução em um recurso de computação do Google Cloud.

Para informações sobre quais recursos podem ser anexados a uma conta de serviço e ajuda para anexar a conta de serviço ao recurso, consulte a documentação sobre como anexar uma conta de serviço.

No local ou em outro provedor de nuvem

O método preferencial para configurar a autenticação de fora do Google Cloud é usar a federação de identidade da carga de trabalho. Você cria um arquivo de configuração de credenciais e define a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS para apontar para ele. Essa abordagem é mais segura do que criar uma chave de conta de serviço.

Se não for possível configurar a federação de identidade da carga de trabalho, crie uma conta de serviço e uma chave para ela:

  1. Abra a página de credenciais do Console de APIs do Google.

  2. Na página "Credenciais", selecione Criar credenciais e escolha Conta de serviço.

  3. Clique no endereço de e-mail da conta de serviço para a qual você quer criar uma chave.

  4. Clique na guia Chaves.

  5. Clique no menu suspenso Adicionar chave e selecione Criar nova chave.

  6. Selecione JSON como o Tipo de chave e clique em Criar.

  7. Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo JSON.

Linux ou macOS

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Aplicativo da Web

  1. Abra a página de credenciais do Console de APIs do Google.

  2. Se solicitado, selecione o projeto em que você ativou a API Ad Manager.

  3. Na página "Credenciais", selecione Criar credenciais e depois ID do cliente OAuth.

  4. Selecione o tipo de aplicativo Aplicativo da Web.

  5. Preencha o formulário e clique em Criar. Os aplicativos que usam linguagens e frameworks como PHP, Java, Python, Ruby e .NET precisam especificar URIs de redirecionamento autorizados. Os URIs de redirecionamento são os endpoints para os quais o servidor OAuth 2.0 pode enviar respostas. Esses endpoints precisam obedecer às regras de validação do Google.

  6. Depois de criar as credenciais, faça o download do arquivo client_secret.json. Armazene o arquivo com segurança em um local que só o aplicativo possa acessar.

Siga as etapas para receber tokens de acesso do OAuth 2.0.

Desenvolvimento local

Configure o Application Default Credentials (ADC) no ambiente local.

Instale a CLI do Google Cloud e inicialize-a executando o seguinte comando:

gcloud init

Crie credenciais de autenticação local para sua Conta do Google e defina o ID do projeto como um projeto em que a API Ad Manager está ativada:

gcloud auth application-default login --scopes="https://www.googleapis.com/auth/admanager"
gcloud auth application-default set-quota-project PROJECT_ID

Como alternativa, autentique-se como uma conta de serviço definindo a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo de chave.

Linux ou macOS

export GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Windows

set GOOGLE_APPLICATION_CREDENTIALS=KEY_FILE_PATH

Configurar sua rede do Ad Manager

Conta de serviço

  1. Acesse sua rede do Ad Manager.
  2. Clique na guia Administrador.
  3. Verifique se o acesso à API está ativado.
  4. Clique no botão Adicionar um usuário da conta de serviço.
  5. Preencha o formulário usando o e-mail da conta de serviço. O usuário da conta de serviço precisa ser adicionado às funções e equipes adequadas para a integração da API.
  6. Clique no botão Salvar. Uma mensagem vai aparecer confirmando a adição da sua conta de serviço.
  7. Para ver os usuários da conta de serviço, acesse a guia "Usuários" e clique no filtro Conta de serviço.

Aplicativo da Web

  1. Acesse sua rede do Ad Manager.
  2. Clique na guia Administrador.
  3. Verifique se o acesso à API está ativado.

Desenvolvimento local

  1. Acesse sua rede do Ad Manager.
  2. Clique na guia Administrador.
  3. Verifique se o acesso à API está ativado.

Sem uma biblioteca de cliente

Se você não estiver usando uma biblioteca de cliente, ainda recomendamos usar uma biblioteca OAuth2 para autenticação.

Para instruções detalhadas sobre como conseguir tokens de acesso, consulte Como usar o OAuth2 com as APIs do Google.

Tokens de acesso

Inclua o token de acesso em uma solicitação à API adicionando um parâmetro de consulta access_token ou um valor de cabeçalho HTTP Authorization Bearer. Quando possível, o cabeçalho HTTP é preferível, porque as strings de consulta tendem a ficar visíveis nos registros do servidor.

Exemplo:

GET /v1/networks/1234
Host: admanager.googleapis.com
Authorization: Bearer ya29.a0Ad52N3_shYLX

GET https://admanager.googleapis.com/v1/networks/1234?access_token=1/fFAGRNJru1FTz70BzhT3Zg

Escopo

Cada token de acesso está associado a um ou mais escopos. Um escopo controla o conjunto de recursos e operações permitidas por um token de acesso. A API do Ad Manager tem dois escopos. Recomendamos usar o escopo admanager.readonly mais restrito se o aplicativo não precisar gravar dados.

Escopo Permissões
https://www.googleapis.com/auth/admanager Veja e gerencie suas campanhas no Google Ad Manager.
https://www.googleapis.com/auth/admanager.readonly Confira suas campanhas e dados no Google Ad Manager.