Большинство ресурсов изменяются (создаются, обновляются или удаляются) с помощью метода Mutate . Метод Mutate вызывается как HTTP- POST на URL-адрес ресурса, соответствующий шаблону имени ресурса, без завершающего идентификатора ресурса. Идентификаторы ресурсов, подлежащих мутации, вместо этого передаются в теле JSON-запроса. Это позволяет отправлять один вызов API, содержащий несколько операций над различными ресурсами.
Например, название ресурса кампании имеет следующий формат:
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
Чтобы получить URL-адрес, используемый для мутационных кампаний, опустите конечный идентификатор ресурса и добавьте :mutate :
https://googleads.googleapis.com/v20/customers/CUSTOMER_ID/campaigns:mutate
Сообщение Mutate содержит JSON-объект верхнего уровня с массивом operations , который может содержать множество объектов operation . Каждая операция, в свою очередь, может быть одной из следующих: create , update или remove . Это единственно возможные операции mutate.
POST /v20/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "operations": [ ... ] }
Большинство сервисов поддерживают тысячи операций в одном вызове API. В руководстве «Системные ограничения» описаны ограничения на размер запросов.
Операции в рамках одного API-запроса по умолчанию выполняются как один набор действий, то есть либо все они выполняются успешно, либо весь пакет завершается ошибкой, если какая-либо одна операция завершается неудачей. Некоторые сервисы поддерживают атрибут partialFailure для изменения этого поведения. Подробнее о семантике операций mutate см. в разделе « Ресурсы по мутациям» .
Создавать
Операции создания создают новые сущности и должны включать полное JSON-представление ресурса, который вы собираетесь создать.
POST /v20/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_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 /v20/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "operations": [ { "updateMask": "name,status", "update": { "resourceName": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID", "name": "My renamed campaign", "status": "PAUSED", } } ] }
Удалять
Операции удаления фактически удаляют объект, присваивая ему статус REMOVED в Google Ads. Для удаления требуется только имя resourceName .
POST /v20/customers/CUSTOMER_ID/campaigns:mutate HTTP/1.1 Host: googleads.googleapis.com Content-Type: application/json Authorization: Bearer ACCESS_TOKEN developer-token: DEVELOPER_TOKEN { "operations": [ { "remove": "customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID" } ] }