Видео: ознакомьтесь с докладом об услугах и ресурсах на семинаре 2019 г.
В этом руководстве представлены основные компоненты, составляющие Google Ads API. Google Ads API состоит из ресурсов и сервисов . Ресурс представляет объект Google Ads, а сервисы извлекают объекты Google Ads и манипулируют ими.
Иерархия объектов
Аккаунт Google Ads можно рассматривать как иерархию объектов.
Ресурсом верхнего уровня учетной записи является клиент .
Каждая учетная запись содержит одну или несколько активных кампаний .
Каждая
Campaignсодержит одну или несколько групп объявлений , которые используются для объединения ваших объявлений в логические коллекции.Каждая группа
AdGroupсодержит одно или несколько объявлений группы объявлений .AdGroupAdпредставляет объявление, которое вы запускаете.
Вы можете прикрепить один или несколько AdGroupCriterion или CampaignCriterion к группе объявлений или кампании. Они представляют собой критерии, которые определяют, как запускается реклама.
Существует много типов критериев , таких как ключевые слова, возрастные диапазоны и местоположения. Критерии, определенные на уровне кампании, влияют на все остальные ресурсы в рамках кампании. Вы также можете указать бюджеты и даты для всей кампании.
Наконец, вы можете прикрепить расширения на уровне аккаунта, кампании или группы объявлений. Расширения позволяют добавлять в объявления дополнительную информацию, например номер телефона, почтовый адрес или рекламные акции.
Ресурсы
Ресурсы представляют объекты в вашем аккаунте Google Реклама. Campaign и AdGroup — два примера ресурсов.
Идентификаторы объектов
Каждый объект в Google Ads идентифицируется своим идентификатором. Некоторые из этих идентификаторов уникальны во всем мире для всех аккаунтов Google Реклама, а другие уникальны только в ограниченной области.
| Идентификатор объекта | Сфера уникальности | Глобально уникальный? |
|---|---|---|
| Идентификатор бюджета | Глобальный | Да |
| Идентификатор кампании | Глобальный | Да |
| Идентификатор группы объявлений | Глобальный | Да |
| Идентификатор объявления | Группа объявлений | Нет, но пара ( AdGroupId , AdId ) глобально уникальна |
| Идентификатор критерия группы объявлений | Группа объявлений | Нет, но пара ( AdGroupId , CriterionId ) глобально уникальна |
| Идентификатор критерия кампании | Кампания | Нет, но пара ( CampaignId , CriterionId ) глобально уникальна |
| Расширения объявлений | Кампания | Нет, но пара ( CampaignId , AdExtensionId ) глобально уникальна |
| Идентификатор фида | Глобальный | Да |
| Идентификатор элемента фида | Глобальный | Да |
| Идентификатор атрибута фида | Подача | Нет |
| Идентификатор сопоставления фида | Глобальный | Да |
| Идентификатор ярлыка | Глобальный | Да |
| Идентификатор списка пользователей | Глобальный | Да |
Эти правила идентификации могут быть полезны при разработке локального хранилища для ваших объектов Google Рекламы.
Некоторые объекты могут использоваться для нескольких типов сущностей. В таких случаях объект содержит поле type , описывающее его содержимое. Например, AdGroupAd может относиться к текстовому объявлению, объявлению отеля, локальному объявлению и т. д. Доступ к этому значению можно получить через поле AdGroupAd.ad.type , и оно возвращает значение в перечислении AdType .
Имена ресурсов
Каждый ресурс однозначно идентифицируется строкой resource_name , которая объединяет ресурс и его родителей в путь. Например, имена ресурсов кампании имеют вид:
customers/customer_id/campaigns/campaign_id
Таким образом, для кампании с идентификатором 987654 в аккаунте Google Реклама с идентификатором клиента 1234567 resource_name будет таким:
customers/1234567/campaigns/987654
Услуги
Сервисы позволяют извлекать и изменять объекты Google Рекламы. Существует три типа сервисов: модификация, поиск объектов и статистики и сервисы поиска метаданных.
Модифицировать (мутировать) объекты
Эти службы изменяют экземпляры связанного типа ресурсов с помощью mutate на изменение. Они также предоставляют запрос на get , который извлекает один экземпляр ресурса, что может быть полезно для изучения структуры ресурса.
Примеры услуг:
CustomerServiceдля изменения клиентов .CampaignServiceдля модификации кампаний .AdGroupServiceдля изменения групп объявлений .
Каждый mutate должен включать соответствующие объекты operation . Например, метод CampaignService.MutateCampaigns ожидает один или несколько экземпляров CampaignOperation . Подробное обсуждение операций см. в разделе Изменение и проверка объектов .
Параллельные мутации
Объект Google Реклама не может быть изменен одновременно более чем одним источником. Это может привести к возникновению ошибок, если несколько пользователей обновляют один и тот же объект с помощью вашего приложения или если вы изменяете объекты Google Реклама параллельно, используя несколько потоков. Это включает в себя обновление объекта из нескольких потоков в одном и том же приложении или из разных приложений (например, вашего приложения и одновременного сеанса пользовательского интерфейса Google Реклама).
API не позволяет заблокировать объект перед обновлением; если два источника пытаются одновременно изменить объект, API вызывает ошибку DatabaseError.CONCURRENT_MODIFICATION_ERROR .
Асинхронные и синхронные мутации
Методы изменения Google Ads API являются синхронными. Вызовы API возвращают ответ только после изменения объектов, что требует от вас ожидания ответа на каждый запрос. Хотя этот подход относительно прост для написания кода, он может отрицательно сказаться на балансировке нагрузки и растрате ресурсов, если процессы будут вынуждены ждать завершения вызовов.
Альтернативный подход заключается в асинхронном изменении объектов с помощью BatchJobService , который выполняет пакетные операции над несколькими службами, не дожидаясь их завершения. После отправки пакетного задания серверы Google Ads API выполняют операции асинхронно, освобождая процессы для выполнения других операций. Вы можете периодически проверять статус задания на завершение.
Дополнительные сведения об асинхронной обработке см. в руководстве по пакетной обработке.
Проверка мутации
Большинство запросов на изменение могут быть проверены без фактического выполнения вызова с реальными данными. Вы можете протестировать запрос на отсутствующие параметры и неверные значения полей без фактического выполнения операции.
Чтобы использовать эту функцию, установите для необязательного логического поля запроса validate_only значение true . Затем запрос будет полностью проверен, как если бы он собирался выполняться, но окончательное выполнение пропускается. Если ошибок не обнаружено, возвращается пустой ответ. Если проверка не пройдена, сообщения об ошибках в ответе будут указывать на точки сбоя.
validate_only особенно полезен при проверке объявлений на наличие распространенных нарушений правил. Объявления автоматически отклоняются, если они нарушают правила, такие как использование определенных слов, знаков препинания, заглавных букв или длины. Одна плохая реклама может привести к провалу всей партии. Проверка нового объявления в рамках запроса validate_only может выявить такие нарушения. См. пример кода для обработки ошибок нарушения политики, чтобы увидеть это в действии.
Получить объекты и статистику производительности
GoogleAdsService — это единый унифицированный сервис для получения объектов и статистики эффективности.
Для всех запросов Search и SearchStream для GoogleAdsService требуется запрос, указывающий запрашиваемый ресурс, извлекаемые атрибуты ресурса и показатели производительности, предикаты, используемые для фильтрации запроса, и сегменты, используемые для дальнейшего анализа статистики производительности. Дополнительную информацию о формате запроса см. в руководстве по языку запросов Google Реклама .
Получить метаданные
GoogleAdsFieldService извлекает метаданные о ресурсах в Google Ads API, например доступные атрибуты для ресурса и его тип данных.
Эта служба предоставляет информацию, необходимую для создания запроса к GoogleAdsService . Для удобства информация, возвращаемая GoogleAdsFieldService , также доступна в справочной документации по полям .