Konfiguracja

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

Konfigurowanie biblioteki w czasie działania

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

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

Alternatywne opcje konfiguracji

Biblioteka udostępnia też dodatkowe opcje wczytywania ustawień konfiguracyjnych. Aby je włączyć, dodaj odwołanie do pakietu NuGet do Google.Ads.GoogleAds.Extensionspakietu w projekcie.

Jeśli użyjesz jednej z tych opcji, ustawienia konfiguracji nie zostaną pobrane automatycznie. Musisz je wczytać w sposób opisany w kolejnych sekcjach. Podczas wczytywania ustawień z plików lub strumieni zewnętrznych pamiętaj o obsłudze wyjątków wejścia/wyjścia plików (np. FileNotFoundException lub UnauthorizedAccessException).

Używanie pliku App.config

Wszystkie ustawienia specyficzne dla 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="" />

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

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

Określanie oddzielnego pliku App.config

Jeśli nie chcesz, aby plik App.config był zbyt obszerny, możesz przenieść konfigurację specyficzną dla biblioteki do osobnego pliku konfiguracyjnego za pomocą właściwości configSource:

  1. Określ configSource w App.config. Zmodyfikuj 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 pliku App.config do tego pliku:

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

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

Używanie niestandardowego pliku JSON

Do skonfigurowania biblioteki klienta możesz użyć instancji IConfigurationRoot.

Tworzenie pliku JSON

Utwórz plik JSON o nazwie GoogleAdsApi.json, który ma podobną strukturę do pliku App.config:

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

Wczytywanie konfiguracji

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

Używanie pliku settings.json

Proces jest podobny do używania niestandardowego pliku JSON, z tym że klucze powinny znajdować się w sekcji o nazwie GoogleAdsApi:

{
  "GoogleAdsApi": {
    "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):

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

Możesz też wczytać plik settings.json bezpośrednio według ścieżki za pomocą config.LoadFromSettingsJson(filePath, "GoogleAdsApi") lub ze zmiennej środowiskowej GOOGLE_ADS_CONFIGURATION_FILE_PATH (EnvironmentVariableNames.CONFIG_FILE_PATH) za pomocą config.TryLoadFromEnvironmentFilePath.

Używanie zmiennych środowiskowych

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

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

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

Używanie ogólnego strumienia

Możesz też wczytać konfigurację lub jej części ze strumienia ogólnego, 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ę Google Ads .NET.

Ustawienia łączności

  • 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: jeśli do łączenia się z internetem używasz serwera proxy, ustaw ten parametr na adres URL serwera proxy HTTP.
  • ProxyUser: ustaw tę wartość na nazwę użytkownika wymaganą do uwierzytelnienia na serwerze proxy. Jeśli nazwa użytkownika nie jest wymagana, pozostaw to pole puste.
  • ProxyPassword: jeśli ustawisz wartość parametru ProxyUser, ustaw ten parametr na hasło do konta ProxyUser.
  • ProxyDomain: ustaw tę wartość na domenę dla ProxyUser, jeśli serwer proxy wymaga ustawienia domeny.
  • 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 o błędzie 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 rozwiązują błędy w formie:

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. Pamiętaj, że błąd wskazuje też, że Twój kod obsłużył znacznie większy obiekt odpowiedzi (np. duży SearchGoogleAdsResponse). Może to mieć wpływ na wydajność kodu ze względu na stertę dużych obiektów w .NET. Jeśli stanie się to problemem z wydajnością, być może trzeba będzie zmienić organizację wywołań interfejsu API lub przeprojektować części aplikacji.

Ustawienia OAuth2

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

  • AuthorizationMethod: ustaw na OAuth2.
  • OAuth2Mode: ustaw na 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ć się za pomocą domyślnego uwierzytelniania aplikacji (obsługiwane w wersji 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) wstrzykiwanie wstępnie utworzonej instancji 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żyć 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ę do pliku JSON klucza OAuth 2.0.
  • OAuth2PrnEmail: ustaw tę wartość na adres e-mail konta, które jest używane do personifikacji podczas korzystania z delegowania w całej domenie Google Workspace. To ustawienie jest opcjonalne.

Więcej informacji znajdziesz w przewodniku Przepływ konta usługi OAuth.

Ustawienia transportu

Ustawienia interfejsu Google Ads API

Te ustawienia są specyficzne dla interfejsu Google Ads API:

  • DeveloperToken: Opcjonalne w wersji v27.3.0 i nowszych (GOOGLE_ADS_DEVELOPER_TOKEN). Tokeny dewelopera zostały wycofane 9 września 2026 r. Na serwerze API poziomy dostępu są określane przez projekt Google Cloud niezależnie od wersji biblioteki klienta, a serwery API ignorują nagłówek developer-token (do czasu, gdy przyszła wersja główna interfejsu Google Ads API go odrzuci). Aby pominąć lub usunąć DeveloperToken z konfiguracji, użyj wersji Google.Ads.GoogleAds v27.3.0 lub nowszej, w której usunięto lokalną walidację po stronie klienta DeveloperToken (wcześniejsze wersje wymagają niepustego pola DeveloperToken do walidacji lokalnej).
  • LoginCustomerId: jest to identyfikator klienta uprawnionego do korzystania z usługi w ramach żądania, bez łączników (-).
  • LinkedCustomerId: ten nagłówek jest wymagany tylko w przypadku metod, które aktualizują zasoby jednostki, gdy uprawnienia są przyznawane 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. Powinien być ustawiony bez łączników (-). Więcej informacji o połączonych kontach