Autenticación y autorización

Al igual que otras APIs de Google, la API de Google Ads usa el protocolo OAuth 2.0 para la autenticación y la autorización. OAuth 2.0 permite que tu app cliente de la API de Google Ads acceda a la cuenta de Google Ads de un usuario sin tener que controlar ni almacenar su información de acceso.

Información sobre el modelo de acceso de Google Ads

Para trabajar de manera eficaz con la API de Google Ads, debes comprender cómo funciona el modelo de acceso de Google Ads. Te recomendamos que leas la guía del modelo de acceso de Google Ads.

Flujos de trabajo de OAuth

Existen tres flujos de trabajo comunes que se utilizan cuando se trabaja con la API de Google Ads.

Flujo de la cuenta de servicio

Este es el flujo de trabajo recomendado si no requiere interacción humana. Este flujo de trabajo requiere un paso de configuración en el que el usuario agrega una cuenta de servicio a su cuenta de Google Ads. Luego, la app puede usar las credenciales de la cuenta de servicio para administrar la cuenta de Google Ads del usuario. Para configurar esto, crea y descarga el archivo de claves JSON en la consola de Google Cloud. Luego, copia google_ads_config.rb en tu directorio principal y modifícalo para especificar la ubicación del archivo de claves de tu cuenta de servicio y la dirección de correo electrónico del usuario al que suplantar:

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

Si prefieres no almacenar esta información en un archivo y usar variables de entorno, puedes configurar GOOGLE_ADS_JSON_KEY_FILE_PATH y 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"

También puedes pasar la información de forma programática en el tiempo de ejecución con la gem googleauth para crear credenciales a partir de un archivo JSON de cuenta de servicio:

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

Consulta la guía del flujo de trabajo de la cuenta de servicio para obtener más información.

Flujo de autenticación de un solo usuario

Este flujo de trabajo se puede usar si no puedes usar cuentas de servicio. Este flujo de trabajo requiere dos pasos de configuración:

  1. Otorga acceso a un solo usuario a todas las cuentas que se administrarán con la API de Google Ads. Un enfoque común es otorgarle al usuario acceso a una cuenta de administrador de la API de Google Ads y vincular todas las cuentas de Google Ads a esa cuenta de administrador.
  2. El usuario ejecuta una herramienta de línea de comandos, como gcloud o el ejemplo de código de GenerateUserCredentials, para autorizar tu app a administrar todas sus cuentas de Google Ads en su nombre.

Para configurar las credenciales de OAuth 2.0 para Ruby, copia el archivo google_ads_config.rb en tu directorio principal y modifícalo para incluir tu token de desarrollador, ID de cliente, secreto del cliente y token de actualización:

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

El cliente leerá automáticamente el archivo de configuración del directorio principal si se instancia sin argumentos:

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

Como alternativa, si prefieres almacenar el archivo en otro lugar, puedes crear una instancia del cliente pasando la ruta de acceso a la ubicación en la que guardas este archivo:

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

Si prefieres no almacenar esta información en un archivo y usar variables de entorno, puedes configurar cada una de ellas:

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"

También puedes pasar la información de forma programática en el tiempo de ejecución:

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

Consulta la guía del flujo de trabajo de autenticación de un solo usuario para obtener más información.

Flujo de autenticación de varios usuarios

Este es el flujo de trabajo recomendado si tu app permite que los usuarios accedan y autoricen tu app para administrar sus cuentas de Google Ads en su nombre. Tu app compila y administra las credenciales de usuario de OAuth 2.0. Este flujo de trabajo se puede configurar de manera similar al flujo de un solo usuario, pero con el login_customer_id también especificado.

Te recomendamos que uses un archivo de configuración. Copia el archivo google_ads_config.rb en tu directorio principal y modifícalo para incluir tu token de desarrollador, ID de cliente, secreto de cliente, token de actualización y el ID de 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'

El cliente leerá automáticamente el archivo de configuración del directorio principal si se instancia sin argumentos:

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

Como alternativa, si prefieres almacenar el archivo en otro lugar, puedes crear una instancia del cliente pasando la ruta de acceso a la ubicación en la que guardas este archivo:

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

Si prefieres no almacenar esta información en un archivo y usar variables de entorno, puedes configurar cada una de ellas:

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"

También puedes pasar la información de forma programática en el tiempo de ejecución:

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

Consulta la guía del flujo de trabajo de autenticación de varios usuarios para obtener más información. La biblioteca cliente de Ruby incluye un ejemplo de código como referencia. GenerateUserCredentials es un ejemplo de código de línea de comandos que ilustra cómo obtener la autenticación del usuario en el tiempo de ejecución para administrar sus cuentas de Google Ads en su nombre. Puedes usar este ejemplo de código como referencia para compilar apps para computadoras que requieran autenticación del usuario.

¿Qué sucede si mi usuario administra varias cuentas?

Es común que un usuario administre más de una cuenta de Google Ads, ya sea a través del acceso directo a las cuentas o a través de una cuenta de administrador de Google Ads. La biblioteca cliente de Ruby proporciona los siguientes ejemplos de código que ilustran cómo controlar estos casos.

  1. El ejemplo de código de GetAccountHierarchy muestra cómo recuperar la lista de todas las cuentas de una cuenta de administrador de Google Ads.
  2. En el ejemplo de código de ListAccessibleCustomers, se muestra cómo recuperar la lista de todas las cuentas a las que un usuario tiene acceso directo. Luego, estas cuentas se pueden usar como valores válidos para el parámetro de configuración LoginCustomerId.

Credenciales predeterminadas de la aplicación

La biblioteca cliente de Ruby también admite la autenticación con credenciales predeterminadas de la aplicación (ADC). Te permite establecer las credenciales predeterminadas para tu aplicación sin necesidad de configurar la información de OAuth 2.0 en la configuración de la aplicación.

Esto es especialmente útil para el desarrollo local o para el desarrollo en diferentes APIs de Google, ya que puedes reutilizar las mismas credenciales, siempre que puedan acceder a los permisos de OAuth 2.0 correctos.

En el caso de la API de Google Ads, asegúrate de que las credenciales predeterminadas de tu aplicación puedan acceder al permiso de https://www.googleapis.com/auth/adwords de OAuth 2.0.

Para usar las credenciales predeterminadas de la aplicación, te recomendamos que uses la herramienta de línea de comandos de Google Cloud y que te autentiques para ADC:

gcloud auth application-default login

Este comando abrirá un navegador web para completar el flujo de autenticación de tu Cuenta de Google. Una vez que se autoriza, almacena las credenciales en una ubicación estándar. Luego, debes actualizar tu aplicación para usar ADC.

Te recomendamos que uses un archivo de configuración. Copia el archivo google_ads_config.rb en tu directorio principal, luego agrega tu token de desarrollador y establece use_application_default_credentials como verdadero:

  # 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

Si prefieres no almacenar esta información en un archivo y usar variables de entorno, puedes configurar GOOGLE_ADS_DEVELOPER_TOKEN y GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS:

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

También puedes pasar la información de forma programática en el tiempo de ejecución. Cuando inicialices el cliente en tu código de Ruby, no proporciones credenciales de OAuth2 explícitas. La biblioteca detectará y usará automáticamente las credenciales configuradas por la herramienta de línea de comandos de Google Cloud. Aún deberás especificar tu token de desarrollador.

# 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

Consulta la página de configuración para obtener más detalles sobre las opciones disponibles para configurar la biblioteca cliente de Ruby.