Fluxo de trabalho de autenticação de usuário único

Observação: este guia pressupõe que você esteja familiarizado com o modelo de acesso do Google Ads. Se não estiver, recomendamos ler o Guia do modelo de acesso do Google Ads para se familiarizar com os conceitos. Você também precisa configurar suas credenciais do OAuth usando o mesmo projeto na nuvem do Google Cloud em que ativou a API Google Ads e solicitou um nível de acesso adequado para que a API Google Ads funcione corretamente.

Atenção: o Google recomenda usar o fluxo de trabalho da conta de serviço em vez do fluxo de trabalho de autenticação de usuário único. Use o fluxo de trabalho de autenticação de usuário único somente quando as contas de serviço não puderem ser usadas.

Semelhante ao fluxo de trabalho da conta de serviço, o fluxo de autenticação de usuário único usa os recursos de autorização e gerenciamento de usuários oferecidos pela interface do Google Ads para conceder ao app acesso a todas as contas necessárias. Esse fluxo de trabalho de autenticação tem duas etapas:

• Você concede a um único usuário acesso a todas as contas do Google Ads que precisam ser gerenciadas pelo app.
• O usuário autoriza seu app a gerenciar as contas do Google Ads em nome dele, concedendo acesso a todas as contas do Google Ads.

Como há apenas um usuário envolvido, você pode usar ferramentas como a gcloud CLI ou o GenerateUserCredential code example em vez de criar seu próprio fluxo de autenticação de usuário do OAuth 2.0.

Um caso de uso relacionado para esse fluxo de trabalho é quando suas contas podem ser acessadas por alguns logins de usuário (por exemplo, de 3 a 4 usuários). Assim, o esforço de desenvolvimento para criar um fluxo de trabalho de autenticação multiusuário do OAuth completo não é justificado quando comparado ao esforço para obter autorização para 3 a 4 usuários usando uma ferramenta de linha de comando, como a CLI gcloud.

Desvantagens

Há algumas desvantagens nesse fluxo em comparação com o fluxo de trabalho da conta de serviço:

1. O fluxo de trabalho de autenticação do usuário exige que você crie um ID do cliente e uma chave secreta do OAuth 2.0 no console do Google Cloud, o que exige mais etapas de configuração do que criar uma conta de serviço e uma chave.
2. Se o usuário autorizado sair da equipe ou da empresa, seu app poderá parar de funcionar se você remover o usuário das suas contas ou desativar a conta de usuário. As contas de serviço não estão vinculadas a usuários individuais, portanto, esse risco é evitado.
3. O usuário que autoriza a conta do Google Ads precisa ativar as chaves de acesso na Conta do Google para se defender contra a violação da Conta do Google devido à segurança inadequada, malware ou phishing. As contas de serviço não precisam ativar as chaves de acesso e são menos vulneráveis a esse problema, já que alguns desses modos de ataque não se aplicam diretamente a elas.

Gerar credenciais

Observação: este guia usa um app para computador como o tipo de app OAuth ao criar as credenciais do OAuth, já que ele funciona melhor com a CLI gcloud. Ao usar o fluxo de trabalho de autenticação de usuário único, esse tipo de app OAuth pode ser usado independentemente do tipo de aplicativo que você está criando. Se você escolher Aplicativo da Web, será necessário usar o OAuth 2.0 Playground para gerar um token de atualização.

1. Configure uma tela de permissão do OAuth para seu aplicativo e adicione https://www.googleapis.com/auth/adwords como um escopo do OAuth 2.0. Consulte Como configurar a tela de permissão do OAuth para mais detalhes.

2. Crie um ID do cliente e uma chave secreta do cliente seguindo as instruções. Depois de criar o cliente OAuth 2.0, faça o download do arquivo JSON do cliente clicando no botão Fazer o download do JSON na caixa de diálogo de confirmação. Salve o arquivo como credentials.json.

3. Identifique uma conta de usuário que tenha acesso a todas as contas do Google Ads que você quer gerenciar usando seu app. Se houver contas com acesso ausente, conceda acesso à conta a esse usuário.

4. Faça o download e instale a CLI gcloud. Depois de instalada, verifique se a ferramenta funciona corretamente executando o comando gcloud version em um prompt de linha de comando. A resposta será semelhante a:

   gcloud version

   Google Cloud SDK 492.0.0
   alpha 2024.09.06
   beta 2024.09.06
   bq 2.1.8
   bundled-python3-unix 3.11.9
   core 2024.09.06
   enterprise-certificate-proxy 0.3.2
   gcloud-crc32c 1.0.0
   

5. Gere um token de atualização do OAuth 2.0 executando a ferramenta da CLI gcloud com o arquivo credentials.json da etapa anterior. É necessário transmitir --client-id-file para que o token de atualização seja emitido no projeto do Console de APIs do Google, em vez do projeto padrão da CLI gcloud:

   gcloud auth application-default login \
     --scopes=https://www.googleapis.com/auth/adwords,https://www.googleapis.com/auth/cloud-platform \
     --client-id-file=PATH_TO_CREDENTIALS_JSON

6. O comando gcloud abre uma janela de login da Conta do Google em uma nova janela do navegador e orienta você pelas etapas de autenticação do OAuth 2.0. Faça login como o usuário selecionado nas etapas anteriores. Se o app não for verificado, uma tela de aviso poderá aparecer. Nesses casos, é seguro clicar no link Avançado e na opção Acessar PROJECT_NAME (não seguro).

7. Depois de verificar os escopos, clique no botão Continuar para conceder permissão. O navegador navega até https://cloud.google.com/sdk/auth_success, indicando que a autenticação foi bem-sucedida. A página mostra a seguinte mensagem:

   Authorization code granted. Close this tab.

   O comando gcloud imprime a seguinte mensagem:

   Credentials saved to file: [/****/.config/gcloud/application_default_credentials.json]
   

   Abra o arquivo application_default_credentials.json. O conteúdo dele é semelhante ao seguinte:

   {
     "account": "",
     "client_id": "******.apps.googleusercontent.com",
     "client_secret": "******",
     "refresh_token": "******",
     "type": "authorized_user",
     "universe_domain": "googleapis.com"
   }
   

Configuração da biblioteca de cliente

Selecione a guia correspondente à sua linguagem de programação para instruções sobre como configurar a biblioteca de cliente. Se o usuário autorizado acessar contas de cliente por meio de uma conta de administrador do Google Ads, defina login-customer-id (ou loginCustomerId) como o ID de cliente de 10 dígitos dessa conta de administrador sem hifens.

Java

Configure as seguintes chaves no arquivo ads.properties.

api.googleads.clientId=INSERT_OAUTH2_CLIENT_ID_HERE
api.googleads.clientSecret=INSERT_OAUTH2_CLIENT_SECRET_HERE
api.googleads.refreshToken=INSERT_OAUTH2_REFRESH_TOKEN_HERE
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

Consulte o guia de configuração para outras opções.

.NET

Defina as credenciais do OAuth 2.0 na instância GoogleAdsConfig e use-a para inicializar o objeto GoogleAdsClient.

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.APPLICATION,
    OAuth2ClientId = "INSERT_OAUTH2_CLIENT_ID_HERE",
    OAuth2ClientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE",
    OAuth2RefreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE",
};
GoogleAdsClient client = new GoogleAdsClient(config);

Consulte o guia de configuração para outras opções.

Python

Configure as seguintes chaves no arquivo google-ads.yaml.

client_id: INSERT_OAUTH2_CLIENT_ID_HERE
client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
refresh_token: INSERT_OAUTH2_REFRESH_TOKEN_HERE
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
use_proto_plus: True

Consulte o guia de configuração para outras opções.

PHP

Configure as seguintes chaves no arquivo google_ads_php.ini.

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

[OAUTH2]
clientId = "INSERT_OAUTH2_CLIENT_ID_HERE"
clientSecret = "INSERT_OAUTH2_CLIENT_SECRET_HERE"
refreshToken = "INSERT_OAUTH2_REFRESH_TOKEN_HERE"

Consulte o guia de configuração para outras opções.

Ruby

Configure as seguintes chaves no seu google_ads_config.rb arquivo.

Google::Ads::GoogleAds::Config.new do |c|
  c.client_id = 'INSERT_OAUTH2_CLIENT_ID_HERE'
  c.client_secret = 'INSERT_OAUTH2_CLIENT_SECRET_HERE'
  c.refresh_token = 'INSERT_OAUTH2_REFRESH_TOKEN_HERE'
  c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

Consulte o guia de configuração para outras opções.

Perl

Configure as seguintes chaves no arquivo googleads.properties.

clientId=INSERT_OAUTH2_CLIENT_ID_HERE
clientSecret=INSERT_OAUTH2_CLIENT_SECRET_HERE
refreshToken=INSERT_OAUTH2_REFRESH_TOKEN_HERE
loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

Consulte o guia de configuração para outras opções.

curl

Comece usando um cliente HTTP para buscar um token de acesso do OAuth 2.0. Este guia usa o comando curl.

curl \
  --data "grant_type=refresh_token" \
  --data "client_id=CLIENT_ID" \
  --data "client_secret=CLIENT_SECRET" \
  --data "refresh_token=REFRESH_TOKEN" \
  https://oauth2.googleapis.com/token

Você pode usar o token de acesso nas chamadas de API. O exemplo a seguir mostra como executar um relatório de campanha usando o método GoogleAdsService.SearchStream para recuperar as campanhas na sua conta. Este guia não aborda os detalhes da geração de relatórios.

curl -i -X POST \
  https://googleads.googleapis.com/v26/customers/CUSTOMER_ID/googleAds:searchStream \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "login-customer-id: LOGIN_CUSTOMER_ID" \
  --data-binary "@query.json"

O conteúdo de query.json é o seguinte:

{
  "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}