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