Autenticação e autorização

Assim como outras APIs do Google, a API Google Ads usa o protocolo OAuth 2.0 para autenticação e autorização. O OAuth 2.0 permite que seu app cliente da API Google Ads acesse a conta do Google Ads de um usuário sem precisar processar ou armazenar as informações de login dele.

Entenda o modelo de acesso do Google Ads

Para trabalhar de forma eficaz com a API Google Ads, é importante entender como funciona o modelo de acesso do Google Ads. Recomendamos que você leia o guia do modelo de acesso do Google Ads.

Fluxos de trabalho do OAuth

Há três fluxos de trabalho comuns usados ao trabalhar com a API Google Ads.

Fluxo da conta de serviço

Esse é o fluxo de trabalho recomendado se o seu não exigir interação humana. Esse fluxo de trabalho exige uma etapa de configuração em que o usuário adiciona uma conta de serviço à conta do Google Ads. Em seguida, o app pode usar as credenciais da conta de serviço para gerenciar a conta do Google Ads do usuário. Para configurar isso, crie e faça o download do arquivo de chave JSON no console do Google Cloud. Em seguida, copie google_ads_config.rb para seu diretório inicial e modifique-o para especificar o local do arquivo de chave da conta de serviço e o endereço de e-mail do usuário a ser representado:

  # You can also authenticate using a service account. If "keyfile" is
  # specified below, then service account authentication will be assumed and
  # the above authentication fields ignored. Read more about service account
  # authentication here:
  # https://developers.google.com/google-ads/api/docs/oauth/service-accounts
  # c.keyfile = 'path/to/keyfile.json'
  # c.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'

Se você preferir não armazenar essas informações em um arquivo e usar variáveis de ambiente, defina GOOGLE_ADS_JSON_KEY_FILE_PATH e GOOGLE_ADS_IMPERSONATED_EMAIL, respectivamente.

export GOOGLE_ADS_JSON_KEY_FILE_PATH="/path/to/your/service-account-key.json"
export GOOGLE_ADS_IMPERSONATED_EMAIL="your_email@email.com"

Também é possível transmitir as informações de maneira programática durante a execução usando a gem googleauth para criar credenciais de um arquivo JSON de conta de serviço:

require 'googleauth'
require 'google/ads/google_ads'

# Path to your service account key file
key_file = "/path/to/your/service-account-key.json"

# Define the scopes needed for the Google Ads API
scopes = ['https://www.googleapis.com/auth/adwords']

# Create service account credentials
credentials = Google::Auth::ServiceAccountCredentials.make_creds(
  json_key_io: File.open(key_file),
  scope: scopes
)

# Initialize the Google Ads API client with these credentials
client = Google::Ads::GoogleAds::Client.new do |config|
  config.developer_token = "YOUR_DEVELOPER_TOKEN"
  # Inject the service account credentials
  config.oauth2_client = credentials
end

Consulte o guia de fluxo de trabalho da conta de serviço para saber mais.

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

Esse fluxo de trabalho pode ser usado se você não puder usar contas de serviço. Esse fluxo de trabalho exige duas etapas de configuração:

  1. Conceda a um único usuário acesso a todas as contas que serão gerenciadas usando a API Google Ads. Uma abordagem comum é dar ao usuário uma conta de administrador da API Google Ads e vincular todas as contas do Google Ads a ela.
  2. O usuário executa uma ferramenta de linha de comando, como gcloud ou o exemplo de código GenerateUserCredentials, para autorizar seu app a gerenciar todas as contas do Google Ads em nome dele.

Para configurar as credenciais do OAuth 2.0 para Ruby, copie o arquivo google_ads_config.rb para seu diretório inicial e modifique-o para incluir seu token de desenvolvedor, ID do cliente, chave secreta do cliente e token de atualização:

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # Authentication tells the API that you are allowed to make changes to the
  # specific account you're trying to access.
  # The default method of authentication is to use a refresh token, client id,
  # and client secret to generate an access token.
  c.client_id = 'INSERT_CLIENT_ID_HERE'
  c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

O cliente lê automaticamente o arquivo de configuração do diretório inicial se for instanciado sem argumentos:

client = Google::Ads::GoogleAds::GoogleAdsClient.new

Como alternativa, se você preferir armazenar o arquivo em outro lugar, crie uma instância do cliente transmitindo o caminho para onde você guarda o arquivo:

client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')

Se você preferir não armazenar essas informações em um arquivo e usar variáveis de ambiente, defina cada uma delas:

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"

Você também pode transmitir as informações de forma programática no ambiente de execução:

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
end

Consulte o guia do fluxo de trabalho de autenticação de usuário único para saber mais.

Fluxo de autenticação multiusuário

Esse é o fluxo de trabalho recomendado se o app permitir que os usuários façam login e autorizem o app a gerenciar as contas do Google Ads em nome deles. Seu app cria e gerencia as credenciais de usuário do OAuth 2.0. Esse fluxo de trabalho pode ser configurado de maneira semelhante ao fluxo de usuário único, mas com o login_customer_id também especificado.

Recomendamos que você use um arquivo de configuração. Copie o arquivo google_ads_config.rb para seu diretório inicial e modifique-o para incluir seu token de desenvolvedor, ID do cliente, chave secreta do cliente, token de atualização e ID do cliente:

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # Authentication tells the API that you are allowed to make changes to the
  # specific account you're trying to access.
  # The default method of authentication is to use a refresh token, client id,
  # and client secret to generate an access token.
  c.client_id = 'INSERT_CLIENT_ID_HERE'
  c.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  c.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'

  # Required for manager accounts only: Specify the login customer ID used to
  # authenticate API calls. This will be the customer ID of the authenticated
  # manager account. If you need to use different values for this field, then
  # make sure fetch a new copy of the service after each time you change the
  # value.
  # c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'

O cliente lê automaticamente o arquivo de configuração do diretório inicial se for instanciado sem argumentos:

client = Google::Ads::GoogleAds::GoogleAdsClient.new

Como alternativa, se você preferir armazenar o arquivo em outro lugar, crie uma instância do cliente transmitindo o caminho para onde você guarda o arquivo:

client = Google::Ads::GoogleAds::GoogleAdsClient.new('path/to/google_ads_config.rb')

Se você preferir não armazenar essas informações em um arquivo e usar variáveis de ambiente, defina cada uma delas:

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
export GOOGLE_ADS_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"
export GOOGLE_ADS_LOGIN_CUSTOMER_ID="INSERT_LOGIN_CUSTOMER_ID_HERE"

Você também pode transmitir as informações de forma programática no ambiente de execução:

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  config.client_id = 'INSERT_CLIENT_ID_HERE'
  config.client_secret = 'INSERT_CLIENT_SECRET_HERE'
  config.refresh_token = 'INSERT_REFRESH_TOKEN_HERE'
  config.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
end

Consulte o guia do fluxo de trabalho de autenticação multiusuário para saber mais. A biblioteca de cliente Ruby inclui um exemplo de código para referência. O GenerateUserCredentials é um exemplo de código de linha de comando que ilustra como obter a autenticação do usuário durante a execução para gerenciar as contas do Google Ads em nome dele. Use este exemplo de código como referência para criar apps de computador que exigem autenticação do usuário.

E se meu usuário gerenciar várias contas?

É comum um usuário gerenciar mais de uma conta do Google Ads, seja por acesso direto a elas ou por uma conta de administrador do Google Ads. A biblioteca de cliente Ruby fornece os exemplos de código a seguir que ilustram como lidar com esses casos.

  1. O exemplo de código GetAccountHierarchy mostra como recuperar a lista de todas as contas em uma conta de administrador do Google Ads.
  2. O exemplo de código ListAccessibleCustomers mostra como recuperar a lista de todas as contas a que um usuário tem acesso direto. Essas contas podem ser usadas como valores válidos para a configuração LoginCustomerId.

Application Default Credentials

A biblioteca de cliente Ruby também oferece suporte à autenticação com credenciais padrão do aplicativo (ADC). Ele permite definir as credenciais padrão do aplicativo sem precisar configurar as informações do OAuth 2.0 na configuração do aplicativo.

Isso é particularmente útil para desenvolvimento local ou com diferentes APIs do Google, já que é possível reutilizar as mesmas credenciais, desde que elas acessem os escopos corretos do OAuth 2.0.

Para a API Google Ads, verifique se as credenciais padrão do aplicativo podem acessar o escopo https://www.googleapis.com/auth/adwords do OAuth 2.0.

Para usar as credenciais padrão do aplicativo, recomendamos usar a ferramenta de linha de comando do Google Cloud e fazer a autenticação para o ADC:

gcloud auth application-default login

Esse comando vai abrir um navegador da Web para concluir o fluxo de autenticação da sua Conta do Google. Depois de autorizado, ele armazena as credenciais em um local padrão. Em seguida, atualize o aplicativo para usar o ADC.

Recomendamos que você use um arquivo de configuração. Copie o arquivo google_ads_config.rb para seu diretório inicial, adicione seu token de desenvolvedor e defina use_application_default_credentials como "true":

  # The developer token is required to authenticate that you are allowed to
  # make API calls.
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'

  # You can also authenticate using Application Default Credentials (ADC)
  # To understand how ADC discovers credentials in a given environment,
  # see: https://developers.google.com/identity/protocols/application-default-credentials.
  c.use_application_default_credentials = true

Se você preferir não armazenar essas informações em um arquivo e usar variáveis de ambiente, defina GOOGLE_ADS_DEVELOPER_TOKEN e GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS:

export GOOGLE_ADS_DEVELOPER_TOKEN="INSERT_DEVELOPER_TOKEN_HERE"
export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS="true"

Você também pode transmitir as informações de forma programática no ambiente de execução. Ao inicializar o cliente no seu código Ruby, não forneça credenciais OAuth2 explícitas. A biblioteca detecta e usa automaticamente as credenciais configuradas pela ferramenta de linha de comando do Google Cloud. Você ainda precisa especificar seu token de desenvolvedor.

# Initialize the client. It will automatically use Application Default Credentials.
client = Google::Ads::GoogleAds::Client.new do |config|
  # Developer Token is mandatory for the Google Ads API.
  config.developer_token = "YOUR_DEVELOPER_TOKEN"

  # Optional: Specify a login customer ID if you are accessing accounts
  # through a manager account.
  # config.login_customer_id = "YOUR_LOGIN_CUSTOMER_ID"

  # Do NOT include oauth2_client_id, oauth2_client_secret, or oauth2_refresh_token here.
end

Consulte a página de configuração para mais detalhes sobre as opções disponíveis para configurar a biblioteca de cliente Ruby.