Mutate

您可以使用 Mutate 方法修改（创建、更新或移除）大多数资源。Mutate 方法作为 HTTP POST 调用，发送到与资源名称模式匹配的资源专用网址，但不包含资源 ID。需要更改的资源的 ID 改为在 JSON 请求正文中发送。这样，您就可以发送包含针对不同资源的多项操作的单个 API 调用。

例如，广告系列的资源名称使用以下格式：

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

如需派生用于实现广告系列转变的网址，请省略末尾的资源 ID 并附加 :mutate：

https://googleads.googleapis.com/v16/customers/CUSTOMER_ID/campaigns:mutate

Mutate 消息包含一个带有 operations 数组的顶级 JSON 对象，后者可以包含多个 operation 对象。每个运算又可以是以下项之一：create、update 或 remove。这些是唯一可能的 mutate 操作。

POST /v16/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 /v16/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 调用返回），但只想更改某些字段，这会特别有用。您可以只在 updateMask 中列出要修改的字段名称并发送整个 JSON 对象，而不是删减 JSON 对象。

以下示例将更改具有指定 resourceName 的现有广告系列的 name 和 status。

POST /v16/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 /v16/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"
    }
  ]
}

搜索和搜索信息流

其他方法