Большинство ресурсов изменяются (создаются, обновляются или удаляются) с помощью метода Mutate . Метод Mutate вызывается в виде HTTP POST запроса к URL-адресу, специфичному для ресурса, который соответствует шаблону имени ресурса, без завершающего идентификатора ресурса. Идентификаторы ресурсов, которые необходимо изменить, вместо этого отправляются в теле JSON-запроса. Это позволяет отправить один вызов API, содержащий несколько операций над различными ресурсами.
Например, название ресурса кампании имеет следующий формат:
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
Чтобы получить URL-адрес, используемый для изменения кампаний, опустите завершающий идентификатор ресурса и добавьте :mutate :
https://googleads.googleapis.com/v23/customers/CUSTOMER_ID/campaigns:mutate
Сообщение Mutate содержит JSON-объект верхнего уровня с массивом operations , который может содержать множество объектов operation . Каждая операция, в свою очередь, может быть одной из следующих: create , update или remove . Это единственно возможные операции изменения.
POST /v23/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 для изменения этого поведения. Дополнительную информацию о семантике операций изменения см. в разделе «Изменение ресурсов» .
Создавать
Операции создания создают новые сущности и должны включать полное JSON-представление ресурса, который вы собираетесь создать.
POST /v23/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 /v23/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", } } ] }
Удалять
Операция удаления фактически удаляет объект, устанавливая для него статус в Google Ads как REMOVED . Требуется указать только имя resourceName который необходимо удалить.
POST /v23/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" } ] }