Configuración

La biblioteca cliente de PHP de la API de Google Ads proporciona varios parámetros de configuración que puedes usar para personalizar el comportamiento de la biblioteca.

Archivo de configuración

Puedes almacenar la mayoría de estos parámetros de configuración en archivos de configuración INI y usarlos cuando crees instancias de clientes, por ejemplo, google_ads_php.ini.

Los compiladores de credenciales y clientes proporcionan métodos fromFile para cargar la configuración de esos archivos:

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

Si no se proporciona una ruta de acceso de configuración como argumento, los métodos fromFile se cargan desde la ruta de acceso de configuración predeterminada, que es la siguiente:

  1. Valor de la variable de entorno llamada GOOGLE_ADS_CONFIGURATION_FILE_PATH si está configurada.
  2. De lo contrario, el archivo google_ads_php.ini en tu directorio HOME.
$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile()
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile()
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

Configuración dinámica

Puedes establecer estos parámetros de configuración de forma dinámica cuando crees instancias de clientes:

$oAuth2Credential = (new OAuth2TokenBuilder())
    ->withClientId('INSERT_CLIENT_ID_HERE')
    ->withClientSecret('INSERT_CLIENT_SECRET_HERE')
    ->withRefreshToken('INSERT_REFRESH_TOKEN_HERE')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

Variables de entorno de configuración

Puedes establecer algunos parámetros de configuración a partir de variables de entorno cuando creas instancias de clientes (consulta las variables de entorno estándar).

Los compiladores de credenciales y clientes proporcionan métodos fromEnvironmentVariables para cargar la configuración desde variables de entorno.

$oAuth2Credential = (new OAuth2TokenBuilder())
    // ...
    ->fromEnvironmentVariables()
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->withOAuth2Credential($oAuth2Credential)
    // ...
    ->fromEnvironmentVariables()
    ->build();

Campos de configuración

Los parámetros de configuración admiten varios campos organizados en categorías:

  1. Campos que usa OAuth2TokenBuilder:
    • Modo de aplicación:
      • [OAUTH2] clientId: Es tu ID de cliente de OAuth2.
      • [OAUTH2] clientSecret: Es el secreto de tu cliente de OAuth2.
      • [OAUTH2] refreshToken: Es tu token de actualización de OAuth2.
    • Modo de cuenta de servicio:
      • [OAUTH2] jsonKeyFilePath: Es la ruta de acceso a la clave JSON.
      • [OAUTH2] scopes: Son los permisos de OAuth2 (el valor predeterminado es https://www.googleapis.com/auth/adwords en v32.1.0 y versiones posteriores; se requiere en versiones anteriores a v32.1.0 o cuando se usan permisos personalizados; fromEnvironmentVariables() no los lee de una variable de entorno).
      • [OAUTH2] impersonatedEmail: Dirección de correo electrónico opcional para suplantar la identidad cuando se usa la delegación en todo el dominio de Google Workspace.
    • Modo de credenciales predeterminadas de la aplicación:
      • Cuando no se configuran los campos Modo de aplicación ni Modo de cuenta de servicio, OAuth2TokenBuilder recurre automáticamente a las credenciales predeterminadas de la aplicación (ADC).
  2. Campos que usa GoogleAdsClientBuilder:
    • [GOOGLE_ADS] developerToken: (Baja el 9 de septiembre de 2026) Es tu token de desarrollador de la API de Google Ads. Es opcional, los servidores de la API lo ignoran independientemente de la versión de la biblioteca cliente y se rechazará en una versión principal futura de la API de Google Ads.
      • v35.0.0 y versiones posteriores: No se requiere en la inicialización del cliente (se quitó la validación local del token de desarrollador del cliente en GoogleAdsClientBuilder).
      • Versiones anteriores a v35.0.0: Se requiere para la validación de la configuración local del cliente.
    • [GOOGLE_ADS] loginCustomerId: Es el ID del cliente autorizado que se usará en la solicitud.
    • [GOOGLE_ADS] linkedCustomerId: Es el ID del cliente vinculado.
    • [GOOGLE_ADS] endpoint: Es un extremo del servidor de la API de Google Ads alternativo y opcional.
    • [LOGGING] logFilePath: Es la ruta de acceso para el registro de salida.
    • [LOGGING] logLevel: Es el nivel de registro.
    • [CONNECTION] proxy: Es la URL del servidor proxy que se usa para la conectividad a Internet.
    • [CONNECTION] transport: Es el transporte de red (grpc o rest).
    • [CONNECTION] grpcChannelIsSecure: Indica si el canal de gRPC es seguro.
    • [CONNECTION] grpcChannelCredential: Son las credenciales del canal de gRPC.
    • [CONNECTION] unaryMiddlewares: Son los middlewares unarios.
    • [CONNECTION] streamingMiddlewares: Son los middlewares de transmisión.
    • [CONNECTION] grpcInterceptors: Son los interceptores de gRPC.

Validación de la configuración

La configuración se verifica cuando se crean instancias de los clientes y se arrojan excepciones cuando no es válida. Las reglas de validación son las siguientes:

  1. Los campos [OAUTH2] no deben configurarse para el modo de aplicación y el modo de cuenta de servicio al mismo tiempo.
  2. [OAUTH2] jsonKeyFilePath se debe configurar cuando se usa el modo de cuenta de servicio (en versiones anteriores a v32.1.0, también se debe configurar [OAUTH2] scopes; en v32.1.0 y versiones posteriores, scopes se establece de forma predeterminada en https://www.googleapis.com/auth/adwords).
  3. [OAUTH2] clientId, [OAUTH2] clientSecret y [OAUTH2] refreshToken se deben configurar cuando se usa el modo de aplicación.
  4. En las versiones anteriores a v35.0.0, [GOOGLE_ADS] developerToken se verifica con la validación local del cliente (en v35.0.0 y versiones posteriores, no se requiere [GOOGLE_ADS] developerToken).
  5. Si se configuran, [GOOGLE_ADS] loginCustomerId y [GOOGLE_ADS] linkedCustomerId deben ser números positivos.
  6. Si se configura, [CONNECTION] proxy debe ser una URL válida (consulta el filtro FILTER_VALIDATE_URL).
  7. Si se configura, [LOGGING] logLevel debe ser un nivel de registro de PSR válido en letras mayúsculas, como INFO.
  8. Si se configura, [CONNECTION] transport debe ser grpc o rest.
  9. Si [CONNECTION] transport se establece en grpc, el entorno debe admitir el transporte de gRPC (consulta la guía de transporte).
  10. [CONNECTION] grpcChannelIsSecure debe ser true cuando [CONNECTION] transport no está establecido en grpc (las conexiones REST siempre requieren HTTPS).
  11. [CONNECTION] grpcChannelCredential solo se puede configurar cuando [CONNECTION] transport se establece como grpc.
  12. [CONNECTION] grpcChannelCredential solo se puede configurar cuando [CONNECTION] grpcChannelIsSecure es true.