Структура API

Видео: ознакомьтесь с докладом «Услуги и ресурсы» с семинара 2019 года

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

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

Аккаунт Google Ads можно рассматривать как иерархию объектов.

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

  • Ресурсом верхнего уровня учетной записи является клиент .

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

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

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

Вы можете прикрепить один или несколько AdGroupCriterion или CampaignCriterion к группе объявлений или кампании. Они представляют собой критерии, которые определяют, как будут запускаться объявления.

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

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

Ресурсы

Ресурсы представляют сущности в вашем аккаунте Google Ads. Campaign и AdGroup — два примера ресурсов.

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

Каждый объект в Google Ads идентифицируется собственным ID. Некоторые из этих ID являются глобально уникальными для всех аккаунтов Google Ads, в то время как другие уникальны только в ограниченной области.

Идентификатор объекта Масштаб уникальности Глобально уникальный?
Бюджетный идентификатор Глобальный Да
Идентификатор кампании Глобальный Да
Идентификатор AdGroup Глобальный Да
Идентификатор объявления Группа объявлений Нет, но пара ( AdGroupId , AdId ) глобально уникальна
AdGroupCriterion ID Группа объявлений Нет, но пара ( AdGroupId , CriterionId ) глобально уникальна
ID критерия кампании Кампания Нет, но пара ( CampaignId , CriterionId ) является глобально уникальной
Расширения рекламы Кампания Нет, но пара ( CampaignId , AdExtensionId ) является глобально уникальной
Идентификатор этикетки Глобальный Да
Идентификатор списка пользователей Глобальный Да
Идентификатор актива Глобальный Да

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

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

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

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

customers/customer_id/campaigns/campaign_id

Таким образом, для кампании с идентификатором 987654 в аккаунте Google Ads с идентификатором клиента 1234567 resource_name будет следующим:

customers/1234567/campaigns/987654

Услуги

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

Изменить (мутировать) объекты

Эти сервисы изменяют экземпляры связанного типа ресурса с помощью запроса mutate . Они также предоставляют запрос get , который извлекает один экземпляр ресурса, что может быть полезно для изучения структуры ресурса.

Примеры услуг:

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

Конкурентные мутации

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

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

Асинхронные и синхронные мутации

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

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

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

Проверка мутации

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

Чтобы использовать эту функцию, установите необязательное поле validate_only boolean запроса на true . Затем запрос будет полностью проверен, как если бы он собирался быть выполненным, но окончательное выполнение будет пропущено. Если ошибок не обнаружено, возвращается пустой ответ. Если проверка не пройдена, сообщения об ошибках в ответе укажут точки сбоя.

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

Получить объекты и статистику производительности

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

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

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

GoogleAdsFieldService извлекает метаданные о ресурсах в API Google Ads, такие как доступные атрибуты для ресурса и его тип данных.

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

Назад
Обзор
Далее
Управление версиями