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

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

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

Запросы на изменение

У каждого сервиса, предназначенного для определенного типа ресурса, есть метод 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…