資源服務突變

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

變動端點

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

• 建立 (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。(階層式樹狀結構支援同一 資源類型中的自參照暫時 ID，例如 AdGroupCriterion產品目錄群組和AssetGroupListingGroupFilter節點。)

如要在單一要求中變動多個資源類型，或在不同資源類型之間參照臨時資源名稱，請改用 GoogleAdsService.Mutate。

版本專屬差異

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

• 生命週期目標服務：透過 GoalService.MutateGoals (retention_goal_settings) 和 CampaignGoalConfigService.MutateCampaignGoalConfigs (campaign_retention_settings)，使用標準重複的 operations 欄位，在所有支援版本中變更顧客留存率目標。在第 25 版和後續版本中，獲取新客 (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，這些欄位用於第 23 版和第 24 版的獲取新客目標，且接受單一 operation 欄位。