Структура API

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

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

Аккаунт Google Рекламы можно представить как иерархию объектов.

• Ресурсом верхнего уровня аккаунта является объект customer.

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

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

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

Кампании с максимальной эффективностью имеют структуру, отличную от других типов кампаний: вместо групп объявлений и объявлений в группах объявлений в них используются группы объектов. Вы можете связать креативы с группой объектов, используя AssetGroupAsset, и добавить сигналы аудитории или темы поиска с помощью AssetGroupSignal.

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

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

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

Ресурсы

Ресурсы представляют собой объекты в аккаунте Google Рекламы. Campaign и AdGroup – два примера ресурсов.

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

У каждого объекта в Google Рекламе есть собственный идентификатор. Некоторые из этих идентификаторов уникальны для всех аккаунтов Google Рекламы, а другие – только в рамках определенной области.

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

Некоторые объекты можно использовать для нескольких типов объектов. В таких случаях объект содержит поле type, в котором описано его содержимое. Например, AdGroupAd может относиться к объекту, такому как адаптивное поисковое объявление, объявление гостиницы или объявление для создания спроса. Это значение можно получить через поле AdGroupAd.ad.type, которое возвращает значение из перечисления AdType. Обратите внимание, что возможность изменения может зависеть от версии (например, VideoResponsiveAdInfo в Ad можно изменять в версии 24 и более поздних).

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

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

customers/customer_id/campaigns/campaign_id

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

customers/1234567/campaigns/987654

Сервисы

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

Изменение объектов

Сервисы, относящиеся к определенному ресурсу, изменяют экземпляры связанного типа ресурса с помощью запроса mutate. Вы также можете использовать GoogleAdsService.Mutate для выполнения атомарных мутаций с несколькими типами ресурсов в одном запросе (например, для одновременного создания бюджета кампании, кампании и группы объявлений).

Примеры сервисов, связанных с ресурсами:

• CustomerService для изменения клиентов.

• CampaignService для изменения кампаний.

• AdGroupService – для изменения групп объявлений.

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

Одновременное изменение

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

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

Асинхронные и синхронные операции изменения

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

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

Подробнее о пакетной обработке…

Проверка вызовов mutate

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

Чтобы использовать эту функцию, задайте для необязательного логического поля validate_only запроса значение true. Запрос полностью проверяется, как если бы он должен был быть выполнен, но окончательное выполнение пропускается. Если ошибок нет, возвращается ответ без заполненных результатов изменений (results пуст). Если проверка не пройдена, по умолчанию запрос завершается с ошибкой RPC GoogleAdsFailure (partial_failure = false) или возвращается обычный ответ с ошибками, относящимися к операции, в поле partial_failure_error, если задано значение partial_failure = true.

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

Как получать объекты и статистику эффективности

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

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

Как получить метаданные

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

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