使用臨時 ID

暫時資源名稱

BatchJobService 支援臨時資源名稱，可在同一批次作業的後續作業中參照，包括透過 sequence_token 上傳的多個連續 AddBatchJobOperations 要求。這樣一來，您就能在伺服器端 ID 指派前，在單一批次工作中建立廣告活動及其相關的廣告群組、廣告和條件。在下列通則和範例中，單一要求是指所有 AddBatchJobOperations 上傳內容的整個 BatchJob。

如要在同一個變更要求或批次作業中參照新建立的資源，請在新資源的 resource_name 欄位中指定負整數 ID (例如 -1 或 -2，不包括 0)。舉例來說，在批次要求中建立廣告活動時，請將資源名稱設為 customers/CUSTOMER_ID/campaigns/-1。 在同一項請求的後續作業中建立廣告群組時，請將 customers/CUSTOMER_ID/campaigns/-1 參照為父項廣告活動。API 會自動將 -1 替換為建立時產生的實際廣告活動 ID。

使用限制

使用臨時資源名稱時，請注意下列規則：

• 順序很重要：您只能在定義臨時資源名稱後參照該名稱。在作業清單中，相依作業 (例如建立廣告群組) 必須出現在建立父項資源 (例如建立廣告活動) 的作業之後。
• 單一要求或批次工作範圍：臨時資源名稱不會在不同工作或變動要求之間保留。如要參照先前作業或變更要求中建立的資源，請使用系統產生的實際資源名稱。
• 全域專屬性：在單一工作或變更要求中，每個暫時資源名稱在所有資源類型中都必須使用專屬的負整數。舉例來說，您無法在同一個要求中，同時為廣告活動和廣告群組指派 -1。在相同要求或批次作業中重複使用臨時 ID 會傳回 NewResourceCreationError.DUPLICATE_TEMP_IDS 錯誤。

酬載範例

假設您想在單一 API 要求或批次工作新增廣告活動、廣告群組和廣告，您可以在 GoogleAdsService.Mutate 或 BatchJobService.AddBatchJobOperations 要求酬載中，建構 mutateOperations 陣列，如下列 REST JSON 範例所示 (為求精簡，省略其他必要資源欄位)：

{
  "mutateOperations": [
    {
      "campaignOperation": {
        "create": {
          "resourceName": "customers/CUSTOMER_ID/campaigns/-1"
        }
      }
    },
    {
      "adGroupOperation": {
        "create": {
          "resourceName": "customers/CUSTOMER_ID/adGroups/-2",
          "campaign": "customers/CUSTOMER_ID/campaigns/-1"
        }
      }
    },
    {
      "adGroupAdOperation": {
        "create": {
          "adGroup": "customers/CUSTOMER_ID/adGroups/-2"
        }
      }
    }
  ]
}

這個範例示範了下列重要詳細資料：

• 廣告群組使用新的臨時 ID (-2)，因為 -1 已指派給廣告活動。
• 廣告群組會參照 customers/CUSTOMER_ID/campaigns/-1，將自己連結至前一個作業中建立的廣告活動。
• 由於要求中的後續作業未參照新廣告，因此 adGroupAdOperation 會參照 customers/CUSTOMER_ID/adGroups/-2 並省略 resourceName。

批次工作中的錯誤處理

由於批次工作中的標準作業會啟用部分失敗 (完整子批次除外)，因此如果具有臨時 ID 的父項資源驗證失敗，任何參照該臨時 ID 的子項作業都會因 NewResourceCreationError.TEMP_ID_RESOURCE_HAD_ERRORS 而失敗。在同一個批次工作作業中，如果多個 create 作業重複使用相同的負 ID，系統會傳回 NewResourceCreationError.DUPLICATE_TEMP_IDS。只有在建立資源 (create) 或參照新建立的父項資源時，臨時 ID 才有效；舉例來說，在呼叫 AddBatchJobOperations 時，於 AdGroupCriterionOperation.remove 中傳遞負數臨時 ID 會傳回 RequestError.RESOURCE_NAME_MALFORMED。