突變

注意： 如需更完整的範例，請參閱隨附範例的「Mutates」一節。

大部分的資源都是使用 Mutate 方法進行修改 (建立、更新或移除)。系統會以 HTTP POST 的形式叫用 Mutate 方法，將符合資源名稱模式的特定資源網址傳送至該資源，但不含結尾的資源 ID。相反地，系統會在 JSON 要求主體中傳送要變異的資源 ID。這可讓您傳送單一 API 呼叫，其中包含對不同資源執行的多項作業。

舉例來說，廣告活動的資源名稱採用下列格式：

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

如要擷取用於變更廣告活動的網址，請省略結尾的資源 ID，並附加 :mutate：

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

Mutate 訊息包含頂層 JSON 物件，其中的 operations 陣列可包含許多 operation 物件。每個運算可分別是 create、update 或 remove。這些是唯一可行的變異運算。

POST /v19/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 表示法。

重點提示： 建立作業不會指定 resourceName 或 ID。API 呼叫成功時，回應會包含為新建立的物件產生的 resourceName。

POST /v19/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 呼叫傳回的結果)，但只想變更特定欄位，這項功能就特別實用。您可以不用修剪 JSON 物件，只要在 updateMask 中列出要修改的欄位名稱，然後傳送整個 JSON 物件即可。

重點提示： update_mask 是 Google API 中使用的標準欄位，可用於對特定資源執行部分更新。詳情請參閱 FieldMask 參考說明文件。

下方範例會變更具有指定 resourceName 的現有廣告活動的 name 和 status。

POST /v19/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 /v19/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"
    }
  ]
}