您可以使用 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" } ] }