突變

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

搜尋和 SearchStream

其他方法