Присоединяйтесь к нам в прямом эфире на Discord- сервере сообщества Google Advertising and Measurement и на YouTube 23 июля в 10:00 утра по восточному времени! Мы обсудим новые функции, добавленные в версии 25 API Google Ads.

Эта страница переведена с помощью Cloud Translation API.

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

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

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

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

GoogleAdsConfig config = new GoogleAdsConfig()
{
    DeveloperToken = "******",
    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=""/>

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

Чтобы загрузить параметры конфигурации из файла 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": "",

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

    "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":
    {
        "DeveloperToken": "******",
        "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.
  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);

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

Ниже приведён список настроек, поддерживаемых библиотекой 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 МБ.

Отрегулируйте параметры MaxReceiveMessageLengthInBytes и MaxMetadataSizeInBytes , чтобы исправить некоторые ошибки ResourceExhausted . Эти параметры устраняют ошибки вида Status(StatusCode="ResourceExhausted",Detail="Received message larger than max (423184132 versus 67108864)" .
В этом примере ошибка вызвана тем, что размер сообщения ( 423184132 bytes ) превышает возможности библиотеки ( 67108864 bytes ). Чтобы избежать этой ошибки, увеличьте значение MaxReceiveMessageLengthInBytes до 500000000 .
Обратите внимание, что ошибка также указывает на то, что ваш код обработал значительно большой объект Response (например, большой объект SearchGoogleAdsResponse ). Это может повлиять на производительность вашего кода из-за использования в .NET функции Large Object Heap . Если это станет проблемой производительности, вам, возможно, придется изучить, как реорганизовать вызовы API или перепроектировать некоторые части вашего приложения.

Настройки 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 .

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

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

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

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

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

Конфигурация Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.