В этом руководстве описаны основные компоненты Google Ads API. Google Ads 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, также доступна в справочной документации по полям.