注意:您正在查看 API 的 REST 介面說明文件。我們的官方用戶端程式庫支援 gRPC。詳情請參閱 REST 簡介

突變

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

大多數資源可使用 Mutate 方法修改 (建立、更新或移除)。Mutate 方法會在特定資源網址時以 HTTP POST 叫用,並符合資源名稱模式,但不含資源 ID。要修改的資源 ID 會改為在 JSON 要求內容中傳送。這可讓您傳送包含不同資源的多項作業的單一 API 呼叫。

例如,廣告活動的資源名稱採用以下格式:

customers/CUSTOMER_ID/campaigns/CAMPAIGN_ID

如要取得衍生廣告活動的網址,請省略結尾資源 ID,並附加 :mutate

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

Mutate 訊息包含頂層 JSON 物件,其中包含含有多個 operation 物件的 operations 陣列。每項作業都可以是 createupdateremove 的其中之一。這些是唯一可行的變更。

POST /v12/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 屬性來變更這項行為。請參閱 Muting Resources 一文,進一步瞭解 Δ 運算語意。

建立

「建立」作業會產生新實體,且必須包含您打算建立的資源的完整 JSON 表示法。

POST /v12/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 物件即可。

下方範例更改了具有指定 resourceName 之現有廣告活動的 namestatus

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