Konfiguracja

Biblioteka klienta interfejsu Google Ads API udostępnia kilka ustawień konfiguracji, których możesz użyć do dostosowania działania biblioteki.

Konfigurowanie biblioteki w czasie działania

Preferowanym sposobem konfigurowania biblioteki klienta jest zainicjowanie obiektu GoogleAdsConfig w czasie działania:

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

Alternatywne opcje konfiguracji

Biblioteka udostępnia też dodatkowe opcje wczytywania ustawień konfiguracji z appsettings.json, niestandardowych plików JSON, zmiennych środowiskowych lub App.config. Aby je włączyć, zainstaluj w projekcie pakiet NuGet Google.Ads.GoogleAds.Extensions:

dotnet add package Google.Ads.GoogleAds.Extensions

Jeśli użyjesz jednej z tych opcji, ustawienia konfiguracji nie zostaną pobrane automatycznie. Musisz je wczytać bezpośrednio, jak pokazano w sekcjach poniżej. Pamiętaj, aby obsługiwać wyjątki wejścia/wyjścia plików (takie jak FileNotFoundException lub UnauthorizedAccessException) podczas wczytywania ustawień z plików zewnętrznych lub strumieni.

Używanie pliku appsettings.json lub settings.json

W aplikacjach .NET 8.0 i ASP.NET Core umieść klucze konfiguracji w sekcji GoogleAdsApi w pliku appsettings.json (lub 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"
  }
}

Następnie wyodrębnij sekcję GoogleAdsApi z instancji IConfiguration aplikacji (np. wstrzykniętej przez ASP.NET Core lub utworzonej za pomocą ConfigurationBuilder) i wczytaj ją za pomocą 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);

Możesz też wczytać plik appsettings.json lub settings.json bezpośrednio według ścieżki, używając 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);

Możesz też wczytać ścieżkę ze zmiennej środowiskowej GOOGLE_ADS_CONFIGURATION_FILE_PATH (EnvironmentVariableNames.CONFIG_FILE_PATH), wywołując config.TryLoadFromEnvironmentFilePath.

Używanie niestandardowego pliku JSON

Możesz też użyć instancji IConfigurationRoot, aby wczytać płaski plik JSON bez sekcji GoogleAdsApi najwyższego poziomu.

Tworzenie pliku JSON

Utwórz plik JSON o nazwie GoogleAdsApi.json, który definiuje klucze konfiguracji na poziomie głównym:

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

Wczytywanie konfiguracji

Następnie wczytaj plik JSON do 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);

Używanie zmiennych środowiskowych

Możesz też zainicjować GoogleAdsClient za pomocą zmiennych środowiskowych:

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

Zobacz pełną listę obsługiwanych zmiennych środowiskowych.

Używanie pliku App.config

W aplikacjach .NET Framework wszystkie ustawienia interfejsu Google Ads API są przechowywane w węźle GoogleAdsApi pliku App.config. Typowa konfiguracja App.config wygląda tak:

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

Aby wczytać ustawienia konfiguracji z pliku App.config, wywołaj metodę LoadFromDefaultAppConfigSection na obiekcie 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);

Określanie osobnego pliku App.config

Jeśli nie chcesz, aby plik App.config był przeładowany, możesz przenieść konfigurację biblioteki do osobnego pliku konfiguracji, używając właściwości configSource:

  1. Określ configSource w pliku App.config. Zmodyfikuj plik App.config, aby odwoływał się do zewnętrznego pliku konfiguracji:

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

  2. Określ zawartość pliku konfiguracji. Utwórz kolejny plik konfiguracji o nazwie podanej w configSource (GoogleAdsApi.config) i przenieś węzeł konfiguracji GoogleAdsApi z App.config do tego pliku:

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

  3. Zaktualizuj reguły kompilacji w pliku .csproj. Dołącz nowy plik konfiguracji do projektu i ustaw jego właściwość Kopiuj do katalogu wyjściowego na Zawsze kopiuj. Przebuduj i uruchom projekt, aby aplikacja pobrała wartości z nowego pliku konfiguracji.

Używanie ogólnego strumienia

Możesz też wczytać konfigurację lub jej części z ogólnego strumienia, w tym zaszyfrowanego:

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

Pola konfiguracji

W sekcjach poniżej znajdziesz listę ustawień obsługiwanych przez bibliotekę .NET Google Ads.

Ustawienia połączeń

  • Timeout: użyj tego klucza, aby ustawić limit czasu usługi w milisekundach. Wartość domyślna jest ustawiana na podstawie ustawienia method_config/timeout w googleads_grpc_service_config.json. Ustaw niższą wartość, jeśli chcesz wymusić krótszy limit maksymalnego czasu wywołania interfejsu API. Możesz ustawić limit czasu na 2 godziny lub więcej, ale interfejs API może nadal przekraczać limit czasu w przypadku bardzo długich żądań i zwracać błąd DEADLINE_EXCEEDED.
  • ProxyServer: ustaw tę wartość na adres URL serwera proxy HTTP, jeśli używasz serwera proxy do łączenia się z internetem.
  • ProxyUser: ustaw tę wartość na nazwę użytkownika, która jest wymagana do uwierzytelniania na serwerze proxy. Jeśli nazwa użytkownika nie jest wymagana, pozostaw to pole puste.
  • ProxyPassword: ustaw hasło dla ProxyUser, jeśli ustawisz wartość dla ProxyUser.
  • ProxyDomain: ustaw tę wartość na domenę ProxyUser, jeśli serwer proxy tego wymaga.
  • MaxReceiveMessageLengthInBytes: użyj tego ustawienia, aby zwiększyć maksymalny rozmiar odpowiedzi interfejsu API, którą może obsłużyć biblioteka klienta. Wartością domyślną jest 64 MB.
  • MaxMetadataSizeInBytes: użyj tego ustawienia, aby zwiększyć maksymalny rozmiar odpowiedzi na błąd interfejsu API, którą może obsłużyć biblioteka klienta. Wartością domyślną jest 16 MB.

Dostosuj ustawienia MaxReceiveMessageLengthInBytes i MaxMetadataSizeInBytes, aby naprawić niektóre błędy ResourceExhausted. Te ustawienia dotyczą błędów w formularzu:

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

W tym przykładzie błąd jest spowodowany tym, że rozmiar wiadomości (423184132 bytes) jest większy niż rozmiar, który może obsłużyć biblioteka (67108864 bytes). Aby uniknąć tego błędu, zwiększ wartość MaxReceiveMessageLengthInBytes do 500000000. Zwróć uwagę, że błąd wskazuje również, że Twój kod obsłużył bardzo duży obiekt odpowiedzi (np. duży obiekt SearchGoogleAdsResponse). Może to mieć wpływ na wydajność kodu ze względu na stertę dużych obiektów w .NET. Jeśli zacznie to wpływać na wydajność, być może trzeba będzie przeorganizować wywołania interfejsu API lub przeprojektować części aplikacji.

Ustawienia OAuth2

Jeśli do autoryzowania wywołań serwerów interfejsu Google Ads API używasz protokołu OAuth 2.0, musisz ustawić te klucze konfiguracji:

  • AuthorizationMethod: ustaw wartość OAuth2.
  • OAuth2Mode: ustaw wartość APPLICATION lub SERVICE_ACCOUNT.
  • OAuth2ClientId: ustaw tę wartość na identyfikator klienta OAuth 2.0.
  • OAuth2ClientSecret: ustaw tę wartość na tajny klucz klienta OAuth 2.0.
  • OAuth2Scope: ustaw tę wartość na różne zakresy, jeśli chcesz autoryzować tokeny OAuth 2.0 dla wielu interfejsów API. To ustawienie jest opcjonalne.
  • UseApplicationDefaultCredentials: ustaw tę wartość na true, aby uwierzytelniać za pomocą domyślnego uwierzytelniania aplikacji (obsługiwanego w Google.Ads.GoogleAds v24.1.0 i nowszych; config.LoadFromEnvironmentVariables() odczytuje zmienną środowiskową USE_APPLICATION_DEFAULT_CREDENTIALS bez prefiksu).
  • Credentials: (tylko środowisko wykonawcze, obsługiwane w wersji v27.0.0 i nowszych) wstrzykuje wstępnie skonstruowaną instancję ICredential lub GoogleCredential bezpośrednio do GoogleAdsConfig w środowisku wykonawczym.

Jeśli używasz OAuth2Mode == APPLICATION, musisz ustawić te dodatkowe klucze konfiguracji:

  • OAuth2RefreshToken: ustaw tę wartość na wstępnie wygenerowany token odświeżania OAuth 2.0, jeśli chcesz ponownie używać tokenów OAuth 2.0. To ustawienie jest opcjonalne.
  • OAuth2RedirectUri: ustaw tę wartość na adres URL przekierowania OAuth 2.0. To ustawienie jest opcjonalne.

Więcej informacji znajdziesz w tych przewodnikach:

Jeśli używasz OAuth2Mode == SERVICE_ACCOUNT, musisz ustawić te dodatkowe klucze konfiguracji:

  • OAuth2SecretsJsonPath: ustaw tę wartość na ścieżkę pliku klucza JSON protokołu OAuth 2.0.
  • OAuth2PrnEmail: ustaw tę wartość na adres e-mail konta, pod które się podszywasz, gdy używasz przekazywania dostępu w całej domenie Google Workspace. To ustawienie jest opcjonalne.

Więcej informacji znajdziesz w przewodniku na temat przepływu konta usługi OAuth.

Ustawienia transportu

Ustawienia interfejsu Google Ads API

Te ustawienia są specyficzne dla interfejsu Google Ads API:

  • LoginCustomerId: jest to identyfikator klienta, który ma być użyty w żądaniu, bez łączników (-).
  • LinkedCustomerId: ten nagłówek jest wymagany tylko w przypadku metod, które aktualizują zasoby podmiotu, gdy uprawnienia zostały przyznane za pomocą połączonych kont w interfejsie Google Ads (zasób AccountLink w interfejsie Google Ads API). Ustaw tę wartość na identyfikator klienta dostawcy danych, który aktualizuje zasoby określonego identyfikatora klienta. - nie powinien zawierać łączników. Więcej informacji o połączonych kontach