Большинство ресурсов изменяются (создаются, обновляются или удаляются) с помощью метода Mutate. Метод Mutate вызывается как HTTP-запрос POST к URL ресурса, который соответствует шаблону имени ресурса, без идентификатора ресурса в конце.
Идентификаторы ресурсов, которые нужно изменить, отправляются в теле запроса JSON. Это позволяет отправлять один вызов API, содержащий несколько операций с разными ресурсами.
Например, название ресурса кампании имеет следующий формат:
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
Чтобы получить URL, используемый для изменения кампаний, опустите идентификатор ресурса в конце и добавьте :mutate:
https://googleads.googleapis.com/v26/customers/CUSTOMER_ID/campaigns:mutate
Сообщение Mutate содержит объект JSON верхнего уровня с массивом operations, в котором может быть много объектов operation. Каждая операция, в свою очередь, может быть одной из следующих: create, update или remove. Это единственные возможные операции mutate.
POST /v26/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN { "operations": [ ... ] }
Большинство сервисов поддерживает тысячи операций в одном вызове API. Ограничения на размер запросов описаны в руководстве Системные ограничения.
Операции в рамках одного запроса к API по умолчанию выполняются как единый набор действий. Это означает, что либо все они будут выполнены успешно, либо, если хотя бы одна операция завершится неудачей, весь пакет будет отклонен. Некоторые сервисы поддерживают атрибут partialFailure, который позволяет изменить это поведение. Подробнее о семантике операций изменения ресурсов…
Создать
Операции создания генерируют новые объекты и должны включать полное представление ресурса, который вы хотите создать, в формате JSON.
POST /v26/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN { "operations": [ { "create": { "name": "An example campaign", "status": "PAUSED", "campaignBudget": "customers/CUSTOMER_ID/campaignBudgets/CAMPAIGN_BUDGET_ID", "advertisingChannelType": "SEARCH", "networkSettings": { "targetGoogleSearch": true, "targetSearchNetwork": true, "targetContentNetwork": true, "targetPartnerSearchNetwork": false }, "target_spend": {} } } ] }
Обновить
Операции обновления выполняют разреженные обновления существующего ресурса. Вам нужно указать только те поля, которые вы хотите изменить.
Чтобы указать поля, которые нужно обновить, задайте для атрибута updateMask список названий полей, разделенных запятыми. Это особенно удобно, если у вас уже есть полностью сформированное представление объекта в формате JSON (например, возвращенное предыдущим вызовом API), но вы хотите изменить только определенные поля.
Вместо того чтобы удалять поля из объекта JSON, вы можете просто перечислить названия полей, которые нужно изменить, в updateMask и отправить весь объект JSON.
В примере ниже показано, как изменить name и status существующей кампании с заданным resourceName.
POST /v26/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN { "operations": [ { "updateMask": "name,status", "update": { "resourceName": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID", "name": "My renamed campaign", "status": "PAUSED", } } ] }
Удалить
Операции удаления удаляют объект, устанавливая для него статус REMOVED. Обязательным является только атрибут resourceName.
POST /v26/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN { "operations": [ { "remove": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID" } ] }