更改

注意：如需查看更完整的示例，请参阅随附示例的Mutates部分。

注意：如果您是 Google Ads API 的新手，建议您先阅读入门指南，其中介绍了如何设置账号以及如何进行首次 API 调用。请务必按照 curl 标签页中的说明操作。

大多数资源都是使用 Mutate 方法进行修改（创建、更新或移除）的。系统会以 HTTP POST 的形式调用 Mutate 方法，并将其发送到与资源名称模式匹配的特定于资源的网址，且不包含尾随资源 ID。 要变动的资源的 ID 会改为在 JSON 请求正文中发送。这样，您就可以发送单个 API 调用，其中包含对不同资源的多个操作。

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

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

如需推导用于变动广告系列的网址，请省略尾随资源 ID 并附加 :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 表示法。

**要点**： 创建操作不会指定 resourceName 或 ID。当 API 调用成功时，响应会包含为新创建的对象生成的 resourceName。

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 调用返回），但只想更改某些字段，则此方法特别有用。 您只需在 updateMask 中列出要修改的字段名称，然后发送整个 JSON 对象，而无需修剪 JSON 对象。

**要点** ：update_mask 是 Google API 中使用的标准 字段，用于对给定资源执行部分更新。如需了解完整详情，请参阅 FieldMask参考文档。

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

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",
      }
    }
  ]
}

移除

移除操作会有效地删除对象，并将其 Google Ads 广告状态设置为 REMOVED。您只需提供要移除的 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"
    }
  ]
}