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

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

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

Запросы 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, указывающие на предпочтительный тип ответа).

Операции

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

create

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

update

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

remove

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

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

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

Хотя одна операция может только создать, обновить или удалить один ресурс, один запрос mutate может содержать несколько операций. Объединяйте операции в один запрос 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…