使用暫時 ID

BatchJobService 的一項強大功能是支援使用臨時 ID。

方法是指定新資源的 resource_name 使用負 ID。舉例來說,如果您建立一個廣告活動,並將其資源名稱指定為 customers/<YOUR_CUSTOMER_ID>/campaigns/-1,則在後續作業中建立廣告群組時,您可以使用該資源名稱來參照它,而您指定的 -1 會自動替換成所建立廣告活動的實際 ID。

使用臨時資源名稱時,請注意下列事項:

  • 您必須在資源中定義臨時資源名稱,才能使用。在以下範例中,廣告群組作業必須在作業清單中的廣告活動作業完成後顯示。
  • 系統不會記住所有工作或變更要求中的臨時資源名稱;如要參照在先前工作或修改要求中建立的資源,請使用實際資源名稱。
  • 如果是單一工作或 change 請求,每個臨時資源名稱都必須使用唯一的負數,即使它們來自不同的資源類型也一樣。如果在單一工作或變更要求中重複使用臨時 ID,系統會傳回錯誤。

範例

為了讓有關上述情況的具體範例,假設您想在單一 API 要求中新增廣告活動、廣告群組和廣告。您將為要求建立結構,類似於下列內容:

mutate_operations: [
  {
    campaign_operation: {
      create: {
        resource_name: "customers/<YOUR_CUSTOMER_ID>/campaigns/-1",
        ...
      }
    }
  },
  {
    ad_group_operation: {
      create: {
        resource_name: "customers/<YOUR_CUSTOMER_ID>/adGroups/-2",
        campaign: "customers/<YOUR_CUSTOMER_ID>/campaigns/-1"
        ...
      }
    }
  },
  {
    ad_group_ad_operation: {
      create: {
        ad_group: "customers/<YOUR_CUSTOMER_ID>/adGroups/-2"
        ...
      }
    }
  },
]

請注意,廣告群組會使用新的臨時 ID,因為我們無法重複使用廣告活動所用的 -1,而且建立廣告群組廣告時,也會參照這個廣告群組。廣告群組本身參照了我們在要求先前作業中為廣告活動建立的資源名稱,而 ad_group_ad_operation 中的 resource_name 並不需要,因為沒有其他作業參照該名稱。