Configurazione

La libreria client dell'API Google Ads fornisce diverse impostazioni di configurazione che puoi utilizzare per personalizzare il comportamento della libreria.

Configura la libreria in fase di runtime

Il modo preferito per configurare la libreria client è inizializzare un oggetto GoogleAdsConfig in fase di runtime:

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);

Opzioni di configurazione alternative

La libreria offre anche opzioni aggiuntive per caricare le impostazioni di configurazione da appsettings.json, file JSON personalizzati, variabili di ambiente o App.config. Per attivarli, installa il pacchetto NuGet Google.Ads.GoogleAds.Extensions nel tuo progetto:

dotnet add package Google.Ads.GoogleAds.Extensions

Se utilizzi una di queste opzioni, le impostazioni di configurazione non vengono rilevate automaticamente; devi caricarle esplicitamente come mostrato nelle sezioni seguenti. Assicurati di gestire le eccezioni di I/O dei file (come FileNotFoundException o UnauthorizedAccessException) durante il caricamento delle impostazioni da file o stream esterni.

Utilizza appsettings.json o settings.json

Nelle applicazioni .NET 8.0 e ASP.NET Core, inserisci le chiavi di configurazione all'interno di una sezione GoogleAdsApi in 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"
  }
}

Successivamente, estrai la sezione GoogleAdsApi dall'istanza IConfiguration della tua applicazione (ad esempio, inserita da ASP.NET Core o creata con ConfigurationBuilder) e caricala 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);

In alternativa, puoi caricare un file appsettings.json o settings.json direttamente tramite il percorso utilizzando 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);

Puoi anche caricare il percorso dalla variabile di ambiente GOOGLE_ADS_CONFIGURATION_FILE_PATH (EnvironmentVariableNames.CONFIG_FILE_PATH) chiamando config.TryLoadFromEnvironmentFilePath.

Utilizza un file JSON personalizzato

Puoi anche utilizzare un'istanza IConfigurationRoot per caricare un file JSON semplice senza una sezione GoogleAdsApi di primo livello.

Crea un file JSON

Crea un file JSON denominato GoogleAdsApi.json che definisce le chiavi di configurazione a livello di root:

{
  "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"
}

Carica la configurazione

Successivamente, carica il file JSON in 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);

Utilizza le variabili di ambiente

Puoi anche inizializzare GoogleAdsClient utilizzando le variabili di ambiente:

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);

Nota: poiché GoogleAdsConfig.OAuth2Mode viene impostato per impostazione predefinita su APPLICATION, quando esegui l'autenticazione con un service account utilizzando GOOGLE_ADS_JSON_KEY_FILE_PATH, assicurati di impostare anche GOOGLE_ADS_OAUTH2_MODE=SERVICE_ACCOUNT.

Consulta l'elenco completo delle variabili di ambiente supportate.

Utilizza App.config

Nelle applicazioni .NET Framework, tutte le impostazioni specifiche dell'API Google Ads vengono archiviate nel nodo GoogleAdsApi del file App.config. Una configurazione App.config tipica è la seguente:

<?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>

Per caricare le impostazioni di configurazione da un file App.config, chiama il metodo LoadFromDefaultAppConfigSection su un oggetto 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);

Specifica un file di configurazione App.config separato

Se non vuoi che il tuo App.config sia disordinato, puoi spostare la configurazione specifica della libreria nel relativo file di configurazione utilizzando la proprietà configSource:

1. Specifica un configSource nel tuo App.config. Modifica il file App.config per fare riferimento a un file di configurazione esterno:

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

2. Specifica i contenuti del file di configurazione. Crea un altro file di configurazione con il nome specificato in configSource (GoogleAdsApi.config) e sposta il nodo di configurazione GoogleAdsApi da App.config in questo file:

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

3. Aggiorna le regole di build nel file .csproj. Includi il nuovo file di configurazione nel progetto e imposta la proprietà Copia nella directory di output su Copia sempre. Ricompila ed esegui il progetto in modo che l'applicazione acquisisca i valori dal nuovo file di configurazione.

Utilizza uno stream generico

Puoi anche caricare la configurazione, o parti di essa, da uno stream generico, anche crittografato:

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);

Campi di configurazione

Le sezioni seguenti elencano le impostazioni supportate dalla libreria .NET di Google Ads.

Impostazioni di connettività

• Timeout: utilizza questa chiave per impostare il timeout del servizio in millisecondi. Il valore predefinito viene impostato in base all'impostazione method_config/timeout in googleads_grpc_service_config.json. Imposta un valore inferiore se devi applicare un limite più breve per il tempo massimo di una chiamata API. Puoi impostare il timeout su 2 ore o più, ma l'API potrebbe comunque scadere per richieste con tempi di esecuzione estremamente lunghi e restituire un errore DEADLINE_EXCEEDED.
• ProxyServer: impostalo sull'URL del server proxy HTTP se utilizzi un proxy per connetterti a internet.
• ProxyUser: impostalo sul nome utente richiesto per l'autenticazione con il server proxy. Lascia vuoto questo campo se non è richiesto un nome utente.
• ProxyPassword: imposta questo valore sulla password di ProxyUser se hai impostato un valore per ProxyUser.
• ProxyDomain: impostalo sul dominio per ProxyUser se il tuo server proxy richiede l'impostazione di un dominio.
• MaxReceiveMessageLengthInBytes: utilizza questa impostazione per aumentare le dimensioni massime della risposta dell'API che la libreria client può gestire. Il valore predefinito è 64 MB.
• MaxMetadataSizeInBytes: utilizza questa impostazione per aumentare la dimensione massima della risposta di errore dell'API che la libreria client può gestire. Il valore predefinito è 16 MB.

Regola le impostazioni MaxReceiveMessageLengthInBytes e MaxMetadataSizeInBytes per correggere determinati errori ResourceExhausted. Queste impostazioni risolvono gli errori nel formato:

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

In questo esempio, l'errore è dovuto alle dimensioni del messaggio (423184132 bytes) che sono superiori a quelle che la libreria può gestire (67108864 bytes). Aumenta MaxReceiveMessageLengthInBytes a 500000000 per evitare questo errore. Tieni presente che l'errore indica anche che il tuo codice ha gestito un oggetto di risposta di dimensioni significative (ad esempio un SearchGoogleAdsResponse di grandi dimensioni). Ciò potrebbe avere implicazioni sulle prestazioni del tuo codice a causa dell'heap di oggetti di grandi dimensioni di .NET. Se questo diventa un problema di prestazioni, potresti dover valutare come riorganizzare le chiamate API o riprogettare parti della tua app.

Impostazioni OAuth2

Quando utilizzi OAuth 2.0 per autorizzare le chiamate ai server dell'API Google Ads, devi impostare le seguenti chiavi di configurazione:

• AuthorizationMethod: impostato su OAuth2.
• OAuth2Mode: impostato su APPLICATION o SERVICE_ACCOUNT.
• OAuth2ClientId: imposta questo valore sull'ID client OAuth 2.0.
• OAuth2ClientSecret: imposta questo valore sul client secret OAuth 2.0.
• OAuth2Scope: imposta questo valore su ambiti diversi se vuoi autorizzare i token OAuth 2.0 per più API. Questa impostazione è facoltativa.
• UseApplicationDefaultCredentials: imposta questo valore su true per l'autenticazione utilizzando Credenziali predefinite dell'applicazione (supportate in Google.Ads.GoogleAds v24.1.0 e versioni successive; config.LoadFromEnvironmentVariables() legge la variabile di ambiente USE_APPLICATION_DEFAULT_CREDENTIALS senza prefisso).
• Credentials: (solo runtime, supportato in v27.0.0 e versioni successive) inserisce un'istanza ICredential o GoogleCredential pre-costruita direttamente su GoogleAdsConfig in fase di runtime.

Se utilizzi OAuth2Mode == APPLICATION, devi impostare le seguenti chiavi di configurazione aggiuntive:

• OAuth2RefreshToken: imposta questo valore su un token di aggiornamento OAuth 2.0 pregenerato se vuoi riutilizzare i token OAuth 2.0. Questa impostazione è facoltativa.
• OAuth2RedirectUri: imposta questo valore sull'URL di reindirizzamento OAuth 2.0. Questa impostazione è facoltativa.

Per maggiori dettagli, consulta le seguenti guide:

• Flusso dell'applicazione desktop OAuth
• Flusso dell'applicazione web OAuth

Se utilizzi OAuth2Mode == SERVICE_ACCOUNT, devi impostare le seguenti chiavi di configurazione aggiuntive:

• OAuth2SecretsJsonPath: imposta questo valore sul percorso del file della chiave JSON OAuth 2.0.
• OAuth2PrnEmail: imposta questo valore sull'indirizzo email dell'account di cui stai eseguendo la simulazione quando utilizzi la delega a livello di dominio di Google Workspace. Questa impostazione è facoltativa.

Per ulteriori dettagli, consulta la guida al flusso dei service account OAuth.

Impostazioni di trasporto

• UseGrpcCore: imposta questa impostazione su true per utilizzare la libreria Grpc.Core come livello di trasporto sottostante. Consulta Utilizza la libreria Grpc.Core.

Impostazioni dell'API Google Ads

Le seguenti impostazioni sono specifiche per l'API Google Ads:

• LoginCustomerId: l'ID cliente del cliente autorizzato da utilizzare nella richiesta, senza trattini (-).
• LinkedCustomerId: questa intestazione è obbligatoria solo per i metodi che aggiornano le risorse di un'entità quando l'autorizzazione viene concessa tramite gli Account collegati nell'interfaccia utente di Google Ads (risorsa AccountLink nell'API Google Ads). Imposta questo valore sull'ID cliente del fornitore di dati che aggiorna le risorse dell'ID cliente specificato. Deve essere impostato senza trattini (-). Scopri di più sugli account collegati.