資源服務突變

在 Google Ads API 中，如要建立、更新或移除單一資源類型的實體，最直接的方法是使用資源的專屬服務。

Mutate 端點

每個可變動資源都有對應的服務和作業類型。如要使用專屬服務來變更資源，請在作業中填入下列其中一個欄位，然後傳送至服務的變動端點：

• 建立 (create)：要建立的新資源物件。
• 更新 (update)：修改後的資源物件，並附上指定變更欄位的 update_mask。
• 移除 (remove)：要移除的目標資源 resource_name 字串。

舉例來說，如要建立新的 Campaign，請完成下列步驟：

1. 使用所選屬性建構 Campaign 物件。
2. 將其指派給 CampaignOperation 的 create 欄位。
3. 在 MutateCampaignsRequest 中將作業傳送至 CampaignService.MutateCampaigns。

這個模式適用於 Google Ads API 中所有資源專屬服務：

• AdGroup：將 AdGroupOperation 傳遞至 AdGroupService.MutateAdGroups。
• CampaignCriterion：將 CampaignCriterionOperation 傳遞至 CampaignCriterionService.MutateCampaignCriteria。

下列 REST JSON 酬載說明對 CampaignService.MutateCampaigns 的要求：

{
  "customerId": "CUSTOMER_ID",
  "operations": [
    {
      "create": {
        "name": "Interplanetary Cruise #1",
        "advertisingChannelType": "SEARCH",
        "status": "PAUSED",
        "manualCpc": {},
        "campaignBudget": "customers/CUSTOMER_ID/campaignBudgets/BUDGET_ID",
        "containsEuPoliticalAdvertising": "DOES_NOT_CONTAIN_EU_POLITICAL_ADVERTISING"
      }
    }
  ],
  "partialFailure": false,
  "validateOnly": false
}

多項作業和限制

大多數資源專屬的變更要求都接受重複的 operations 欄位，因此單一要求可以包含該資源類型的多項作業 (每項要求最多 10,000 項作業，AdGroupCriterionService.MutateAdGroupCriteria 則為 20,000 項；CustomerService.MutateCustomer 接受單一 operation 欄位)。根據預設，除非服務支援 partial_failure，且您將其設為 true，否則要求中的所有作業都會以不可分割的方式執行。

不過，個別資源服務有兩項重要限制：

• 單一資源類型：對資源服務提出的要求，只能變更由該特定服務管理的資源。
• 不支援跨資源臨時 ID：由於資源專屬變動呼叫僅接受單一資源類型，因此您無法在同一要求中，將臨時負 ID 指派給父項資源 (例如 customers/CUSTOMER_ID/campaigns/-1)，並從不同類型的子項資源 (例如 AdGroup) 參照該 ID。( 階層樹狀結構 (例如 AdGroupCriterion 商家資訊群組和 AssetGroupListingGroupFilter 節點) 支援相同資源類型中的自我參照臨時 ID)。

如需在單一要求中變更多個資源類型，或參照不同資源類型的暫時資源名稱，請改用 GoogleAdsService.Mutate。

版本差異

變更資源時，請留意支援的 Google Ads API 版本之間的差異：

• 生命週期目標服務：客戶留存率目標會透過 GoalService.MutateGoals (retention_goal_settings) 和 CampaignGoalConfigService.MutateCampaignGoalConfigs (campaign_retention_settings)，使用標準重複 operations 欄位，在所有支援的版本中變更。在 v25 以上版本中，獲取新客 (new_customer_acquisition_goal_settings/campaign_new_customer_acquisition_settings) 和忠誠度留存 (loyalty_retention_goal_settings/campaign_loyalty_retention_settings) 也會透過 GoalService.MutateGoals 和 CampaignGoalConfigService.MutateCampaignGoalConfigs 進行異動。這會取代 CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals 和 CampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals，這兩個欄位在 v23 和 v24 中用於獲取新客，並接受單一 operation 欄位。