Конфигурация

Клиентская библиотека Google Ads API предоставляет несколько параметров конфигурации, которые можно использовать для настройки поведения библиотеки.

Настройте библиотеку во время выполнения.

Предпочтительный способ настройки клиентской библиотеки — инициализация объекта GoogleAdsConfig во время выполнения:

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

GoogleAdsClient client = new GoogleAdsClient(config);

Альтернативные параметры конфигурации

Мы также предоставляем несколько дополнительных параметров для настройки клиентской библиотеки: чтобы включить их, добавьте ссылку Nuget на пакет Google.Ads.GoogleAds.Extensions в вашем проекте.

При использовании одного из этих вариантов параметры конфигурации не будут автоматически распознаны: их следует загрузить явно, как показано ниже.

Используйте App.config

Все настройки, специфичные для Google Ads API , хранятся в узле GoogleAdsApi файла App.config . Типичная конфигурация App.config выглядит следующим образом:

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

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

Чтобы загрузить параметры конфигурации из файла App.config , вызовите метод LoadFromDefaultAppConfigSection объекта GoogleAdsConfig :

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

Укажите отдельный файл App.config

Если вы не хотите загромождать файл App.config , вы можете переместить конфигурацию, специфичную для библиотеки, в отдельный конфигурационный файл, используя свойство configSource .

Шаг 1: Укажите configSource в файле App.config.

Измените файл App.config следующим образом:

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

Шаг 2: Укажите содержимое вашего конфигурационного файла.

Теперь создайте еще один конфигурационный файл с именем, указанным в configSource , и переместите узел конфигурации из вашего App.config в этот файл:

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

Шаг 3: Исправьте правила сборки в вашем файле csproj.

Наконец, добавьте в свой проект новый конфигурационный файл. Измените свойства этого файла на «Всегда копировать в выходную папку» .

Теперь соберите и запустите свой проект. Ваше приложение начнет получать значения из нового конфигурационного файла.

Используйте собственный JSON-файл

Для настройки клиентской библиотеки можно использовать экземпляр IConfigurationRoot .

Создайте JSON-файл

Создайте JSON-файл с именем GoogleAdsApi.json , имеющий структуру, аналогичную файлу App.config .

{
    "Timeout": "2000",

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

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

Загрузите конфигурацию

Далее загрузите JSON-файл в объект 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);

Используйте файл settings.json

Процесс здесь аналогичен использованию пользовательского JSON, за исключением того, что ключи должны находиться в разделе с именем GoogleAdsApi :

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

Далее вы можете использовать экземпляр IConfiguration на своей странице:

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

Используйте переменные среды

Также можно инициализировать GoogleAdsClient с помощью переменных окружения: 

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

См. полный список поддерживаемых переменных среды .

Используйте универсальный поток

Вы также можете загрузить конфигурацию или её части из универсального потока, включая зашифрованный: 

GoogleAdsConfig config = new GoogleAdsConfig()
{
  //Set some configuration properties in code.
  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);

Поля конфигурации

Ниже приведён список настроек, поддерживаемых библиотекой Google Ads .NET.

Настройки подключения

  • Timeout : Use this key to set the service timeout in milliseconds. The default value is set based on the method_config/timeout setting in googleads_grpc_service_config.json . Set a lower value if you need to enforce a shorter limit on the maximum time for an API call. You can set the timeout to 2 hours or more, but the API may still time out extremely long-running requests and return a DEADLINE_EXCEEDED error.
  • ProxyServer : Укажите URL-адрес HTTP-прокси-сервера, если вы используете прокси для подключения к интернету.
  • ProxyUser : Укажите имя пользователя, которое необходимо авторизовать на прокси-сервере. Оставьте это поле пустым, если имя пользователя не требуется.
  • ProxyPassword : Установите это значение равным паролю пользователя ProxyUser , если вы задали значение для ProxyUser .
  • ProxyDomain : Укажите домен для ProxyUser , если ваш прокси-сервер требует его указания.
  • MaxReceiveMessageLengthInBytes : Используйте этот параметр для увеличения максимального размера ответа API, который может обработать клиентская библиотека. Значение по умолчанию — 64 МБ.
  • MaxMetadataSizeInBytes : Используйте этот параметр, чтобы увеличить максимальный размер ответа об ошибке API, который может обработать клиентская библиотека. Значение по умолчанию — 16 МБ.

Для устранения некоторых ошибок ResourceExhausted необходимо изменить параметры MaxReceiveMessageLengthInBytes и MaxMetadataSizeInBytes . Эти параметры устраняют ошибки следующего вида: 

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

In this example, the error is due to the message size ( 423184132 bytes ) being larger than what the library can handle ( 67108864 bytes ). Increase MaxReceiveMessageLengthInBytes to 500000000 to avoid this error. Note that the error also indicates that your code handled a significantly large Response object (such as a large SearchGoogleAdsResponse ). This could have performance implications for your code due to .NET's Large Object Heap . If this becomes a performance concern, then you might have to explore how to reorganize your API calls or redesign parts of your app.

Настройки OAuth2

При использовании OAuth2 для авторизации запросов к серверам Google Ads API необходимо установить следующие ключи конфигурации:

  • AuthorizationMethod : Установить значение OAuth2 .
  • OAuth2Mode : Установите значение APPLICATION или SERVICE_ACCOUNT .
  • OAuth2ClientId : Установите это значение равным идентификатору вашего клиента OAuth2.
  • OAuth2ClientSecret : Установите это значение равным секретному ключу вашего клиента OAuth2.
  • OAuth2Scope : Установите это значение на разные области действия, если вы хотите авторизовать токены OAuth2 для нескольких API. Этот параметр необязателен.

Если вы используете OAuth2Mode == APPLICATION , то вам необходимо установить следующие дополнительные ключи конфигурации.

  • OAuth2RefreshToken : Установите это значение на предварительно сгенерированный токен обновления OAuth2, если вы хотите повторно использовать токены OAuth2. Этот параметр необязателен.
  • OAuth2RedirectUri : Установите это значение равным URL-адресу перенаправления OAuth2. Этот параметр необязателен.

Более подробную информацию см. в следующих руководствах:

Если вы используете OAuth2Mode == SERVICE_ACCOUNT , то вам необходимо установить следующие дополнительные ключи конфигурации.

  • OAuth2PrnEmail : Установите это значение равным адресу электронной почты учетной записи, от имени которой вы осуществляете имитацию.
  • OAuth2SecretsJsonPath : Установите это значение равным пути к файлу конфигурации OAuth2 в формате JSON.

Более подробную информацию см. в руководстве по алгоритму работы учетных записей служб OAuth .

Транспортные настройки

Настройки Google Ads API

Приведенные ниже настройки относятся только к API Google Ads.

  • LoginCustomerId : Это идентификатор клиента, авторизованного для использования в запросе, без дефисов ( - ).
  • LinkedCustomerId : This header is only required for methods that update the resources of an entity when permissioned through Linked Accounts in the Google Ads UI ( AccountLink resource in the Google Ads API). Set this value to the customer ID of the data provider that updates the resources of the specified customer ID. It should be set without hyphens ( - ). Learn more about Linked Accounts .