Configuración

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

Configura la biblioteca en el entorno de ejecución

La forma preferida de configurar la biblioteca cliente es inicializar un objeto GoogleAdsConfig en el entorno de ejecución:

using Google.Ads.Gax.Config;
using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Lib;

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.APPLICATION,
    OAuth2ClientId = "INSERT_CLIENT_ID.apps.googleusercontent.com",
    OAuth2ClientSecret = "INSERT_CLIENT_SECRET",
    OAuth2RefreshToken = "INSERT_REFRESH_TOKEN",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};

GoogleAdsClient client = new GoogleAdsClient(config);

Opciones de configuración alternativas

La biblioteca también proporciona opciones adicionales para cargar parámetros de configuración desde appsettings.json, archivos JSON personalizados, variables de entorno o App.config. Para habilitarlas, instala el paquete NuGet Google.Ads.GoogleAds.Extensions en tu proyecto:

dotnet add package Google.Ads.GoogleAds.Extensions

Si usas una de estas opciones, los parámetros de configuración no se seleccionan automáticamente; debes cargarlos de forma explícita, como se muestra en las siguientes secciones. Asegúrate de controlar las excepciones de E/S de archivos (como FileNotFoundException o UnauthorizedAccessException) cuando cargues la configuración desde archivos o transmisiones externos.

Usa appsettings.json o settings.json

En las aplicaciones de .NET 8.0 y ASP.NET Core, coloca las claves de configuración dentro de una sección GoogleAdsApi en appsettings.json (o settings.json):

{
  "GoogleAdsApi": {
    "LoginCustomerId": "INSERT_LOGIN_CUSTOMER_ID_HERE",
    "OAuth2Mode": "APPLICATION",
    "OAuth2ClientId": "INSERT_CLIENT_ID.apps.googleusercontent.com",
    "OAuth2ClientSecret": "INSERT_CLIENT_SECRET",
    "OAuth2RefreshToken": "INSERT_REFRESH_TOKEN"
  }
}

A continuación, extrae la sección GoogleAdsApi de la instancia IConfiguration de tu aplicación (por ejemplo, insertada por ASP.NET Core o compilada con ConfigurationBuilder) y cárgala con LoadFromConfigurationSection:

using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;
using Microsoft.Extensions.Configuration;

IConfigurationSection section = configuration.GetSection("GoogleAdsApi");
GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromConfigurationSection(section);
GoogleAdsClient client = new GoogleAdsClient(config);

Como alternativa, puedes cargar un archivo appsettings.json o settings.json directamente por ruta de acceso con LoadFromSettingsJson:

using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromSettingsJson("appsettings.json", "GoogleAdsApi");
GoogleAdsClient client = new GoogleAdsClient(config);

También puedes cargar la ruta de acceso desde la variable de entorno GOOGLE_ADS_CONFIGURATION_FILE_PATH (EnvironmentVariableNames.CONFIG_FILE_PATH) llamando a config.TryLoadFromEnvironmentFilePath.

Usa un archivo JSON personalizado

También puedes usar una instancia de IConfigurationRoot para cargar un archivo JSON plano sin una sección GoogleAdsApi de nivel superior.

Crea un archivo JSON

Crea un archivo JSON llamado GoogleAdsApi.json que defina las claves de configuración en el nivel raíz:

{
  "Timeout": "2000",
  "ProxyServer": "http://localhost:8888",
  "ProxyUser": "",
  "ProxyPassword": "",
  "ProxyDomain": "",
  "LoginCustomerId": "INSERT_LOGIN_CUSTOMER_ID_HERE",
  "OAuth2Mode": "APPLICATION",
  "OAuth2ClientId": "INSERT_CLIENT_ID.apps.googleusercontent.com",
  "OAuth2ClientSecret": "INSERT_CLIENT_SECRET",
  "OAuth2RefreshToken": "INSERT_REFRESH_TOKEN"
}

Carga la configuración

Luego, carga el archivo JSON en un IConfigurationRoot:

using System.IO;
using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;
using Microsoft.Extensions.Configuration;

ConfigurationBuilder builder = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("GoogleAdsApi.json");
IConfigurationRoot configRoot = builder.Build();

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromConfigurationRoot(configRoot);
GoogleAdsClient client = new GoogleAdsClient(config);

Usa variables de entorno

También puedes inicializar el GoogleAdsClient con variables de entorno:

using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromEnvironmentVariables();
GoogleAdsClient client = new GoogleAdsClient(config);

Consulta la lista completa de variables de entorno compatibles.

Usa App.config

En las aplicaciones de .NET Framework, todos los parámetros de configuración específicos de la API de Google Ads se almacenan en el nodo GoogleAdsApi del archivo App.config. Una configuración típica de App.config es la siguiente:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <configSections>
    <section name="GoogleAdsApi"
             type="System.Configuration.DictionarySectionHandler" />
  </configSections>
  <GoogleAdsApi>
    <!-- Set the service timeout in milliseconds. -->
    <add key="Timeout" value="2000" />

    <!-- Proxy settings for library. -->
    <add key="ProxyServer" value="http://localhost:8888" />
    <add key="ProxyUser" value="" />
    <add key="ProxyPassword" value="" />
    <add key="ProxyDomain" value="" />

    <!-- Google Ads API settings. -->
    <add key="LoginCustomerId" value="INSERT_LOGIN_CUSTOMER_ID_HERE" />

    <!-- OAuth2 settings -->
    <add key="OAuth2Mode" value="APPLICATION" />
    <add key="OAuth2ClientId"
         value="INSERT_CLIENT_ID.apps.googleusercontent.com" />
    <add key="OAuth2ClientSecret" value="INSERT_CLIENT_SECRET" />
    <add key="OAuth2RefreshToken" value="INSERT_REFRESH_TOKEN" />
  </GoogleAdsApi>
  <startup>
    <supportedRuntime version="v4.0" sku=".NETFramework,Version=v4.7.2" />
  </startup>
</configuration>

Para cargar los parámetros de configuración desde un archivo App.config, llama al método LoadFromDefaultAppConfigSection en un objeto GoogleAdsConfig:

using Google.Ads.GoogleAds.Config;
using Google.Ads.GoogleAds.Extensions.Config;
using Google.Ads.GoogleAds.Lib;

GoogleAdsConfig config = new GoogleAdsConfig();
config.LoadFromDefaultAppConfigSection();
GoogleAdsClient client = new GoogleAdsClient(config);

Especifica un archivo de configuración de aplicación independiente

Si no quieres que tu App.config esté desordenado, puedes mover la configuración específica de la biblioteca a su propio archivo de configuración con la propiedad configSource:

  1. Especifica un configSource en tu App.config. Modifica tu App.config para que haga referencia a un archivo de configuración externo:

    <?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <configSections>
    <section name="GoogleAdsApi"
             type="System.Configuration.DictionarySectionHandler" />
  </configSections>
  <GoogleAdsApi configSource="GoogleAdsApi.config" />
</configuration>

  2. Especifica el contenido de tu archivo de configuración. Crea otro archivo de configuración con el nombre que especificaste en configSource (GoogleAdsApi.config) y mueve el nodo de configuración GoogleAdsApi de tu App.config a este archivo:

    <?xml version="1.0" encoding="utf-8" ?>
<GoogleAdsApi>
  <!-- More settings. -->
</GoogleAdsApi>

  3. Actualiza las reglas de compilación en tu .csproj. Incluye el nuevo archivo de configuración en tu proyecto y establece su propiedad Copiar en el directorio de salida en Copiar siempre. Vuelve a compilar y ejecutar tu proyecto para que la aplicación tome los valores del nuevo archivo de configuración.

Usa una transmisión genérica

También puedes cargar la configuración, o partes de ella, desde un flujo genérico, incluido uno encriptado:

GoogleAdsConfig config = new GoogleAdsConfig()
{
    // Set some configuration properties in code.
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
};

// Load your encrypted data from a file and dispose of the streams properly.
using (CryptoStream strm = GetEncryptedCredentialsStream())
using (StreamReader rdr = new StreamReader(strm))
{
    // Configure the OAuth credentials from the encrypted stream.
    config.LoadOAuth2SecretsFromStream(rdr);
}

GoogleAdsClient client = new GoogleAdsClient(config);

Campos de configuración

En las siguientes secciones, se enumeran los parámetros de configuración que admite la biblioteca de .NET de Google Ads.

Configuración de conectividad

  • Timeout: Usa esta clave para establecer el tiempo de espera del servicio en milisegundos. El valor predeterminado se establece según el parámetro de configuración method_config/timeout en googleads_grpc_service_config.json. Establece un valor más bajo si necesitas aplicar un límite más corto en el tiempo máximo para una llamada a la API. Puedes configurar el tiempo de espera en 2 horas o más, pero la API puede agotar el tiempo de espera de las solicitudes de ejecución muy larga y devolver un error DEADLINE_EXCEEDED.
  • ProxyServer: Configura este parámetro como la URL del servidor proxy HTTP si usas un proxy para conectarte a Internet.
  • ProxyUser: Configura este parámetro como el nombre de usuario que necesitas para autenticarte en el servidor proxy. Deja este campo en blanco si no se requiere un nombre de usuario.
  • ProxyPassword: Configura este valor como la contraseña de ProxyUser si estableciste un valor para ProxyUser.
  • ProxyDomain: Configura este parámetro en el dominio de ProxyUser si tu servidor proxy requiere que se establezca uno.
  • MaxReceiveMessageLengthInBytes: Usa este parámetro de configuración para aumentar el tamaño máximo de la respuesta de la API que puede controlar la biblioteca cliente. El valor predeterminado es de 64 MB.
  • MaxMetadataSizeInBytes: Usa este parámetro de configuración para aumentar el tamaño máximo de la respuesta de error de la API que puede controlar la biblioteca cliente. El valor predeterminado es 16 MB.

Ajusta la configuración de MaxReceiveMessageLengthInBytes y MaxMetadataSizeInBytes para corregir ciertos errores de ResourceExhausted. Estos parámetros de configuración abordan errores de la siguiente forma:

Status(StatusCode="ResourceExhausted",Detail="Received
message larger than max (423184132 versus 67108864)"

En este ejemplo, el error se debe a que el tamaño del mensaje (423184132 bytes) es mayor que el que puede controlar la biblioteca (67108864 bytes). Aumenta MaxReceiveMessageLengthInBytes a 500000000 para evitar este error. Ten en cuenta que el error también indica que tu código controló un objeto de respuesta bastante grande (como un SearchGoogleAdsResponse grande). Esto podría tener implicaciones de rendimiento para tu código debido al montón de objetos grandes de .NET. Si esto se convierte en un problema de rendimiento, es posible que debas explorar cómo reorganizar tus llamadas a la API o rediseñar partes de tu app.

Configuración de OAuth2

Cuando uses OAuth 2.0 para autorizar tus llamadas a los servidores de la API de Google Ads, debes establecer las siguientes claves de configuración:

  • AuthorizationMethod: Configurado como OAuth2.
  • OAuth2Mode: Se establece en APPLICATION o SERVICE_ACCOUNT.
  • OAuth2ClientId: Establece este valor en tu ID de cliente de OAuth 2.0.
  • OAuth2ClientSecret: Establece este valor en tu secreto de cliente de OAuth 2.0.
  • OAuth2ScopeEstablece este valor en diferentes permisos si quieres autorizar tokens de OAuth 2.0 para varias APIs. Este parámetro de configuración es opcional
  • UseApplicationDefaultCredentials: Establece este valor en true para autenticarte con las credenciales predeterminadas de la aplicación (compatible con Google.Ads.GoogleAds v24.1.0 y versiones posteriores; config.LoadFromEnvironmentVariables() lee la variable de entorno USE_APPLICATION_DEFAULT_CREDENTIALS sin prefijo).
  • Credentials: (solo en el entorno de ejecución, compatible con v27.0.0 y versiones posteriores) Inserta una instancia de ICredential o GoogleCredential compilada previamente de forma directa en GoogleAdsConfig en el entorno de ejecución.

Si usas OAuth2Mode == APPLICATION, debes establecer las siguientes claves de configuración adicionales:

  • OAuth2RefreshToken: Establece este valor en un token de actualización de OAuth 2.0 generado previamente si quieres reutilizar tokens de OAuth 2.0. Este parámetro de configuración es opcional
  • OAuth2RedirectUri: Establece este valor en la URL de redireccionamiento de OAuth 2.0. Este parámetro de configuración es opcional.

Consulta las siguientes guías para obtener más detalles:

Si usas OAuth2Mode == SERVICE_ACCOUNT, debes establecer las siguientes claves de configuración adicionales:

  • OAuth2SecretsJsonPath: Establece este valor en la ruta de acceso del archivo de claves JSON de OAuth 2.0.
  • OAuth2PrnEmail: Establece este valor en la dirección de correo electrónico de la cuenta que suplantas cuando usas la delegación de todo el dominio de Google Workspace. Este parámetro de configuración es opcional.

Consulta la guía Flujo de la cuenta de servicio de OAuth para obtener más detalles.

Configuración de transporte

  • UseGrpcCore: Establece este parámetro de configuración en true para usar la biblioteca Grpc.Core como la capa de transporte subyacente. Consulta Cómo usar la biblioteca de Grpc.Core.

Configuración de la API de Google Ads

Los siguientes parámetros de configuración son específicos de la API de Google Ads:

  • LoginCustomerId: Es el ID del cliente autorizado que se usará en la solicitud, sin guiones (-).
  • LinkedCustomerId: Este encabezado solo es obligatorio para los métodos que actualizan los recursos de una entidad cuando se otorgan permisos a través de las cuentas vinculadas en la IU de Google Ads (recurso AccountLink en la API de Google Ads). Establece este valor en el ID de cliente del proveedor de datos que actualiza los recursos del ID de cliente especificado. Se debe configurar sin guiones (-). Obtén más información sobre las cuentas vinculadas.