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

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 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 do usuário.

Entender o modelo de acesso do Google Ads

Para trabalhar de maneira eficaz com a API Google Ads, é necessário entender como o modelo de acesso do Google Ads funciona. Recomendamos a leitura do 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 ele 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. 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 o 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 no tempo de execução usando a gem googleauth para criar credenciais de um arquivo JSON da 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 do 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:

Conceda a um único usuário acesso a todas as contas a serem gerenciadas usando a API Google Ads. Uma abordagem comum é conceder o usuário 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 gcloud ou o GenerateUserCredentials exemplo de código para autorizar o 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 google_ads_config.rb para o diretório inicial e modificando-o para incluir o token de desenvolvedor, o ID do cliente, a chave secreta do cliente e o 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 vai ler 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, instancie o cliente transmitindo o caminho para o local em que 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_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"

Também é possível transmitir as informações de maneira programática no tempo 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. O 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 especificado também.

Recomendamos o uso de um arquivo de configuração. Copie o arquivo google_ads_config.rb para o diretório inicial e modifique-o para incluir o 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 vai ler 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, instancie o cliente transmitindo o caminho para o local em que 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_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"

Também é possível transmitir as informações de maneira programática no tempo 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 conseguir a autenticação do usuário no tempo de execução para gerenciar as contas do Google Ads em nome dele. Use esse exemplo de código como referência para criar apps para computador que exigem autenticação do usuário.

E se o 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 Ruby fornece os exemplos de código a seguir 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 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 Application Default Credentials (ADC). Ela 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 para desenvolvimento em relação a diferentes APIs do Google, já que você pode reutilizar as mesmas credenciais, desde que elas possam acessar os escopos corretos do OAuth 2.0.

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

Para usar as credenciais padrão do aplicativo, recomendamos usar a ferramenta de linha de comando do Google Cloud e autenticar para 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, é necessário atualizar o aplicativo para usar o ADC.

Recomendamos o uso de um arquivo de configuração. Copie o arquivo google_ads_config.rb para o diretório inicial, adicione o token de desenvolvedor e defina use_application_default_credentials como verdadeiro:

  # 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"

Também é possível transmitir as informações de maneira programática no tempo de execução. Ao inicializar o cliente no código Ruby, não forneça credenciais OAuth2 explícitas. A biblioteca vai detectar e usar automaticamente as credenciais configuradas pela ferramenta de linha de comando do Google Cloud. Você ainda precisará especificar o 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.

Autenticação e autorização Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.