Видео: ознакомьтесь с докладом «Услуги и ресурсы» с семинара 2019 года
В этом руководстве рассматриваются основные компоненты API Google Рекламы. API Google Рекламы состоит из ресурсов и сервисов . Ресурс представляет собой сущность Google Рекламы, а сервисы извлекают и обрабатывают сущности Google Рекламы.
Иерархия объектов
Аккаунт Google Ads можно рассматривать как иерархию объектов.
Ресурсом верхнего уровня учетной записи является клиент .
Каждый клиент содержит одну или несколько активных кампаний .
Каждая кампания содержит одну или несколько групп объявлений , используемых для группировки ваших объявлений в логические коллекции.
Группа объявлений представляет собой объявление, которое вы показываете. За исключением кампаний для приложений, где на группу объявлений может быть только одно объявление, каждая группа объявлений содержит одно или несколько объявлений.
Вы можете добавить один или несколько AdGroupCriterion или CampaignCriterion к группе объявлений или кампании. Они представляют собой критерии, определяющие, как будет запускаться показ рекламы.
Существует множество типов критериев , таких как ключевые слова, возрастные диапазоны и местоположения. Критерии, заданные на уровне кампании, влияют на все остальные ресурсы в рамках кампании. Вы также можете указать бюджеты и даты для всей кампании.
Наконец, вы можете добавлять расширения на уровне аккаунта, кампании или группы объявлений. Расширения позволяют добавлять в объявления дополнительную информацию, например номер телефона, почтовый адрес или информацию об акциях.
Ресурсы
Ресурсы представляют собой сущности в вашем аккаунте Google Рекламы. Примерами ресурсов являются Campaign и AdGroup .
Идентификаторы объектов
Каждый объект в Google Рекламе идентифицируется собственным идентификатором. Некоторые из этих идентификаторов уникальны для всех аккаунтов Google Рекламы, а другие — только в определённой области.
| Идентификатор объекта | Область уникальности | Уникальность в мировом масштабе? |
|---|---|---|
| Идентификатор бюджета | Глобальный | Да |
| Идентификатор кампании | Глобальный | Да |
| Идентификатор группы объявлений | Глобальный | Да |
| Идентификатор объявления | Группа объявлений | Нет, но пара ( AdGroupId , AdId ) глобально уникальна |
| Идентификатор критерия AdGroup | Группа объявлений | Нет, но пара ( AdGroupId , CriterionId ) глобально уникальна |
| Идентификатор критерия кампании | Кампания | Нет, но пара ( 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 Рекламы. Существует три типа сервисов: изменение, поиск объектов и статистики, а также поиск метаданных.
Изменять (мутировать) объекты
Эти сервисы изменяют экземпляры связанного типа ресурса с помощью запроса mutate . Они также предоставляют запрос get , который извлекает отдельный экземпляр ресурса, что может быть полезно для изучения структуры ресурса.
Примеры услуг:
CustomerServiceдля изменения клиентов .CampaignServiceдля изменения кампаний .AdGroupServiceдля изменения групп объявлений .
Каждый запрос 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 выполняют операции асинхронно, освобождая процессы для выполнения других операций. Вы можете периодически проверять статус выполнения задания.
Дополнительную информацию об асинхронной обработке см. в руководстве по пакетной обработке .
Проверка мутации
Большинство запросов на мутацию можно проверить без фактического выполнения вызова с реальными данными. Вы можете проверить запрос на отсутствующие параметры и неверные значения полей, не выполняя операцию.
Чтобы использовать эту функцию, установите необязательное логическое поле validate_only запроса в true . После этого запрос будет полностью проверен, как если бы он был выполнен, но финальное выполнение будет пропущено. Если ошибок не обнаружено, возвращается пустой ответ. Если проверка не пройдена, сообщения об ошибках в ответе укажут на точки сбоя.
validate_only особенно полезна при проверке объявлений на наличие распространённых нарушений правил. Объявления автоматически отклоняются, если они нарушают правила, например, наличие определённых слов, знаков препинания, заглавных букв или длину. Одно некорректное объявление может привести к ошибке проверки всего пакета. Тестирование нового объявления в запросе validate_only может выявить любые подобные нарушения. Чтобы увидеть это в действии, обратитесь к примеру кода для обработки ошибок нарушения правил .
Получить объекты и статистику производительности
GoogleAdsService — это единый унифицированный сервис для получения объектов и статистики эффективности.
Для всех запросов Search и SearchStream к GoogleAdsService требуется запрос, в котором указан ресурс, атрибуты ресурса и метрики эффективности, которые необходимо получить, предикаты для фильтрации запроса и сегменты для дальнейшей детализации статистики эффективности. Подробнее о формате запроса см. в руководстве по языку запросов Google Ads .
Получить метаданные
GoogleAdsFieldService извлекает метаданные о ресурсах в API Google Ads, такие как доступные атрибуты ресурса и его тип данных.
Эта служба предоставляет информацию, необходимую для построения запроса к GoogleAdsService . Для удобства информация, возвращаемая GoogleAdsFieldService , также доступна в справочной документации по полям .