Как изменить объекты

Цель. Научиться изменять объекты с помощью Google Ads API.

Как описано в руководстве по структуре API, у каждого ресурса верхнего уровня в Google Ads API есть соответствующий сервис, который поддерживает изменение экземпляров ресурса. Вы также можете использовать GoogleAdsService.Mutate, чтобы атомарно изменять несколько типов ресурсов в одном запросе.

В этом руководстве на примере CampaignService показано, как изменять объекты Campaign, но те же принципы применимы и к другим сервисам, связанным с определенными типами ресурсов.

Примечание. Ресурс верхнего уровня – это ресурс, название которого не содержит точку (.). Например, Campaign – это ресурс верхнего уровня, а Campaign.NetworkSettings – нет.

Запросы mutate

У каждого сервиса, предназначенного для определенного типа ресурсов, есть метод mutate, который принимает запрос mutate. Запрос состоит из следующих элементов:

• customer_id (или customerId в URL REST)
• Подборка operations
• Дополнительные настройки выполнения, например partial_failure, validate_only и response_content_type (определяет, возвращается ли изменяемый ресурс или только его название после изменения).

Например, метод MutateCampaigns в CampaignService принимает объект MutateCampaignsRequest, который состоит из следующих элементов:

• customer_id
• Коллекция из CampaignOperation объектов (operations)
• Необязательные настройки выполнения (partial_failure, validate_only и response_content_type, указывающие предпочтительный тип ответа).

Примечание. Доступные сервисы и методы могут различаться в зависимости от версии API. Например, чтобы настроить цели по жизненному циклу клиентов и кампаний, используйте методы Mutate* в GoalService и CampaignGoalConfigService в версии 25 и более поздних или методы Configure* в CustomerLifecycleGoalService и CampaignLifecycleGoalService в версии 24 и более ранних.

Операции

Объект операции, например CampaignOperation, позволяет указать действие, которое вы хотите выполнить с одним ресурсом, задав его поле operation. Это поле oneof, состоящее из следующих атрибутов:

create

Создает новый экземпляр ресурса.

update

Обновляет ресурс в соответствии с атрибутами ресурса update. Если вы задали это поле, вам также необходимо указать update_mask операции, чтобы Google Ads API знал, какие атрибуты нужно изменить во время операции обновления. В каждой клиентской библиотеке есть утилита или вспомогательный метод для создания маски поля, которые генерируют update_mask.

remove

Удаляет ресурс, указанный в строке с названием ресурса (например, customers/1234567890/campaigns/987654321).

Поскольку поле operation является полем oneof, вы не можете использовать одну операцию для изменения нескольких объектов. Например, если вы хотите создать одну кампанию и удалить другую, добавьте в запрос два экземпляра CampaignOperation: один с параметром create, а другой – с параметром remove.

Массовые операции

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

Например, если вы хотите создать десять кампаний, вам нужно отправить один объект MutateCampaignsRequest, содержащий десять объектов CampaignOperation. Чтобы сгруппировать операции с разными типами ресурсов в один запрос, используйте GoogleAdsService.Mutate или изменяющие ресурсы.

Изменение ответов

Содержимое ответа зависит от того, что было отправлено в поле response_content_type запроса mutate. Например, если указано значение MUTABLE_RESOURCE, то ответ будет содержать как resource_name ресурса, так и изменяемые поля кампании в campaign. По умолчанию (RESOURCE_NAME_ONLY) в каждом элементе MutateCampaignResult заполняется только поле resource_name.

Ошибки изменения

По умолчанию (partial_failure = false) операции в запросе mutate применяются к аккаунту Google Рекламы, только если каждая операция в запросе выполнена успешно. Если хотя бы одна операция завершится неудачно, весь запрос будет откачен. Для запросов mutate, поддерживающих частичный сбой (с полем partial_failure в сообщении запроса), установка значения partial_failure = true приводит к тому, что действительные операции выполняются, а для операций, которые не удалось выполнить, возвращаются ошибки, относящиеся к определенной операции, в поле partial_failure_error ответа. Подробнее о том, как устранять ошибки, рассказывается в руководстве по частичным сбоям и руководстве по распространенным ошибкам.

Отслеживание изменений

Чтобы отслеживать изменения, внесенные в объекты в аккаунте Google Рекламы, или получать текущее состояние объектов, можно использовать ресурсы change_status и change_event.

• change_status предоставляет сводку ресурсов, которые изменились за определенный период времени.
• change_event – подробная история изменений, в том числе старые и новые значения измененных полей.

Чтобы запросить эти ресурсы, используйте метод GoogleAdsService.SearchStream или GoogleAdsService.Search. Подробнее о потоковой передаче отчетов с помощью GoogleAdsService…