Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Configuration

La bibliothèque cliente de l'API Google Ads fournit plusieurs paramètres de configuration que vous pouvez utiliser pour personnaliser le comportement de la bibliothèque.

Configurer la bibliothèque au moment de l'exécution

La méthode recommandée pour configurer la bibliothèque cliente consiste à initialiser un objet GoogleAdsConfig au moment de l'exécution :

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

Autres options de configuration

La bibliothèque fournit également des options supplémentaires pour charger les paramètres de configuration à partir de appsettings.json, de fichiers JSON personnalisés, de variables d'environnement ou de App.config. Pour les activer, installez le package NuGet Google.Ads.GoogleAds.Extensions dans votre projet :

dotnet add package Google.Ads.GoogleAds.Extensions

Si vous utilisez l'une de ces options, les paramètres de configuration ne sont pas récupérés automatiquement. Vous devez les charger explicitement, comme indiqué dans les sections suivantes. Veillez à gérer les exceptions d'E/S de fichier (telles que FileNotFoundException ou UnauthorizedAccessException) lors du chargement des paramètres à partir de fichiers ou de flux externes.

Utiliser appsettings.json ou settings.json

Dans les applications .NET 8.0 et ASP.NET Core, placez vos clés de configuration dans une section GoogleAdsApi de appsettings.json (ou 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"
  }
}

Ensuite, extrayez la section GoogleAdsApi de l'instance IConfiguration de votre application (par exemple, injectée par ASP.NET Core ou créée avec ConfigurationBuilder) et chargez-la avec 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);

Vous pouvez également charger un fichier appsettings.json ou settings.json directement par chemin d'accès à l'aide de 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);

Vous pouvez également charger le chemin d'accès à partir de la variable d'environnement GOOGLE_ADS_CONFIGURATION_FILE_PATH (EnvironmentVariableNames.CONFIG_FILE_PATH) en appelant config.TryLoadFromEnvironmentFilePath.

Utiliser un fichier JSON personnalisé

Vous pouvez également utiliser une instance IConfigurationRoot pour charger un fichier JSON plat sans section GoogleAdsApi de niveau supérieur.

Créer un fichier JSON

Créez un fichier JSON nommé GoogleAdsApi.json qui définit les clés de configuration au niveau racine :

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

Charger la configuration

Ensuite, chargez le fichier JSON dans 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);

Utiliser des variables d'environnement

Vous pouvez également initialiser GoogleAdsClient à l'aide de variables d'environnement :

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

Consultez la liste complète des variables d'environnement compatibles.

Utiliser App.config

Dans les applications .NET Framework, tous les paramètres spécifiques à l'API Google Ads sont stockés dans le nœud GoogleAdsApi du fichier App.config. Voici un exemple de configuration App.config :

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

Pour charger les paramètres de configuration à partir d'un fichier App.config, appelez la méthode LoadFromDefaultAppConfigSection sur un objet 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);

Spécifier un fichier App.config distinct

Si vous ne souhaitez pas encombrer votre fichier App.config, vous pouvez déplacer la configuration spécifique à la bibliothèque dans son propre fichier de configuration à l'aide de la propriété configSource :

Spécifiez un configSource dans votre App.config. Modifiez votre App.config pour référencer un fichier de configuration externe :

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

Spécifiez le contenu de votre fichier de configuration. Créez un autre fichier de configuration portant le nom que vous avez spécifié dans configSource (GoogleAdsApi.config), puis déplacez le nœud de configuration GoogleAdsApi de votre App.config vers ce fichier :
```
<?xml version="1.0" encoding="utf-8" ?>
<GoogleAdsApi>
  
</GoogleAdsApi>
```
Mettez à jour les règles de compilation dans votre .csproj. Incluez le nouveau fichier de configuration dans votre projet et définissez sa propriété Copy to Output Directory (Copier dans le répertoire de sortie) sur Copy always (Toujours copier). Recompilez et exécutez votre projet pour que votre application récupère les valeurs du nouveau fichier de configuration.

Utiliser un flux générique

Vous pouvez également charger la configuration, ou des parties de celle-ci, à partir d'un flux générique, y compris un flux chiffré :

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

Champs de configuration

Les sections suivantes listent les paramètres compatibles avec la bibliothèque .NET Google Ads.

Paramètres de connectivité

Timeout : utilisez cette clé pour définir le délai avant expiration du service en millisecondes. La valeur par défaut est définie en fonction du paramètre method_config/timeout dans googleads_grpc_service_config.json. Définissez une valeur inférieure si vous devez appliquer une limite plus courte pour la durée maximale d'un appel d'API. Vous pouvez définir le délai avant expiration sur deux heures ou plus, mais l'API peut toujours expirer pour les requêtes extrêmement longues et renvoyer une erreur DEADLINE_EXCEEDED.
ProxyServer : définissez cette option sur l'URL du serveur proxy HTTP si vous utilisez un proxy pour vous connecter à Internet.
ProxyUser : définissez cette option sur le nom d'utilisateur dont vous avez besoin pour vous authentifier auprès du serveur proxy. Laissez ce champ vide si aucun nom d'utilisateur n'est requis.
ProxyPassword : définissez cette valeur sur le mot de passe de ProxyUser si vous avez défini une valeur pour ProxyUser.
ProxyDomain : définissez ce paramètre sur le domaine de ProxyUser si votre serveur proxy en nécessite un.
MaxReceiveMessageLengthInBytes : utilisez ce paramètre pour augmenter la taille maximale de la réponse de l'API que la bibliothèque cliente peut gérer. La valeur par défaut est de 64 Mo.
MaxMetadataSizeInBytes : utilisez ce paramètre pour augmenter la taille maximale de la réponse d'erreur de l'API que la bibliothèque cliente peut gérer. La valeur par défaut est de 16 Mo.

Ajustez les paramètres MaxReceiveMessageLengthInBytes et MaxMetadataSizeInBytes pour corriger certaines erreurs ResourceExhausted. Ces paramètres permettent de résoudre les erreurs de la forme suivante :

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

Dans cet exemple, l'erreur est due au fait que la taille du message (423184132 bytes) est supérieure à ce que la bibliothèque peut gérer (67108864 bytes). Augmentez MaxReceiveMessageLengthInBytes à 500000000 pour éviter cette erreur. Notez que l'erreur indique également que votre code a traité un objet de réponse d'une taille importante (par exemple, un SearchGoogleAdsResponse volumineux). Cela peut avoir des conséquences sur les performances de votre code en raison du tas d'objets volumineux de .NET. Si cela devient un problème de performances, vous devrez peut-être réfléchir à la manière de réorganiser vos appels d'API ou de repenser certaines parties de votre application.

Paramètres OAuth2

Lorsque vous utilisez OAuth 2.0 pour autoriser vos appels auprès des serveurs de l'API Google Ads, vous devez définir les clés de configuration suivantes :

Définissez AuthorizationMethod sur OAuth2.
OAuth2Mode : définissez cette valeur sur APPLICATION ou SERVICE_ACCOUNT.
OAuth2ClientId : définissez cette valeur sur votre ID client OAuth 2.0.
OAuth2ClientSecret : définissez cette valeur sur votre code secret du client OAuth 2.0.
OAuth2Scope : définissez cette valeur sur différents champs d'application si vous souhaitez autoriser les jetons OAuth 2.0 pour plusieurs API. Ce paramètre est facultatif.
UseApplicationDefaultCredentials : définissez cette valeur sur true pour vous authentifier à l'aide des identifiants par défaut de l'application (compatibles avec Google.Ads.GoogleAds v24.1.0 et versions ultérieures ; config.LoadFromEnvironmentVariables() lit la variable d'environnement USE_APPLICATION_DEFAULT_CREDENTIALS sans préfixe).
Credentials : (environnement d'exécution uniquement, compatible avec v27.0.0 et versions ultérieures) Injectez une instance ICredential ou GoogleCredential préconstruite directement sur GoogleAdsConfig au moment de l'exécution.

Si vous utilisez OAuth2Mode == APPLICATION, vous devez définir les clés de configuration supplémentaires suivantes :

OAuth2RefreshToken : définissez cette valeur sur un jeton d'actualisation OAuth 2.0 prégénéré si vous souhaitez réutiliser des jetons OAuth 2.0. Ce paramètre est facultatif.
OAuth2RedirectUri : définissez cette valeur sur l'URL de redirection OAuth 2.0. Ce paramètre est facultatif.

Pour en savoir plus, consultez les guides suivants :

Si vous utilisez OAuth2Mode == SERVICE_ACCOUNT, vous devez définir les clés de configuration supplémentaires suivantes :

OAuth2SecretsJsonPath : définissez cette valeur sur le chemin d'accès au fichier de clé JSON OAuth 2.0.
OAuth2PrnEmail : définissez cette valeur sur l'adresse e-mail du compte dont vous empruntez l'identité lorsque vous utilisez la délégation au niveau du domaine Google Workspace. Ce paramètre est facultatif.

Pour en savoir plus, consultez le guide Flux de compte de service OAuth.

Paramètres de transport

UseGrpcCore : définissez ce paramètre sur true pour utiliser la bibliothèque Grpc.Core comme couche transport sous-jacente. Consultez Utiliser la bibliothèque Grpc.Core.

Paramètres de l'API Google Ads

Les paramètres suivants sont spécifiques à l'API Google Ads :

LoginCustomerId : ID du client autorisé à utiliser dans la requête, sans tirets (-).
LinkedCustomerId : cet en-tête n'est requis que pour les méthodes qui mettent à jour les ressources d'une entité lorsqu'elles sont autorisées via des comptes associés dans l'interface utilisateur Google Ads (ressource AccountLink dans l'API Google Ads). Définissez cette valeur sur le numéro client du fournisseur de données qui met à jour les ressources du numéro client spécifié. Il doit être défini sans trait d'union (-). En savoir plus sur les comptes associés