Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

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

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

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

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

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

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

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

dotnet add package Google.Ads.GoogleAds.Extensions

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

Используйте appsettings.json или settings.json

В приложениях .NET 8.0 и ASP.NET Core поместите ключи конфигурации в раздел GoogleAdsApi файла appsettings.json (или 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"
  }
}

Затем извлеките раздел GoogleAdsApi из экземпляра IConfiguration вашего приложения (например, внедренного ASP.NET Core или созданного с помощью ConfigurationBuilder) и загрузите его с помощью 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);

Вы также можете загрузить файл appsettings.json или settings.json напрямую по пути, используя 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);

Вы также можете загрузить путь из переменной среды GOOGLE_ADS_CONFIGURATION_FILE_PATH (EnvironmentVariableNames.CONFIG_FILE_PATH), вызвав config.TryLoadFromEnvironmentFilePath.

Как использовать собственный JSON-файл

Вы также можете использовать экземпляр IConfigurationRoot, чтобы загрузить простой файл JSON без раздела GoogleAdsApi верхнего уровня.

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

Создайте файл JSON с названием GoogleAdsApi.json, в котором на корневом уровне определены ключи конфигурации:

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

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

Затем загрузите файл JSON в 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);

Использование переменных среды

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

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

Ознакомьтесь с полным списком поддерживаемых переменных среды.

Использование App.config

В приложениях .NET Framework все настройки, относящиеся к 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="" />

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

Чтобы загрузить настройки конфигурации из файла App.config, вызовите метод LoadFromDefaultAppConfigSection для объекта 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);

Как указать отдельный файл конфигурации App.config

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

Укажите 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>

Укажите содержимое файла конфигурации. Создайте ещё один файл конфигурации с именем, указанным в configSource (GoogleAdsApi.config), и переместите узел конфигурации GoogleAdsApi из App.config в этот файл:
```
<?xml version="1.0" encoding="utf-8" ?>
<GoogleAdsApi>
  
</GoogleAdsApi>
```
Обновите правила сборки в файле .csproj. Добавьте новый файл конфигурации в проект и задайте для его свойства Copy to Output Directory (Копировать в выходной каталог) значение Copy always (Всегда копировать). Пересоберите и запустите проект, чтобы приложение получило значения из нового файла конфигурации.

Использовать общий поток

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

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

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

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

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

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 МБ.

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

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). Укажите идентификатор клиента поставщика данных, который обновляет ресурсы указанного идентификатора клиента. Идентификатор указывается без дефисов (-). Подробнее о связанных аккаунтах…