大部分的資源都是使用 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"
}
]
}