大部分的資源都是使用 Mutate
方法修改 (建立、更新或移除)。系統會在 HTTP POST
中叫用 Mutate
方法,指向符合資源名稱模式的資源專屬網址,但不加上結尾資源 ID。系統會將要修改的資源 ID 改為透過 JSON 要求主體傳送。如此一來,您就能傳送單一 API 呼叫,當中包含多項不同資源上的多項作業。
舉例來說,廣告活動的資源名稱採用以下格式:
customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID
如要找出用於變更廣告活動的網址,請省略結尾資源 ID 並附加 :mutate
:
https://googleads.googleapis.com/v16/customers/CUSTOMER_ID/campaigns:mutate
Mutate
訊息包含頂層 JSON 物件,其中的 operations
陣列可包含許多 operation
物件。各項作業也可以是下列其中一個值:create
、update
或 remove
。這些是唯一可能的
修改作業。
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
屬性來變更這項行為。請參閱「合併資源」一文,進一步瞭解 mut 作業語意。
建立
「建立作業」會產生新實體,且必須包含要建立資源的完整 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" } ] }