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