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 aplicación cliente de la API de Google Ads acceda a la cuenta de Google Ads de un usuario sin tener que administrar ni almacenar su información de acceso.

Comprende el modelo de acceso de Google Ads

Para trabajar de manera eficaz con la API de Google Ads, comprende cómo funciona el modelo de acceso de Google Ads. Consulta la guía del modelo de acceso de Google Ads.

Flujos de trabajo de OAuth

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

Flujo de la cuenta de servicio

Este es el flujo de trabajo recomendado si tu flujo de trabajo no requiere ninguna 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. La biblioteca de Python se configura de la siguiente manera:

• Si usas un archivo google-ads.yaml o una cadena YAML, agrega lo siguiente a tu configuración para establecer la ruta de acceso al archivo JSON de clave privada en tu entorno local (junto con el impersonated_email opcional si usas la delegación de todo el dominio):

  json_key_file_path: JSON_KEY_FILE_PATH
  # Optional: only set if using Google Workspace domain-wide delegation:
  # impersonated_email: IMPERSONATED_EMAIL
  

  Luego, llama a los métodos load_from_storage o load_from_string:

  from google.ads.googleads.client import GoogleAdsClient
  
  client = GoogleAdsClient.load_from_storage()
  

• Si usas un dict para configurar la biblioteca, incluye el siguiente par clave-valor y llama al método load_from_dict, pasando el dict de configuración:

  from google.ads.googleads.client import GoogleAdsClient
  
  configuration = {
      # ...
      "json_key_file_path": JSON_KEY_FILE_PATH,
      # ...
  }
  
  client = GoogleAdsClient.load_from_dict(configuration)
  

• Si usas variables de entorno, agrega lo siguiente a tu configuración o entorno de bash:

  export GOOGLE_ADS_JSON_KEY_FILE_PATH=JSON_KEY_FILE_PATH
  

  Luego, llama al método load_from_env:

  from google.ads.googleads.client import GoogleAdsClient
  
  client = GoogleAdsClient.load_from_env()
  

Si la opción de configuración json_key_file_path está presente en cualquiera de estos métodos de configuración, la opción use_application_default_credentials es False o no está configurada, y las claves de credenciales de usuario de OAuth (client_id, client_secret y refresh_token) no están configuradas o están marcadas como comentario, la biblioteca autoriza automáticamente con el flujo de la cuenta de servicio.

Consulta la guía de 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 a un solo usuario acceso a todas las cuentas que se administrarán con la API de Google Ads. Un enfoque común es otorgar al usuario acceso a una cuenta de administrador de la API de Google Ads y vincular todas las cuentas de Google Ads con esa cuenta de administrador.

2. El usuario ejecuta una herramienta, como la gcloud CLI o el ejemplo de código de generate_user_credentials, para autorizar a tu app a administrar todas sus cuentas de Google Ads en su nombre.

La biblioteca se puede inicializar con las credenciales de OAuth 2.0 del usuario de la siguiente manera:

Si usas la herramienta de gcloud CLI (recomendado)

1. Sigue la documentación de Genera credenciales para configurar las credenciales predeterminadas de la aplicación (ADC) en tu entorno local.

2. Agrega la siguiente configuración a tu cadena google-ads.yaml o YAML:

   use_application_default_credentials: true
   

   Luego, llama al método load_from_storage o load_from_string:

   from google.ads.googleads.client import GoogleAdsClient
   
   client = GoogleAdsClient.load_from_storage()
   

   Si usas un dict para configurar la biblioteca, incluye el siguiente par clave-valor y llama al método load_from_dict:

   from google.ads.googleads.client import GoogleAdsClient
   
   configuration = {
       # ...
       "use_application_default_credentials": True,
       # ...
   }
   
   client = GoogleAdsClient.load_from_dict(configuration)
   

   Si usas variables de entorno, agrega lo siguiente a tu configuración o entorno de bash:

   export GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS=true
   

   Luego, llama al método load_from_env:

   from google.ads.googleads.client import GoogleAdsClient
   
   client = GoogleAdsClient.load_from_env()
   

Si manejas tokens de OAuth directamente

1. Sigue los pasos para configurar un proyecto de la consola y descarga el archivo JSON que incluye el ID de cliente y el secreto del cliente de tu proyecto.

2. Clona la biblioteca cliente de Python en tu máquina y cambia a su directorio:

   git clone https://github.com/googleads/google-ads-python.git
   cd google-ads-python
   

3. Ejecuta el ejemplo y proporciona una ruta de acceso absoluta al archivo JSON que descargaste en el paso 1:

   python examples/authentication/generate_user_credentials.py \
       -c PATH_TO_CREDENTIALS_JSON
   

   Una vez que se complete, se imprimirá un token de actualización en tu consola. Cópialo y guárdalo para el siguiente paso.

4. Para configurar la biblioteca, agrega los siguientes parámetros a la configuración que elijas:

   Agrega la siguiente configuración a tu cadena google-ads.yaml o YAML:

   client_id: INSERT_OAUTH2_CLIENT_ID_HERE
   client_secret: INSERT_OAUTH2_CLIENT_SECRET_HERE
   refresh_token: INSERT_REFRESH_TOKEN_HERE
   

   Luego, llama al método load_from_storage o load_from_string:

   from google.ads.googleads.client import GoogleAdsClient
   
   client = GoogleAdsClient.load_from_storage()
   

   Si usas un dict para configurar la biblioteca, incluye los siguientes pares clave-valor y llama al método load_from_dict:

   from google.ads.googleads.client import GoogleAdsClient
   
   configuration = {
       # ...
       "client_id": INSERT_OAUTH2_CLIENT_ID_HERE,
       "client_secret": (
           INSERT_OAUTH2_CLIENT_SECRET_HERE
       ),
       "refresh_token": INSERT_REFRESH_TOKEN_HERE,
       # ...
   }
   
   client = GoogleAdsClient.load_from_dict(configuration)
   

   Si usas variables de entorno, agrega lo siguiente a tu configuración o entorno de bash:

   export GOOGLE_ADS_CLIENT_ID=\
   INSERT_OAUTH2_CLIENT_ID_HERE
   export GOOGLE_ADS_CLIENT_SECRET=\
   INSERT_OAUTH2_CLIENT_SECRET_HERE
   export GOOGLE_ADS_REFRESH_TOKEN=\
   INSERT_REFRESH_TOKEN_HERE
   

   Luego, llama al método load_from_env:

   from google.ads.googleads.client import GoogleAdsClient
   
   client = GoogleAdsClient.load_from_env()
   

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 multiusuario

Este es el flujo de trabajo recomendado si tu app permite que los usuarios accedan y autoricen a tu app a administrar sus cuentas de Google Ads en su nombre. Tu app compila y administra las credenciales de usuario de OAuth 2.0. La biblioteca se puede inicializar con las credenciales del usuario de la siguiente manera, lo que supone que tu aplicación obtiene credenciales en el entorno de ejecución, ya sea ejecutando un flujo de autorización o cargándolas desde un almacén de datos:

Un dict es el mecanismo de configuración más simple que se puede usar para obtener credenciales en el entorno de ejecución:

from google.ads.googleads.client import GoogleAdsClient

configuration = {
    # ...
    "client_id": client_id,
    "client_secret": client_secret,
    "refresh_token": refresh_token,
    # ...
}

client = GoogleAdsClient.load_from_dict(configuration)

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

Autenticación manual

Puedes generar credenciales de autenticación con cualquier enfoque y proporcionarlas a la GoogleAdsClient de forma manual creando una instancia de la clase de cliente directamente. Si suponemos que el objeto de credenciales que creas es una instancia de google.auth.credentials.Credentials, puedes pasarlo de la siguiente manera:

from google.ads.googleads.client import GoogleAdsClient
from google.auth import default

# This line retrieves ADCs from the environment. You can use any authentication
# approach as long as the `credentials` variable is an instance of
# `google.auth.credentials.Credentials`.
credentials, _ = default(scopes=["https://www.googleapis.com/auth/adwords"])

client = GoogleAdsClient(
    credentials=credentials,
    use_proto_plus=True,
)

Administrar 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 de una cuenta de administrador de Google Ads. La biblioteca cliente de Python proporciona los siguientes ejemplos de código que ilustran cómo controlar estos casos:

1. En el ejemplo de código de get_account_hierarchy, se 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 list_accessible_customers, 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 login_customer_id.