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

Клиентская библиотека 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 . Включите новый конфигурационный файл в свой проект и установите для свойства Copy to Output Directory значение Copy always . Пересоберите и запустите проект, чтобы ваше приложение получало значения из нового конфигурационного файла.

Используйте собственный 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 Ads .NET.

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

• Timeout : Используйте этот ключ для установки таймаута службы в миллисекундах. Значение по умолчанию устанавливается на основе параметра method_config/timeout в файле googleads_grpc_service_config.json . Установите меньшее значение, если вам необходимо установить более короткий лимит на максимальное время выполнения вызова API. Вы можете установить таймаут в 2 часа или более, но 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 функции Large Object Heap . Если это станет проблемой производительности, вам, возможно, придется изучить, как реорганизовать вызовы 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 для аутентификации с использованием учетных данных приложения по умолчанию (поддерживается в 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. Этот параметр необязателен.

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

• Процесс аутентификации OAuth для настольных приложений
• Процесс аутентификации OAuth в веб-приложении

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

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

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

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

• UseGrpcCore : Установите этот параметр в true , чтобы использовать библиотеку Grpc.Core в качестве базового транспортного уровня. См. раздел «Использование библиотеки Grpc.Core .

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

Следующие настройки относятся только к API Google Ads:

• DeveloperToken : необязателен в v27.3.0 и более поздних ( GOOGLE_ADS_DEVELOPER_TOKEN ). Использование токенов разработчиков было прекращено 9 сентября 2026 года ; на сервере API уровни доступа определяются вашим проектом Google Cloud независимо от версии клиентской библиотеки, и серверы API игнорируют заголовок developer-token (до тех пор, пока будущая основная версия Google Ads API не отклонит его). Чтобы опустить или удалить DeveloperToken из вашей конфигурации, используйте Google.Ads.GoogleAds v27.3.0 или более поздней, в которой удалена локальная проверка DeveloperToken на стороне клиента (в более ранних версиях для локальной проверки требовался непустой DeveloperToken ).
• LoginCustomerId : Это идентификатор клиента, авторизованного для использования в запросе, без дефисов ( - ).
• LinkedCustomerId : Этот заголовок необходим только для методов, обновляющих ресурсы сущности при наличии разрешения через связанные учетные записи в пользовательском интерфейсе Google Ads (ресурс AccountLink в API Google Ads). Установите это значение равным идентификатору клиента поставщика данных, обновляющего ресурсы указанного идентификатора клиента. Значение должно быть без дефисов ( - ). Подробнее о связанных учетных записях .