Konfiguration

Die Google Ads API-Clientbibliothek bietet mehrere Konfigurationseinstellungen, mit denen sich das Bibliotheksverhalten anpassen lässt.

Bibliothek zur Laufzeit konfigurieren

Die bevorzugte Methode zum Konfigurieren der Clientbibliothek ist die Initialisierung eines GoogleAdsConfig-Objekts zur Laufzeit:

GoogleAdsConfig config = new GoogleAdsConfig()
{
    DeveloperToken = "******",
    OAuth2Mode = "APPLICATION",
    OAuth2ClientId = "******.apps.googleusercontent.com",
    OAuth2ClientSecret = "******",
    OAuth2RefreshToken = "******"
};

GoogleAdsClient client = new GoogleAdsClient(config);

Alternative Konfigurationsoptionen

Sie haben außerdem einige zusätzliche Optionen zum Konfigurieren der Clientbibliothek. Wenn Sie diese aktivieren möchten, fügen Sie dem Projekt Google.Ads.GoogleAds.Extensions in Ihrem Projekt eine Nuget-Referenz hinzu.

Wenn Sie eine dieser Optionen verwenden, werden die Konfigurationseinstellungen nicht automatisch übernommen. Sie sollten sie wie unten beschrieben explizit laden.

Mit App.config konfigurieren

Alle Einstellungen für Google Ads API werden im Knoten GoogleAdsApi der Datei App.config gespeichert. Eine typische Konfiguration für App.config sieht so aus:

<?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=""/>

    <!-- API-specific settings -->
    <add key="DeveloperToken" value="******"/>

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

Wenn Sie Konfigurationseinstellungen aus einer App.config-Datei laden möchten, rufen Sie die Methode LoadFromDefaultAppConfigSection für ein GoogleAdsConfig-Objekt auf:

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

Separate App.config-Datei angeben

Wenn Sie Ihr App.config nicht überladen möchten, können Sie die bibliotheksspezifische Konfiguration mit der Property configSource in eine eigene Konfigurationsdatei verschieben.

Schritt 1: configSource in App.config angeben

Ändern Sie den App.config so:

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

Schritt 2: Inhalt der Konfigurationsdatei festlegen

Erstellen Sie jetzt eine weitere Konfigurationsdatei mit dem auf configSource angegebenen Namen und verschieben Sie den Konfigurationsknoten aus App.config in diese Datei:

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

Schritt 3: Build-Regeln in CCS Projekt korrigieren

Fügen Sie schließlich eine neue Konfigurationsdatei in Ihr Projekt ein. Ändern Sie die Attribute dieser Datei zu Immer in Ausgabeordner kopieren.

Erstellen Sie nun Ihr Projekt und führen Sie es aus. Ihre Anwendung ruft dann Werte aus der neuen Konfigurationsdatei ab.

Konfiguration mit einer benutzerdefinierten JSON-Datei

Sie können eine IConfigurationRoot-Instanz verwenden, um die Clientbibliothek zu konfigurieren.

JSON-Datei erstellen

Erstellen Sie eine JSON-Datei mit dem Namen GoogleAdsApi.json, die eine ähnliche Struktur wie die Datei App.config hat.

{
    "Timeout": "2000",

    "ProxyServer": "http://localhost:8888",
    "ProxyUser": "",
    "ProxyPassword": "",
    "ProxyDomain": "",

    "DeveloperToken": "******",

    "OAuth2Mode": "APPLICATION",
    "OAuth2ClientId": "******.apps.googleusercontent.com",
    "OAuth2ClientSecret": "******",
    "OAuth2RefreshToken": "******",
}

Konfiguration laden

Als Nächstes laden Sie die JSON-Datei in ein IConfigurationRoot.

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

Konfiguration mit settings.json

Das Verfahren hier ähnelt einem benutzerdefinierten JSON-Code, mit der Ausnahme, dass sich die Schlüssel in einem Abschnitt mit dem Namen GoogleAdsApi befinden sollten:

{
    "GoogleAdsApi":
    {
        "DeveloperToken": "******",
        "OAuth2Mode": "APPLICATION",
        "OAuth2ClientId": "******.apps.googleusercontent.com",
        "OAuth2ClientSecret": "******",
        "OAuth2RefreshToken": "******",
        ...
    }
    // More settings...
}

Als Nächstes können Sie die IConfiguration-Instanz auf Ihrer Seite verwenden:

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

Konfiguration mithilfe von Umgebungsvariablen

Sie können GoogleAdsClient auch mithilfe von Umgebungsvariablen initialisieren:

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

Sehen Sie sich die vollständige Liste der unterstützten Umgebungsvariablen an.

Felder für die Konfiguration

Im Folgenden finden Sie eine Liste der Einstellungen, die in der Google Ads .NET-Bibliothek unterstützt werden.

Konnektivitätseinstellungen

  • Timeout: Verwenden Sie diesen Schlüssel, um das Zeitlimit des Dienstes in Millisekunden festzulegen. Der Standardwert basiert auf der Einstellung method_config/timeout in googleads_gRPC_service_config.json. Legen Sie einen niedrigeren Wert fest, wenn Sie ein kürzeres Limit für die maximale Zeit für einen API-Aufruf erzwingen müssen. Sie können das Zeitlimit auf 2 Stunden oder mehr festlegen. Die API kann jedoch trotzdem extrem lange Anfragen mit langer Ausführungszeit zurückgeben und den Fehler DEADLINE_EXCEEDED zurückgeben.
  • ProxyServer: Legen Sie die URL auf den HTTP-Proxyserver fest, wenn Sie einen Proxy für die Verbindung mit dem Internet verwenden.
  • ProxyUser: Geben Sie hier den Nutzernamen an, den Sie für die Authentifizierung auf dem Proxyserver benötigen. Lassen Sie dieses Feld leer, wenn kein Nutzername erforderlich ist.
  • ProxyPassword: Legen Sie dieses Passwort auf ProxyUser fest, wenn Sie einen Wert für ProxyUser festgelegt haben.
  • ProxyDomain: Legen Sie dies auf die Domain für ProxyUser fest, wenn Ihr Proxyserver einen festlegen muss.
  • MaxReceiveMessageLengthInBytes: Verwenden Sie diese Einstellung, um die maximale Größe der API-Antwort zu erhöhen, die die Clientbibliothek verarbeiten kann. Der Standardwert beträgt 64 MB.
  • MaxMetadataSizeInBytes: Verwenden Sie diese Einstellung, um die maximale Größe der API-Fehlerantwort zu erhöhen, die die Clientbibliothek verarbeiten kann. Der Standardwert ist 16 MB.

Passen Sie die Einstellungen MaxReceiveMessageLengthInBytes und MaxMetadataSizeInBytes an, um bestimmte ResourceExhausted-Fehler zu beheben. Diese Einstellungen beheben Fehler im Format Status(StatusCode="ResourceExhausted",Detail="Received message larger than max (423184132 versus 67108864)".

In diesem Beispiel liegt der Fehler daran, dass die Nachrichtengröße (423184132 bytes) größer als die Kapazität der Bibliothek ist (67108864 bytes). Erhöhen Sie MaxReceiveMessageLengthInBytes auf 500000000, um diesen Fehler zu vermeiden.

Der Fehler weist auch darauf hin, dass Ihr Code ein deutlich umfangreiches Antwortobjekt verarbeitet hat (z. B. ein großes SearchGoogleAdsResponse). Dies kann sich auf die Leistung Ihres Codes auswirken, da .NETs Large Object Heap. Wenn dies zu Leistungseinbußen führt, müssen Sie möglicherweise herausfinden, wie Sie Ihre API-Aufrufe neu organisieren oder Teile Ihrer Anwendung neu gestalten können.

OAuth2-Einstellungen

Wenn Sie OAuth2 verwenden, um Ihre Aufrufe an die Google Ads API-Server zu autorisieren, sollten Sie die folgenden Konfigurationsschlüssel festlegen:

  • AuthorizationMethod: Legen Sie OAuth2 fest.
  • OAuth2Mode: Wird auf APPLICATION oder SERVICE_ACCOUNT festgelegt.
  • OAuth2ClientId: Legen Sie für diesen Wert Ihre OAuth2-Client-ID fest.
  • OAuth2ClientSecret: Legen Sie diesen Wert auf den OAuth2-Clientschlüssel fest.
  • OAuth2Scope: Legen Sie diesen Wert auf verschiedene Bereiche fest, wenn Sie OAuth2-Tokens für mehrere APIs autorisieren möchten. Diese Einstellung ist optional.

Wenn Sie OAuth2Mode == APPLICATION verwenden, müssen Sie die folgenden zusätzlichen Konfigurationsschlüssel festlegen.

  • OAuth2RefreshToken: Legen Sie für diesen Wert ein vorgeneriertes OAuth2-Aktualisierungstoken fest, wenn Sie OAuth2-Tokens wiederverwenden möchten. Diese Einstellung ist optional.
  • OAuth2RedirectUri: Legen Sie für diesen Wert die OAuth2-Weiterleitungs-URL fest. Diese Einstellung ist optional.

Weitere Informationen finden Sie in den folgenden Leitfäden:

Wenn Sie OAuth2Mode == SERVICE_ACCOUNT verwenden, müssen Sie die folgenden zusätzlichen Konfigurationsschlüssel festlegen.

  • OAuth2PrnEmail: Legen Sie diesen Wert auf die E-Mail-Adresse des Kontos fest, für das Sie die Identität übernehmen.
  • OAuth2SecretsJsonPath: Legen Sie für diesen Wert den Pfad zur OAuth2-JSON-Konfigurationsdatei fest.

Weitere Informationen finden Sie in der Anleitung OAuth-Dienstkonto.

Transporteinstellungen

  • UseGrpcCore: Legen Sie diese Einstellung auf true fest, um die Grpc.Core-Bibliothek als zugrunde liegende Transportebene zu verwenden. Weitere Informationen finden Sie im gRPC-Supportleitfaden.

Google Ads API-Einstellungen

Die folgenden Einstellungen gelten speziell für die Google Ads API.

  • DeveloperToken: Geben Sie hier Ihr Entwicklertoken an.
  • LoginCustomerId: Dies ist die Kundennummer des autorisierten Kunden, der in der Anfrage verwendet wird, ohne Bindestriche (-).
  • LinkedCustomerId: Dieser Header ist nur für Methoden erforderlich, die die Ressourcen einer Entität aktualisieren, wenn sie über verknüpfte Konten in der Google Ads-UI (AccountLink-Ressource in der Google Ads API) berechtigt sind. Legen Sie diesen Wert auf die Kundennummer des Datenanbieters fest, der die Ressourcen der angegebenen Kundennummer aktualisiert. Er sollte ohne Bindestriche (-) festgelegt werden. Weitere Informationen zu verknüpften Konten.