O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Autenticação e autorização

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 o 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.

Entender o modelo de acesso do Google Ads

Para trabalhar de forma eficaz com a API Google Ads, entenda como funciona o modelo de acesso do Google Ads. Consulte 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 fluxo de trabalho não exigir nenhuma interação humana. Esse fluxo de trabalho requer uma etapa de configuração, em que o usuário adiciona uma conta de serviço à conta do Google Ads. 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, 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 opcional do usuário que será personificado ao usar a delegação em todo o domínio do Google Workspace):

# 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'
# Optional unless using Google Workspace domain-wide delegation:
c.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'

Se você preferir não armazenar essas informações em um arquivo e quiser usar variáveis de ambiente, defina GOOGLE_ADS_JSON_KEY_FILE_PATH (e GOOGLE_ADS_IMPERSONATED_EMAIL, que é opcional):

export GOOGLE_ADS_JSON_KEY_FILE_PATH="/path/to/your/service-account-key.json"
# Optional unless using Google Workspace domain-wide delegation:
export GOOGLE_ADS_IMPERSONATED_EMAIL="your_email@email.com"

Também é possível transmitir o caminho do arquivo de chave da conta de serviço (e o e-mail de identidade temporária opcional) de maneira programática no ambiente de execução:

require 'google/ads/google_ads'

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.keyfile = '/path/to/your/service-account-key.json'
  # Optional unless using Google Workspace domain-wide delegation:
  config.impersonate = 'INSERT_EMAIL_ADDRESS_TO_IMPERSONATE_HERE'
end

Como alternativa, use a gem googleauth para criar credenciais de conta de serviço e transmitir credentials.updater_proc para config.authentication:

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 = File.open(key_file) do |io|
  Google::Auth::ServiceAccountCredentials.make_creds(
    json_key_io: io,
    scope: scopes
  )
end

# Initialize the Google Ads API client with these credentials.
client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  # Inject the service account credential updater proc.
  config.authentication = credentials.updater_proc
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 requer duas etapas de configuração:

Dê 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 acesso a uma conta de administrador da API Google Ads e vincular todas as contas do Google Ads a essa conta de administrador.
O usuário executa uma ferramenta de linha de comando, como a ferramenta de linha de comando do Google Cloud ou o exemplo de código GenerateUserCredentials, para autorizar seu app a gerenciar todas as contas do Google Ads em nome dele.

As credenciais do OAuth 2.0 podem ser configuradas para Ruby copiando o arquivo google_ads_config.rb para seu diretório inicial e modificando-o para incluir o ID do cliente, a chave secreta do cliente e o token de atualização:

# 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 instanciado sem argumentos:

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

Se preferir armazenar o arquivo em outro lugar, instancie o cliente transmitindo o caminho para onde você mantém esse 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_CLIENT_ID="INSERT_CLIENT_ID_HERE"
export GOOGLE_ADS_CLIENT_SECRET="INSERT_CLIENT_SECRET_HERE"
export GOOGLE_ADS_REFRESH_TOKEN="INSERT_REFRESH_TOKEN_HERE"

Também é possível transmitir as informações de forma programática no ambiente de execução:

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  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, com o login_customer_id também especificado.

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

# 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 to 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 instanciado sem argumentos:

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

Se preferir armazenar o arquivo em outro lugar, instancie o cliente transmitindo o caminho para onde você mantém esse 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_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"

Também é possível transmitir as informações de forma programática no ambiente de execução:

client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  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 do Ruby inclui um exemplo de código para referência. O exemplo de código de linha de comando GenerateUserCredentials ilustra como conseguir a autenticação do usuário no momento da execução para gerenciar as contas do Google Ads em nome dele. Use este exemplo de código como referência para criar apps para computador que exigem autenticação do usuário.

Gerenciar várias contas

É comum que um usuário gerencie mais de uma conta do Google Ads, seja por acesso direto às contas ou por uma conta de administrador do Google Ads. A biblioteca de cliente do Ruby fornece os seguintes exemplos de código que ilustram como lidar com esses casos:

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

Application Default Credentials

A biblioteca de cliente do Ruby (v36.1.0 e mais recentes) também é compatível com a autenticação com o Application Default Credentials (ADC). Ele permite definir as credenciais padrão para o aplicativo sem precisar configurar as informações do OAuth 2.0 na configuração do aplicativo.

Isso é útil principalmente para o desenvolvimento local ou para o desenvolvimento em diferentes APIs do Google, já que é possível reutilizar as mesmas credenciais, desde que elas possam acessar os escopos necessários do OAuth 2.0.

Para a API Google Ads, verifique se o Application Default Credentials pode acessar o escopo do OAuth 2.0 https://www.googleapis.com/auth/adwords.

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

gcloud auth application-default login

Esse comando abre 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.

Copie o arquivo google_ads_config.rb para o diretório inicial e defina use_application_default_credentials como true:

# 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_USE_APPLICATION_DEFAULT_CREDENTIALS:

export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS="true"

Também é possível transmitir as informações de forma programática no ambiente de execução. Ao inicializar o cliente no código Ruby, defina config.use_application_default_credentials = true e não forneça credenciais explícitas do OAuth 2.0. A biblioteca detecta e usa automaticamente as credenciais configuradas pela ferramenta de linha de comando do Google Cloud:

# Initialize the client using Application Default Credentials.
client = Google::Ads::GoogleAds::GoogleAdsClient.new do |config|
  config.use_application_default_credentials = true

  # 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 client_id, client_secret, or 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 do Ruby.