Структура API

В этом руководстве описаны основные компоненты Google Ads API. Google Ads API состоит из ресурсов и сервисов. Ресурс представляет собой объект Google Рекламы, а сервисы извлекают объекты Google Рекламы и управляют ими.

Иерархия объектов

Аккаунт Google Рекламы можно представить как иерархию объектов.

Модель кампании

  • Ресурс верхнего уровня в аккаунте – это клиент.

  • У каждого клиента есть одна или несколько активных кампаний.

  • Каждая кампания содержит одну или несколько групп объявлений, которые используются для логического объединения объявлений.

  • Объявление из группы объявлений – это объявление, которое вы показываете в группе объявлений. В каждой группе объявлений может быть одно или несколько объявлений. Исключение составляют кампании для приложений, в которых может быть только одно объявление на группу.

Кампании с максимальной эффективностью отличаются от других типов кампаний по структуре: вместо групп объявлений и объявлений в них используются группы объектов. Вы связываете объекты креативов с группой объектов с помощью AssetGroupAsset и добавляете сигналы аудитории или тем поиска с помощью AssetGroupSignal.

К группе объявлений или кампании можно прикрепить один или несколько ресурсов AdGroupCriterion или CampaignCriterion. Это критерии, определяющие, как активируются объявления.

Существует множество типов критериев, например ключевые слова, возрастные диапазоны и местоположения. Критерии, заданные на уровне кампании, влияют на все остальные ресурсы в ней. Вы также можете задавать бюджеты, а также даты и время начала и окончания кампаний или отдельных объявлений с помощью AdGroupAd.start_date_time и AdGroupAd.end_date_time.

Наконец, вы можете прикрепить объекты на уровне аккаунта, кампании, группы объявлений или группы объектов. Объекты позволяют добавлять в объявления дополнительную информацию, например номера телефонов, почтовые адреса или сведения о промоакциях. Подробнее об объектах…

Ресурсы

Ресурсы представляют собой объекты в аккаунте Google Рекламы. Campaign и AdGroup – это два примера ресурсов.

Идентификаторы объектов

У каждого объекта в Google Рекламе есть собственный идентификатор. Некоторые из этих идентификаторов уникальны для всех аккаунтов Google Рекламы, а другие – только в определенных пределах.

Идентификатор объекта Уровень уникальности Глобальный или нет
Идентификатор бюджета Глобальный Да
Идентификатор кампании Глобальный Да
Идентификатор группы объявлений Глобальный Да
Идентификатор объявления Группа объявлений Нет, но пара AdGroupId и AdId уникальна в глобальном масштабе. Запрещено использовать один и тот же AdId в нескольких группах объявлений.
Идентификатор критерия группы объявлений Группа объявлений Нет, но пара AdGroupId и CriterionId уникальна в глобальном масштабе.
Идентификатор критерия кампании Кампания Нет, но пара CampaignId и CriterionId уникальна в глобальном масштабе.
Идентификатор ярлыка Клиент Нет, но пара CustomerId и LabelId уникальна в глобальном масштабе.
Идентификатор списка пользователей Все страны Да
Идентификатор объекта Все страны Да

Эти правила могут быть полезны при разработке локального хранилища для объектов Google Рекламы.

Некоторые объекты можно использовать для нескольких типов объектов. В таких случаях объект содержит поле type, описывающее его содержимое. Например, AdGroupAd может относиться к адаптивному поисковому объявлению, объявлению для рекламы отелей или объявлению для создания спроса. Это значение можно получить через поле AdGroupAd.ad.type. Оно возвращает значение в перечислении AdType. Обратите внимание, что изменяемость может зависеть от версии. Например, VideoResponsiveAdInfo в Ad можно изменять в версии 24 и более поздних.

Названия ресурсов

Каждый ресурс уникально идентифицируется строкой resource_name, которая объединяет ресурс и его родительские элементы в путь. Например, название ресурса кампании имеет следующий вид:

customers/customer_id/campaigns/campaign_id

Например, для кампании с идентификатором 987654 в аккаунте Google Рекламы с идентификатором клиента 1234567 resource_name будет выглядеть так:

customers/1234567/campaigns/987654

Сервисы

Сервисы позволяют получать и изменять объекты Google Рекламы. Существует три типа сервисов: модификация, получение объектов и статистики, а также получение метаданных.

Изменение объектов

Сервисы, относящиеся к ресурсам, изменяют экземпляры связанного типа ресурса с помощью запроса mutate. Вы также можете использовать GoogleAdsService.Mutate, чтобы выполнять атомарные изменения в нескольких типах ресурсов в рамках одного запроса (например, одновременно создавать бюджет кампании, кампанию и группу объявлений).

Примеры сервисов, связанных с ресурсами:

Каждый запрос mutate должен включать соответствующие объекты operation. Например, метод CampaignService.MutateCampaigns ожидает один или несколько экземпляров CampaignOperation. Подробная информация об операциях приведена в статье Объекты изменений.

Одновременное изменение

Одновременное изменение одного объекта Google Реклама из нескольких источников невозможно. Это может привести к ошибкам, если несколько пользователей обновляют один и тот же объект с помощью вашего приложения или если вы изменяете объекты Google Рекламы параллельно, используя несколько потоков. Это может произойти, если объект обновляется из нескольких потоков в одном приложении или из разных приложений (например, из вашего приложения и одновременно из интерфейса Google Рекламы).

API не позволяет заблокировать объект перед обновлением. Если два источника попытаются одновременно изменить объект, API выдаст ошибку DatabaseError.CONCURRENT_MODIFICATION.

Асинхронные и синхронные изменения

Методы изменения Google Ads API являются синхронными. Вызовы API возвращают ответ только после изменения объектов, поэтому вам нужно дождаться ответа на каждый запрос. Хотя этот подход относительно прост в кодировании, он может негативно повлиять на балансировку нагрузки и привести к потере ресурсов, если процессы будут вынуждены ждать завершения вызовов.

Альтернативный подход – асинхронное изменение объектов с помощью BatchJobService, который выполняет пакеты операций в нескольких сервисах, не дожидаясь их завершения. После отправки пакетного задания серверы Google Ads API выполняют операции асинхронно, освобождая процессы для выполнения других операций. Вы можете периодически проверять статус задания.

Дополнительную информацию об асинхронной обработке можно найти в руководстве по пакетной обработке.

Проверка вызовов mutate

Большинство запросов mutate можно проверить без выполнения вызова с реальными данными. Вы можете проверить запрос на наличие отсутствующих параметров и неправильных значений полей, не выполняя операцию.

Чтобы использовать эту функцию, задайте для необязательного логического поля validate_only значение true. Запрос полностью проверяется, как если бы он выполнялся, но окончательное выполнение пропускается. Если ошибок не обнаружено, возвращается ответ без измененных результатов (results пусто). Если проверка не пройдена, запрос по умолчанию завершается ошибкой RPC GoogleAdsFailure (partial_failure = false) или возвращает обычный ответ с ошибками, связанными с операцией, в partial_failure_error, когда partial_failure = true.

validate_only особенно полезен для тестирования объявлений на предмет распространенных нарушений правил. Объявления автоматически отклоняются, если они нарушают правила, например содержат определенные слова, знаки препинания, заглавные буквы или имеют недопустимую длину. Одно недопустимое объявление может привести к отклонению всей партии. Проверка нового объявления в запросе validate_only может выявить такие нарушения. Пример кода, в котором обрабатываются ошибки нарушения правил, можно найти в документации.

Получение объектов и статистики эффективности

GoogleAdsService – это единый сервис для получения объектов и статистики эффективности.

Все запросы Search и SearchStream для GoogleAdsService должны содержать запрос, в котором указаны ресурс, атрибуты ресурса и показатели эффективности, которые нужно получить, предикаты для фильтрации запроса и сегменты для дальнейшей детализации статистики эффективности. Дополнительную информацию о формате запросов можно найти в руководстве по языку запросов Google Рекламы.

Получение метаданных

GoogleAdsFieldService извлекает метаданные о ресурсах в Google Ads API, например доступные атрибуты ресурса и его тип данных. Подробную информацию о запросах к этому сервису можно найти в руководстве по метаданным ресурсов.

Этот сервис предоставляет информацию, необходимую для создания запроса к GoogleAdsService. Для удобства информация, возвращаемая GoogleAdsFieldService, также доступна в справочной документации по полям.