Configuración

Puedes configurar la biblioteca cliente de Python con un archivo YAML, variables de entorno, una cadena YAML o un dict.

Configuración de autenticación

Existen varias formas de administrar las credenciales de OAuth necesarias para acceder a la API de Google Ads. El enfoque que elijas afectará los campos de configuración que uses. Para obtener más información, consulta la guía de autenticación.

Configuración con un archivo YAML

Puedes especificar un archivo YAML para usar cuando inicialices el cliente que contiene la información necesaria para realizar solicitudes a la API de Google Ads. Se accede a este archivo cuando se inicializa un cliente con el método load_from_storage. La forma más sencilla de generar este archivo es copiar el ejemplo de google-ads.yaml del repositorio de GitHub y modificarlo para incluir tus credenciales, como el token de actualización, el ID de cliente y el secreto del cliente.

Si no proporcionas una ruta de acceso, la biblioteca buscará el archivo en tu directorio $HOME:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage()

Para especificar una ubicación en la que se encuentra el archivo google-ads.yaml, puedes pasar la ruta de acceso como una cadena al método cuando lo llames:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")

También puedes especificar la ruta de acceso definiendo una variable de entorno específica:

import os
from google.ads.googleads.client import GoogleAdsClient

os.environ["GOOGLE_ADS_CONFIGURATION_FILE_PATH"] = "path/to/google-ads.yaml"
client = GoogleAdsClient.load_from_storage()

Si se proporcionan ambos valores (se pasa una ruta de acceso al método y la variable de entorno está presente), la biblioteca prioriza la ruta de acceso que se pasó al método.

Configuración con variables de entorno

Puedes almacenar toda la configuración del cliente como variables de entorno, que se leen cuando se usa el método load_from_env del cliente. Las variables de entorno deben tener el mismo nombre que las definidas en el archivo google-ads.yaml, pero deben estar en mayúsculas y tener el prefijo del espacio de nombres GOOGLE_ADS_. Por ejemplo, client_id se debe almacenar como GOOGLE_ADS_CLIENT_ID.

Las variables de entorno se suelen definir en un archivo de configuración de Bash, como un archivo .bashrc o .bash_profile ubicado en el directorio $HOME. También se pueden definir con la línea de comandos.

Estos son algunos pasos básicos para definir una variable de entorno con un archivo .bashrc en una terminal:

# Append the line "export GOOGLE_ADS_CLIENT_ID=1234567890" to
# the bottom of your .bashrc file.
echo "export GOOGLE_ADS_CLIENT_ID=1234567890" >> ~/.bashrc
# Update your bash environment to use the most recently updated
# version of your .bashrc file.
source ~/.bashrc

También puedes establecer variables de entorno en tu instancia de terminal directamente desde la línea de comandos:

export GOOGLE_ADS_CLIENT_ID=1234567890
echo $GOOGLE_ADS_CLIENT_ID

El método load_from_env carga datos de configuración del atributo environ en el módulo os integrado de Python. Por ejemplo: os.environ["GOOGLE_ADS_CLIENT_ID"]

A continuación, se muestra un ejemplo de cómo inicializar una instancia del cliente con la configuración de las variables de entorno:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_env()

Para configurar logging a través de variables de entorno, el valor de configuración debe ser un objeto JSON que coincida con la estructura de las claves YAML en el archivo de configuración de google-ads.yaml de muestra.

Este es un ejemplo de cómo se podría configurar con un archivo .bashrc:

export GOOGLE_ADS_LOGGING='{
  "version": 1,
  "disable_existing_loggers": false,
  "formatters": {
    "default_fmt": {
      "format": "[%(asctime)s - %(levelname)s] %(message).5000s",
      "datefmt": "%Y-%m-%d %H:%M:%S"
    }
  },
  "handlers": {
    "default_handler": {
      "class": "logging.StreamHandler",
      "formatter": "default_fmt"
    }
  },
  "loggers": {
    "": {
      "handlers": ["default_handler"],
      "level": "INFO"
    }
  }
}'

Punto clave: Si la variable de entorno GOOGLE_ADS_CONFIGURATION_FILE_PATH se configura cuando se llama al método load_from_env, los valores de configuración se recuperan del archivo google-ads.yaml ubicado en la ruta especificada, no de las variables de entorno descritas anteriormente.

Configuración con una cadena de YAML

Si leíste un archivo YAML en la memoria, puedes proporcionarlo directamente al cliente durante la inicialización. Para ello, usa el método load_from_string:

from google.ads.googleads.client import GoogleAdsClient

with open("/path/to/yaml", "r", encoding="utf-8") as handle:
    yaml_content = handle.read()

client = GoogleAdsClient.load_from_string(yaml_content)

Configuración con un dict

Puedes pasar un dict directamente al método load_from_dict. Por ejemplo:

from google.ads.googleads.client import GoogleAdsClient

credentials = {
    "refresh_token": "YOUR_REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "use_proto_plus": True,
}

client = GoogleAdsClient.load_from_dict(credentials)

Campos de configuración

La configuración de la biblioteca cliente admite los siguientes campos.

Autenticación

Usa solo uno de estos grupos de campos, según el enfoque de autenticación que utilices:

  • Un solo usuario con credenciales predeterminadas de la aplicación (documentación)
    • use_application_default_credentials: Indica si la biblioteca debe usar credenciales predeterminadas de la aplicación (ADC) para la autenticación (se admite en google-ads v28.3.0 y versiones posteriores).
  • Un solo usuario con tokens de OAuth (documentación)
    • client_id: Es tu ID de cliente de OAuth.
    • client_secret: Es tu secreto del cliente de OAuth.
    • refresh_token: Es tu token de actualización de OAuth.
  • Cuenta de servicio (documentación)
    • json_key_file_path: Es la ruta de acceso a un archivo de clave privada local. Se usa para la autenticación con una cuenta de servicio.
    • impersonated_email: Dirección de correo electrónico opcional de la cuenta que se suplantará cuando se use la delegación para todo el dominio de Google Workspace.

Comportamiento de la biblioteca

Estos campos determinan el comportamiento de la biblioteca:

Configuración a nivel de la solicitud

Variables de entorno

Para configurar la biblioteca con variables de entorno, usa lo siguiente:

  • GOOGLE_ADS_ADS_ASSISTANT
  • GOOGLE_ADS_CLIENT_ID
  • GOOGLE_ADS_CLIENT_SECRET
  • GOOGLE_ADS_CONFIGURATION_FILE_PATH
  • GOOGLE_ADS_ENDPOINT
  • GOOGLE_ADS_HTTP_PROXY
  • GOOGLE_ADS_IMPERSONATED_EMAIL
  • GOOGLE_ADS_JSON_KEY_FILE_PATH
  • GOOGLE_ADS_LINKED_CUSTOMER_ID
  • GOOGLE_ADS_LOGIN_CUSTOMER_ID
  • GOOGLE_ADS_LOGGING
  • GOOGLE_ADS_REFRESH_TOKEN
  • GOOGLE_ADS_USE_PROTO_PLUS
  • GOOGLE_ADS_USE_APPLICATION_DEFAULT_CREDENTIALS (compatible con v28.3.0 y versiones posteriores)

Configuración de registros

Los campos de registro, que son campos debajo del campo de configuración logging, se derivan directamente del módulo integrado logging.config porque la biblioteca pasa todos los campos debajo del espacio de nombres logging directamente al método logging.config.dictConfig. Consulta la guía de registro para obtener todos los detalles.

  • version: Es un valor entero que representa una versión del esquema.
  • disable_existing_loggers: Indica si se deben inhabilitar los registradores configurados en otro lugar de la aplicación.
  • formatters: Son diccionarios que definen diferentes tipos de formateadores.
  • handlers: Son diccionarios que definen diferentes controladores, que controlan dónde se escriben los registros y qué formateadores se deben usar.
  • loggers: Son diccionarios que definen diferentes tipos de registradores, que incluyen un controlador y un nivel de registro.