В этом руководстве описаны основные компоненты Google Ads API. Google Реклама API состоит из ресурсов и сервисов. Ресурс представляет собой объект Google Рекламы, а сервисы извлекают объекты Google Рекламы и управляют ими.
Иерархия объектов
Аккаунт Google Рекламы можно представить как иерархию объектов.
Ресурс верхнего уровня в аккаунте – это клиент.
У каждого клиента есть одна или несколько активных кампаний.
Каждая кампания содержит одну или несколько групп объявлений, которые используются для группировки объявлений в логические коллекции.
Объявление из группы объявлений – это объявление, которое вы показываете в группе объявлений. За исключением кампаний для приложений, в которых в каждой группе объявлений может быть только одно объявление, ориентированное на группу объявлений, каждая группа объявлений содержит одно или несколько таких объявлений.
Кампании с максимальной эффективностью имеют структуру, отличную от других типов кампаний: вместо групп объявлений и объявлений в группах объявлений в них используются группы объектов. Вы можете связать объекты креатива с группой объектов, используя AssetGroupAsset, и добавить сигналы аудитории или темы поиска с помощью AssetGroupSignal.
Вы можете прикрепить один или несколько объектов AdGroupCriterion или CampaignCriterion к группе объявлений или кампании. Это критерии, определяющие, как активируются объявления.
Существует множество типов критериев, например ключевые слова, возрастные диапазоны и местоположения. Критерии, заданные на уровне кампании, влияют на все остальные ресурсы в кампании. Вы также можете указать бюджеты, а также даты и время начала и окончания кампаний или отдельных объявлений с помощью AdGroupAd.start_date_time и AdGroupAd.end_date_time.
Наконец, вы можете прикреплять объекты на уровне аккаунта, кампании, группы объявлений или группы объектов. Объекты позволяют добавлять в объявления дополнительную информацию, например номера телефонов, почтовые адреса или сведения о промоакциях. Подробнее об объектах…
Ресурсы
Ресурсы представляют собой объекты в аккаунте Google Рекламы.
Campaign и AdGroup – это два примера ресурсов.
Идентификаторы объектов
У каждого объекта в Google Рекламе есть собственный идентификатор. Некоторые из этих идентификаторов являются глобально уникальными для всех аккаунтов Google Рекламы, а другие уникальны только в ограниченной области.
| Идентификатор объекта | Уровень уникальности | Глобальный или нет |
|---|---|---|
| Идентификатор бюджета | Глобальный | Да |
| Идентификатор кампании | Глобальный | Да |
| Идентификатор группы объявлений | Глобальный | Да |
| Идентификатор объявления | Группа объявлений | Нет, но пара (AdGroupId, AdId) уникальна в глобальном масштабе. Запрещено использовать один и тот же AdId в нескольких группах объявлений. |
| Идентификатор критерия группы объявлений | Группа объявлений | Нет, но пара (AdGroupId, CriterionId) уникальна в глобальном масштабе. |
| Идентификатор критерия кампании | Кампания | Нет, но пара (CampaignId, CriterionId) уникальна в глобальном масштабе. |
| Идентификатор ярлыка | Клиент | Нет, но пара (CustomerId, LabelId) уникальна в глобальном масштабе. |
| Идентификатор списка пользователей | Все страны | Да |
| Идентификатор объекта | Все страны | Да |
Эти правила могут быть полезны при разработке локального хранилища для объектов 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.
Асинхронные и синхронные операции изменения
Методы изменения Google Ads API являются синхронными. Вызовы API возвращают ответ только после изменения объектов, поэтому вам нужно дождаться ответа на каждый запрос. Хотя этот подход относительно прост в кодировании, он может негативно повлиять на балансировку нагрузки и привести к потере ресурсов, если процессы будут вынуждены ждать завершения вызовов.
Другой подход – асинхронное изменение объектов с помощью BatchJobService, который выполняет пакеты операций в нескольких сервисах, не дожидаясь их завершения. После отправки пакетного задания серверы Google Ads API выполняют операции асинхронно, освобождая процессы для выполнения других операций. Вы можете периодически проверять статус задания.
Подробнее о пакетной обработке см. в руководстве по асинхронной обработке.
Проверка вызовов mutate
Большинство запросов mutate можно проверить без фактического выполнения вызова с реальными данными. Вы можете проверить запрос на наличие отсутствующих параметров и неправильных значений полей, не выполняя операцию.
Чтобы использовать эту функцию, задайте для необязательного логического поля validate_only запроса значение true. Запрос полностью проверяется, как если бы он выполнялся, но окончательное выполнение пропускается. Если ошибок не обнаружено, возвращается ответ без измененных результатов (results пусто). Если проверка не пройдена, запрос по умолчанию завершается ошибкой RPC GoogleAdsFailure (partial_failure = false) или возвращается обычный ответ с ошибками, связанными с операцией, в partial_failure_error, когда partial_failure = true.
validate_only особенно полезен для тестирования объявлений на предмет распространенных нарушений правил. Объявления автоматически отклоняются, если они нарушают правила, например содержат определенные слова, знаки препинания, заглавные буквы или имеют недопустимую длину. Одно недопустимое объявление может привести к отклонению всей партии. Протестировав новое объявление в validate_only
запросе, вы сможете выявить такие нарушения. Пример кода, в котором обрабатываются ошибки, связанные с нарушением правил, приведен в этом разделе.
Как получать объекты и статистику эффективности
GoogleAdsService – это единый сервис для получения объектов и статистики эффективности.
Все запросы Search и SearchStream для GoogleAdsService должны содержать запрос, в котором указаны ресурс, атрибуты ресурса и показатели эффективности, которые нужно получить, предикаты для фильтрации запроса и сегменты для дальнейшей детализации статистики эффективности. Подробную информацию о формате запросов можно найти в руководстве по языку запросов Google Рекламы.
Получение метаданных
GoogleAdsFieldService позволяет получать метаданные о ресурсах в Google Ads API, например доступные атрибуты ресурса и его тип данных. Подробные сведения о запросах к этому сервису можно найти в руководстве по метаданным ресурсов.
Этот сервис предоставляет информацию, необходимую для создания запроса к GoogleAdsService. Для удобства информация, возвращаемая GoogleAdsFieldService, также доступна в справочной документации по полям.