大部分的資源都是使用 Mutate
方法修改 (建立、更新或移除)。在沒有結尾資源 ID 的情況下,系統會將 Mutate
方法叫用為與資源名稱模式相符的資源專屬網址 HTTP POST
。所變更資源的 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
。這些是唯一可能的 CHANGE 作業。
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
屬性來變更這項行為。如要進一步瞭解 change 作業語意,請參閱修改資源。
建立
建立作業會產生新實體,且必須包含您要建立的資源的完整 JSON 表示法。
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 表示法完整格式 (例如先前的 API 呼叫所傳回),但只想變更特定欄位,這個方法就特別實用。您只需列出要在 updateMask
中修改的欄位名稱,然後傳送整個 JSON 物件即可,而不必修剪 JSON 物件。
以下範例會變更具有指定 resourceName
的現有廣告活動 name
和 status
。
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", } } ] }
移除
移除作業可有效刪除物件,並將物件的 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" } ] }