Konfiguration

Die Google Ads API-Clientbibliothek bietet mehrere Konfigurationseinstellungen, mit denen Sie das Verhalten der Bibliothek anpassen können.

Bibliothek zur Laufzeit konfigurieren

Die bevorzugte Methode zum Konfigurieren der Clientbibliothek besteht darin, zur Laufzeit ein GoogleAdsConfig-Objekt zu initialisieren:

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

GoogleAdsClient client = new GoogleAdsClient(config);

Alternative Konfigurationsoptionen

Die Bibliothek bietet auch zusätzliche Optionen zum Laden von Konfigurationseinstellungen. Fügen Sie dazu in Ihrem Projekt einen NuGet-Verweis auf das Google.Ads.GoogleAds.Extensions Paket hinzu.

Wenn Sie eine dieser Optionen verwenden, werden die Konfigurationseinstellungen nicht automatisch übernommen. Sie müssen sie explizit laden, wie in den folgenden Abschnitten beschrieben. Achten Sie darauf, dass Sie bei der Verwendung von Einstellungen aus externen Dateien oder Streams Dateieingabe-/ausgabefehler (z. B. FileNotFoundException oder UnauthorizedAccessException) abfangen.

App.config verwenden

Alle Einstellungen für die Google Ads API werden im Knoten GoogleAdsApi der Datei App.config gespeichert. Eine typische App.config-Konfiguration 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="" />

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

Rufen Sie die Methode LoadFromDefaultAppConfigSection für ein GoogleAdsConfig-Objekt auf, um Konfigurationseinstellungen aus einer App.config-Datei zu laden:

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

Separate App.config-Datei angeben

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

  1. Geben Sie in Ihrer App.config eine configSource an. Ändern Sie Ihre App.config, um auf eine externe Konfigurationsdatei zu verweisen:

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

  2. Geben Sie den Inhalt Ihrer Konfigurationsdatei an. Erstellen Sie eine weitere Konfiguration datei mit dem Namen, den Sie in configSource angegeben haben (GoogleAdsApi.config), und verschieben Sie den Konfigurationsknoten GoogleAdsApi aus Ihrer App.config in diese Datei:

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

  3. Aktualisieren Sie die Build-Regeln in Ihrer .csproj. Fügen Sie die neue Konfigurationsdatei in Ihr Projekt ein und legen Sie die Eigenschaft In Ausgabeverzeichnis kopieren auf Immer kopieren fest. Erstellen Sie Ihr Projekt neu und führen Sie es aus, damit Ihre Anwendung Werte aus der neuen Konfigurationsdatei übernimmt.

Benutzerdefinierte JSON-Datei verwenden

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": "",
  "OAuth2Mode": "APPLICATION",
  "OAuth2ClientId": "INSERT_CLIENT_ID.apps.googleusercontent.com",
  "OAuth2ClientSecret": "INSERT_CLIENT_SECRET",
  "OAuth2RefreshToken": "INSERT_REFRESH_TOKEN"
}

Konfiguration laden

Laden Sie als Nächstes die JSON-Datei in eine IConfigurationRoot-Instanz:

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

settings.json verwenden

Der Vorgang ist hier ähnlich wie bei der Verwendung einer benutzerdefinierten JSON-Datei, mit dem Unterschied, dass sich die Schlüssel in einem Abschnitt mit dem Abschnittsnamen GoogleAdsApi befinden sollten:

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

Extrahieren Sie als Nächstes den Abschnitt GoogleAdsApi aus der IConfiguration-Instanz Ihrer Anwendung (z. B. eingefügt von ASP.NET Core oder erstellt mit ConfigurationBuilder):

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

Alternativ können Sie eine settings.json Datei direkt über den Pfad mit config.LoadFromSettingsJson(filePath, "GoogleAdsApi") oder über die GOOGLE_ADS_CONFIGURATION_FILE_PATH Umgebungsvariable (EnvironmentVariableNames.CONFIG_FILE_PATH) mit config.TryLoadFromEnvironmentFilePath laden.

Umgebungsvariablen verwenden

Sie können den GoogleAdsClient auch mit Umgebungsvariablen initialisieren:

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

Die vollständige Liste der unterstützten Umgebungsvariablen finden Sie hier.

Generischen Stream verwenden

Sie können die Konfiguration oder Teile davon auch aus einem generischen Stream laden, einschließlich eines verschlüsselten Streams:

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

Konfigurationsfelder

In den folgenden Abschnitten sind die Einstellungen aufgeführt, die von der Google Ads .NET-Bibliothek unterstützt werden.

Konnektivitätseinstellungen

  • Timeout: Mit diesem Schlüssel können Sie das Dienst-Timeout in Millisekunden festlegen. Der Standardwert wird basierend auf der method_config/timeout Einstellung in googleads_grpc_service_config.json festgelegt. Legen Sie einen niedrigeren Wert fest, wenn Sie ein kürzeres Limit für die maximale Zeit für einen API-Aufruf erzwingen möchten. Sie können das Timeout auf 2 Stunden oder mehr festlegen. Die API kann jedoch bei extrem langen Anfragen trotzdem ein Timeout verursachen und den Fehler DEADLINE_EXCEEDED zurückgeben.
  • ProxyServer: Legen Sie dies auf die HTTP-Proxyserver-URL fest, wenn Sie einen Proxy verwenden, um eine Verbindung zum Internet herzustellen.
  • ProxyUser: Legen Sie dies auf den Nutzernamen fest, den Sie zur Authentifizierung beim Proxyserver benötigen. Lassen Sie dieses Feld leer, wenn kein Nutzername erforderlich ist.
  • ProxyPassword: Legen Sie dies auf das Passwort von 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 eine solche erfordert.
  • MaxReceiveMessageLengthInBytes: Mit dieser Einstellung können Sie die maximale Größe der API-Antwort erhöhen, die von der Clientbibliothek verarbeitet werden kann. Der Standardwert ist 64 MB.
  • MaxMetadataSizeInBytes: Mit dieser Einstellung können Sie die maximale Größe der API-Fehlerantwort erhöhen, die von der Clientbibliothek verarbeitet werden kann. Der Standardwert ist 16 MB.

Passen Sie die Einstellungen MaxReceiveMessageLengthInBytes und MaxMetadataSizeInBytes an, um bestimmte ResourceExhausted-Fehler zu beheben. Diese Einstellungen beheben Fehler der folgenden Art:

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

In diesem Beispiel ist der Fehler darauf zurückzuführen, dass die Nachrichtengröße (423184132 bytes) größer ist als die Größe, die von der Bibliothek verarbeitet werden kann (67108864 bytes). Erhöhen Sie MaxReceiveMessageLengthInBytes auf 500000000, um diesen Fehler zu vermeiden. Der Fehler weist auch darauf hin, dass Ihr Code ein sehr großes Antwortobjekt (z. B. eine große SearchGoogleAdsResponse) verarbeitet hat. Dies kann aufgrund des .NET-Large Object Heap Auswirkungen auf die Leistung Ihres Codes haben. Wenn dies zu einem Leistungsproblem wird, müssen Sie möglicherweise Ihre API-Aufrufe neu organisieren oder Teile Ihrer App neu entwerfen.

OAuth 2.0-Einstellungen

Wenn Sie OAuth 2.0 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: Legen Sie APPLICATION oder SERVICE_ACCOUNT fest.
  • OAuth2ClientId: Legen Sie diesen Wert auf Ihre OAuth 2.0-Client-ID fest.
  • OAuth2ClientSecret: Legen Sie diesen Wert auf Ihren OAuth 2.0-Clientschlüssel fest.
  • OAuth2Scope: Legen Sie diesen Wert auf verschiedene Bereiche fest, wenn Sie OAuth 2.0-Tokens für mehrere APIs autorisieren möchten. Diese Einstellung ist optional.
  • UseApplicationDefaultCredentials: Legen Sie diesen Wert auf true fest, um sich mit Standardanmeldedaten für Anwendungen zu authentifizieren (unterstützt in Google.Ads.GoogleAds v24.1.0 und höher; config.LoadFromEnvironmentVariables() liest die Umgebungsvariable USE_APPLICATION_DEFAULT_CREDENTIALS ohne Präfix).
  • Credentials: (Nur zur Laufzeit, unterstützt in v27.0.0 und höher) Fügen Sie zur Laufzeit eine vorkonstruierte ICredential oder GoogleCredential-Instanz direkt in GoogleAdsConfig ein.

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

  • OAuth2RefreshToken: Legen Sie diesen Wert auf ein vorab generiertes OAuth 2.0-Aktualisierungstoken fest, wenn Sie OAuth 2.0-Tokens wiederverwenden möchten. Diese Einstellung ist optional.
  • OAuth2RedirectUri: Legen Sie diesen Wert auf die OAuth 2.0-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:

  • OAuth2SecretsJsonPath: Legen Sie diesen Wert auf den Pfad der JSON-Schlüsseldatei für OAuth 2.0 fest.
  • OAuth2PrnEmail: Legen Sie diesen Wert auf die E-Mail-Adresse des Kontos fest, das Sie bei der domainweiten Google Workspace-Delegierung verwenden. Diese Einstellung ist optional.

Weitere Informationen finden Sie im Leitfaden zum OAuth-Dienstkontoablauf.

Übertragungseinstellungen

  • UseGrpcCore: Legen Sie diese Einstellung auf true fest, um die Grpc.Core-Bibliothek als zugrunde liegende Transportschicht zu verwenden. Weitere Informationen finden Sie unter Die Grpc.Core Bibliothek verwenden.

Google Ads API-Einstellungen

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

  • LoginCustomerId: Dies ist die Kundennummer des autorisierten Kunden, die in der Anfrage verwendet werden soll, ohne Bindestriche (-).
  • LinkedCustomerId: Dieser Header ist nur für Methoden erforderlich, die die Ressourcen einer Entität aktualisieren, wenn die Berechtigung über verknüpfte Konten in der Google Ads-Benutzeroberfläche erteilt wurde (AccountLink-Ressource in der Google Ads API). Legen Sie diesen Wert auf die Kundennummer des Datenanbieters fest, der die Ressourcen der angegebenen Kundennummer aktualisiert. Sie sollte ohne Bindestriche (-) festgelegt werden. Weitere Informationen zu verknüpften Konten.