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

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

Как настроить библиотеку во время выполнения

Рекомендуемый способ настройки клиентской библиотеки – инициализация объекта GoogleAdsConfig во время выполнения:

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

Альтернативные варианты настройки

Библиотека также предоставляет дополнительные возможности для загрузки настроек конфигурации. Чтобы включить их, добавьте в проект ссылку NuGet на пакет Google.Ads.GoogleAds.Extensions.

Если вы используете один из этих вариантов, настройки конфигурации не будут выбраны автоматически. Вам нужно будет загрузить их вручную, как показано в следующих разделах. При загрузке настроек из внешних файлов или потоков обязательно обрабатывайте исключения ввода-вывода файлов (например, FileNotFoundException или UnauthorizedAccessException).

Как использовать файл 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" />
  </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>

Чтобы загрузить настройки конфигурации из файла 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" />
  </configSections>
  <GoogleAdsApi configSource="GoogleAdsApi.config" />
</configuration>

  2. Укажите содержимое файла конфигурации. Создайте ещё один файл конфигурации с именем, указанным в configSource (GoogleAdsApi.config), и переместите узел конфигурации GoogleAdsApi из 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": "INSERT_CLIENT_ID.apps.googleusercontent.com",
  "OAuth2ClientSecret": "INSERT_CLIENT_SECRET",
  "OAuth2RefreshToken": "INSERT_REFRESH_TOKEN"
}

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

Затем загрузите файл 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": "INSERT_CLIENT_ID.apps.googleusercontent.com",
    "OAuth2ClientSecret": "INSERT_CLIENT_SECRET",
    "OAuth2RefreshToken": "INSERT_REFRESH_TOKEN"
  }
}

Затем извлеките раздел GoogleAdsApi из экземпляра приложения IConfiguration (например, внедренного ASP.NET Core или созданного с помощью ConfigurationBuilder):

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

Вы также можете загрузить файл settings.json напрямую по пути с помощью метода config.LoadFromSettingsJson(filePath, "GoogleAdsApi") или из переменной среды GOOGLE_ADS_CONFIGURATION_FILE_PATH (EnvironmentVariableNames.CONFIG_FILE_PATH) с помощью метода config.TryLoadFromEnvironmentFilePath.

Как использовать переменные среды

Вы также можете инициализировать 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 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);

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

В следующих разделах перечислены настройки, поддерживаемые библиотекой Google Рекламы для .NET.

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

  • Timeout: используйте этот ключ, чтобы задать тайм-аут сервиса в миллисекундах. Значение по умолчанию задается на основе параметра method_config/timeout в файле googleads_grpc_service_config.json. Укажите меньшее значение, если вам нужно установить более короткий лимит на максимальное время вызова API. Вы можете установить время ожидания на два часа или более, но API все равно может прервать выполнение слишком долгих запросов и вернуть ошибку DEADLINE_EXCEEDED.
  • ProxyServer – укажите URL HTTP-прокси, если вы используете прокси-сервер для подключения к интернету.
  • ProxyUser – укажите имя пользователя, которое требуется для аутентификации на прокси-сервере. Если имя пользователя не требуется, оставьте это поле пустым.
  • ProxyPassword – укажите пароль для ProxyUser, если вы задали значение для ProxyUser.
  • ProxyDomain – укажите домен для ProxyUser, если это требуется для вашего прокси-сервера.
  • MaxReceiveMessageLengthInBytes – используйте эту настройку, чтобы увеличить максимальный размер ответа API, который может обработать клиентская библиотека. Значение по умолчанию – 64 МБ.
  • MaxMetadataSizeInBytes – используйте эту настройку, чтобы увеличить максимальный размер ответа об ошибке API, который может обработать клиентская библиотека. Значение по умолчанию – 16 МБ.

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

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

В этом примере ошибка возникает из-за того, что размер сообщения (423184132 bytes) превышает допустимый для библиотеки (67108864 bytes). Чтобы избежать этой ошибки, увеличьте MaxReceiveMessageLengthInBytes до 500000000. Обратите внимание, что ошибка также указывает на то, что ваш код обработал значительно большой объект ответа (например, большой SearchGoogleAdsResponse). Это может повлиять на производительность вашего кода из-за кучи больших объектов .NET. Если это начнет влиять на производительность, вам, возможно, придется пересмотреть организацию вызовов API или переработать некоторые части приложения.

Настройки OAuth2

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

  • AuthorizationMethod: задайте значение OAuth2.
  • OAuth2Mode: задайте значение APPLICATION или SERVICE_ACCOUNT.
  • OAuth2ClientId: укажите идентификатор клиента OAuth 2.0.
  • OAuth2ClientSecret – укажите секретный код клиента OAuth 2.0.
  • OAuth2Scope – задайте для этого параметра разные области действия, если хотите авторизовать токены OAuth 2.0 для нескольких API. Это необязательная настройка.
  • UseApplicationDefaultCredentials. Установите значение true, чтобы выполнять аутентификацию с помощью Application Default Credentials (поддерживается в Google.Ads.GoogleAds v24.1.0 и более поздних версиях; config.LoadFromEnvironmentVariables() считывает переменную среды USE_APPLICATION_DEFAULT_CREDENTIALS без префикса).
  • Credentials: (только во время выполнения, поддерживается в v27.0.0 и более поздних версиях) Внедрите заранее созданный экземпляр ICredential или GoogleCredential непосредственно в GoogleAdsConfig во время выполнения.

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

  • OAuth2RefreshToken. Если вы хотите повторно использовать токены OAuth 2.0, укажите в качестве значения предварительно сгенерированный токен обновления OAuth 2.0. Это необязательная настройка.
  • OAuth2RedirectUri – задайте для этого параметра URL переадресации OAuth 2.0. Это необязательная настройка.

Подробную информацию можно найти в следующих руководствах:

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

  • OAuth2SecretsJsonPath: укажите путь к файлу JSON с ключом OAuth 2.0.
  • OAuth2PrnEmail – укажите адрес электронной почты аккаунта, от имени которого вы действуете при использовании делегирования доступа к данным в домене Google Workspace. Это необязательная настройка.

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

Настройки транспорта

  • UseGrpcCore – установите для этой настройки значение true, чтобы использовать библиотеку Grpc.Core в качестве базового транспортного уровня. Подробнее о том, как использовать библиотеку Grpc.Core…

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

Ниже перечислены настройки, относящиеся к Google Ads API:

  • LoginCustomerId – идентификатор клиента, который будет использоваться в запросе, без дефисов (-).
  • LinkedCustomerId: этот заголовок требуется только для методов, которые обновляют ресурсы объекта, если разрешение на это было предоставлено через связанные аккаунты в интерфейсе Google Рекламы (ресурс AccountLink в Google Ads API). Укажите идентификатор клиента поставщика данных, который обновляет ресурсы указанного идентификатора клиента. Идентификатор указывается без дефисов (-). Подробнее о связанных аккаунтах…