Mutate

注意 ：请参阅 Mutates 部分 随附的示例，以获取更完整的示例。

您可以使用 Mutate 修改（创建、更新或移除）大多数资源 方法。Mutate 方法作为 HTTP POST 来调用，指向特定于资源的 与资源名称模式匹配的网址，不带尾部资源 ID。 需要更改的资源的 ID 在 JSON 请求中发送 正文。这样，您就可以发送单个 API 调用，其中包含多个 不同资源

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

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

要推导出用于更改广告系列的网址，请省略末尾的资源 ID 和 附加 :mutate：

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

Mutate 消息包含具有 operations 数组的顶级 JSON 对象 可包含多个 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 属性 更改此行为。请参阅转变资源 详细了解 mutate 操作语义。

创建

创建操作会生成新实体，并且必须包含完整的 JSON 表示您要创建的资源。

要点 ：创建操作不指定 resourceName 或 ID。当 API 调用成功后，响应会包含为新调用生成的 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": [
    {
    "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 表示法（例如， 返回），但只想更改某些字段。 您无需删减 JSON 对象，只需列出待 并发送整个 JSON 对象。updateMask

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

以下示例将更改采用同一出价策略的现有广告系列的 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",
      }
    }
  ]
}

移除

Delete 操作可以有效地删除对象，从而将其 Google Ads 状态设置为 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"
    }
  ]
}