資源服務突變

使用資源的專屬服務，是在 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 項作業)。根據預設，要求中的所有作業都會以原子方式執行，除非您將 partial_failure 設為 true。

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

• 單一資源類型：對資源服務的要求只能變更該特定服務管理的資源。
• 沒有暫時性資源 ID 或交叉參照：資源專屬的變動呼叫作業會獨立處理。您無法指派暫時性負數 ID (例如 customers/CUSTOMER_ID/campaigns/-1)，也無法在同一項要求中，從其他作業參照新建立的實體。

如需在單一要求中變動多個資源類型，或在相依作業中參照臨時資源名稱，請改用 GoogleAdsService.Mutate。

版本專屬差異

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

• 生命週期目標服務：在第 25 版和後續版本中，所有生命週期目標 (包括獲取新客 (new_customer_acquisition_goal_settings)、顧客留存率 (retention_goal_settings) 和顧客忠誠度 (loyalty_retention_goal_settings)) 都會透過 GoalService.MutateGoals 和 CampaignGoalConfigService.MutateCampaignGoalConfigs，使用標準重複的 operations 欄位進行變動。這會取代 CustomerLifecycleGoalService.ConfigureCustomerLifecycleGoals 和 CampaignLifecycleGoalService.ConfigureCampaignLifecycleGoals (用於第 24 版和更早版本的獲取新客功能，並接受單一 operation 欄位)。
• 廣告活動日期和時間欄位：建立或更新 Campaign 時，v23 以上版本會使用 start_date_time 和 end_date_time (yyyy-MM-dd HH:mm:ss)，取代 v22 中使用的僅限日期的 start_date 和 end_date 欄位。
• 合成內容驗證可變動性：雖然 22 以上版本的結構定義中會顯示 Asset.synthetic_content_info 和 Ad.synthetic_content_info，但 synthetic_content_info.advertiser_attestation.status 和 synthetic_content_info.advertiser_attestation.source 欄位只能在 23 以上版本中變動 (system_attestation 一律為 OUTPUT_ONLY)。嘗試在 22 版本中變動 advertiser_attestation 子欄位時，會傳回不可變動欄位錯誤 ("The field attempted to be mutated is immutable" 或 "Field cannot be set")。