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