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

Preferowany sposób konfigurowania biblioteki klienta polega na zainicjowaniu obiektu GoogleAdsConfig w czasie działania:

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

GoogleAdsClient client = new GoogleAdsClient(config);

Alternatywne opcje konfiguracji

Udostępniamy też kilka dodatkowych opcji konfigurowania biblioteki klienta. Aby je włączyć, dodaj w projekcie odwołanie Nuget do Google.Ads.GoogleAds.Extensions pakietu.

Jeśli używasz jednej z tych opcji, ustawienia konfiguracyjne nie są pobierane automatycznie. Musisz je wczytać w sposób opisany poniżej.

Używanie pliku App.config

Wszystkie ustawienia dotyczące 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"></section>
  </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>

Aby wczytać ustawienia konfiguracyjne z pliku App.config, wywołaj metodę LoadFromDefaultAppConfigSection na obiekcie GoogleAdsConfig:

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ł zbyt długi, możesz przenieść konfigurację biblioteki do osobnego pliku konfiguracyjnego za pomocą właściwości configSource.

Krok 1. Określ configSource w pliku App.config

Zmodyfikuj plik App.config tak, aby wyglądał tak:

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

Krok 2. Określ zawartość pliku konfiguracyjnego

Teraz utwórz kolejny plik konfiguracyjny o nazwie określonej w configSource i przenieś do niego węzeł konfiguracji z pliku App.config:

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

Krok 3. Popraw reguły kompilacji w pliku csproj

Na koniec dodaj nowy plik konfiguracyjny do projektu. Zmień właściwości tego pliku na Zawsze kopiuj do folderu wyjściowego.

Teraz skompiluj i uruchom projekt. Twoja aplikacja zacznie pobierać wartości z nowego pliku konfiguracyjnego.

Używanie niestandardowego pliku JSON

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

Utwórz plik JSON

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

{
    "Timeout": "2000",

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

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

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

Wczytaj konfigurację

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":
    {
        "DeveloperToken": "******",
        "OAuth2Mode": "APPLICATION",
        "OAuth2ClientId": "******.apps.googleusercontent.com",
        "OAuth2ClientSecret": "******",
        "OAuth2RefreshToken": "******",
        ...
    }
    // More settings...
}

Następnie możesz użyć instancji IConfiguration na stronie:

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

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 z ogólnego strumienia, w tym zaszyfrowanego:

GoogleAdsConfig config = new GoogleAdsConfig()
{
  //Set some configuration properties in code.
  DeveloperToken = "******",
  OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
};

// Load your encrypted data from a file.

CryptoStream strm = ....

StreamReader rdr = new StreamReader(strm);
// Configure the OAuth credentials from the encrypted file.
config.LoadOAuth2SecretsFromStream(rdr);

GoogleAdsClient client = new GoogleAdsClient(config);

Pola konfiguracji

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

Ustawienia łączności

  • Timeout (Limit czasu): 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. Jeśli chcesz wymusić krótszy limit maksymalnego czasu wywołania interfejsu API, ustaw niższą wartość. Możesz ustawić limit czasu na 2 godziny lub więcej, ale interfejs API może nadal przekraczać limit czasu w przypadku bardzo długotrwałych żądań i zwracać błąd DEADLINE_EXCEEDED.
  • ProxyServer(Serwer proxy): jeśli do łączenia się z internetem używasz serwera proxy, ustaw ten adres URL serwera proxy HTTP.
  • ProxyUser(Użytkownik proxy): ustaw tę nazwę użytkownika, która jest wymagana do uwierzytelnienia na serwerze proxy. Jeśli nazwa użytkownika nie jest wymagana, pozostaw to pole puste.
  • ProxyPassword(Hasło proxy): jeśli ustawisz wartość ProxyUser, ustaw to hasło ProxyUser.
  • ProxyDomain(Domena proxy): jeśli serwer proxy wymaga ustawienia domeny dla ProxyUser, ustaw tę domenę.
  • MaxReceiveMessageLengthInBytes(Maksymalna długość wiadomości przychodzącej w bajtach): użyj tego ustawienia, aby zwiększyć maksymalny rozmiar odpowiedzi interfejsu API, którą może obsłużyć biblioteka klienta. Wartość domyślna to 64 MB.
  • MaxMetadataSizeInBytes(Maksymalny rozmiar metadanych w bajtach): 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ść domyślna to 16 MB.

Dostosuj ustawienia MaxReceiveMessageLengthInBytes i MaxMetadataSizeInBytes, aby naprawić niektóre błędy ResourceExhausted. Te ustawienia rozwiązują błędy w postaci 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ługuje znacznie większy obiekt Response (np. duży SearchGoogleAdsResponse). Może to mieć wpływ na wydajność kodu ze względu na stertę dużych obiektów . Jeśli stanie się to problemem z wydajnością, być może trzeba będzie zmienić sposób organizacji 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 OAuth2, ustaw te klucze konfiguracji:

  • AuthorizationMethod (Metoda autoryzacji): ustaw wartość OAuth2.
  • OAuth2Mode (Tryb OAuth2): ustaw wartość APPLICATION lub SERVICE_ACCOUNT.
  • OAuth2ClientId (Identyfikator klienta OAuth2): ustaw tę wartość na identyfikator klienta OAuth2.
  • OAuth2ClientSecret (Tajny klucz klienta OAuth2): ustaw tę wartość na tajny klucz klienta OAuth2.
  • OAuth2Scope(Zakres OAuth2): jeśli chcesz autoryzować tokeny OAuth2 w przypadku wielu interfejsów API, ustaw tę wartość na różne zakresy. To ustawienie jest opcjonalne.

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

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

Więcej informacji znajdziesz w tych przewodnikach:

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

  • OAuth2PrnEmail(Adres e-mail PRN OAuth2): ustaw tę wartość na adres e-mail konta, które chcesz podszyć.
  • OAuth2SecretsJsonPath(Ścieżka do pliku JSON z tajnymi kluczami OAuth2): ustaw tę wartość na ścieżkę do pliku konfiguracyjnego JSON OAuth2.

Więcej informacji znajdziesz w przewodniku dotyczącym procesu konta usługi OAuth.

Ustawienia transportu

  • UseGrpcCore(Używaj GrpcCore): ustaw tę wartość na true, aby używać biblioteki Grpc.Core jako podstawowej warstwy transportowej. Zobacz Używanie starszej biblioteki Grpc.

Ustawienia interfejsu Google Ads API

Te ustawienia dotyczą interfejsu Google Ads API.

  • DeveloperToken (Token programisty): ustaw tę wartość na token programisty.
  • LoginCustomerId(Identyfikator klienta logowania): jest to identyfikator klienta autoryzowanego do użycia w żądaniu, bez łączników (-).
  • LinkedCustomerId(Identyfikator połączonego klienta): ten nagłówek jest wymagany tylko w przypadku metod, które aktualizują zasoby encji, gdy uprawnienia są przyznawane za pomocą połączonych kont w interfejsie Google Ads (AccountLink w interfejsie Google Ads API). Ustaw tę wartość na identyfikator klienta dostawcy danych, który aktualizuje zasoby określonego identyfikatora klienta. Należy go ustawić bez łączników (-). Więcej informacji o połączonych kontach.