Большинство ресурсов изменяются (создаются, обновляются или удаляются) с помощью метода 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. Это единственные возможные операции изменения.
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 в Google Рекламе. Обязательным является только удаляемый элемент 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" } ] }