更新商家適用的 Vertex AI Search 店面商品目錄

LocalInventory 是與特定地點相關聯的商品目錄資訊，可透過 place_id 識別。舉例來說，可以為提供特定價格的商店或區域建立 LocalInventory。LocalInventory 具有以下欄位：

• LocalInventory.price_info
• LocalInventory.attributes
• LocalInventory.fulfillment_types

現有的 LocalInventory 項目會透過 Product.local_inventories 顯示 (fulfillment_types 除外，為了回溯相容性，fulfillment_types 會透過 Product.fulfillment_info 提供)。這個欄位僅供輸出。設定 Product.local_inventories 對 Product CRUD API 或 SetInventory 沒有影響。

每個 (LocalInventory.place_id, LocalInventory.fulfillment_types[...]) 配對都指向商品目錄更新說明文件中提及的相同 (fulfillment_info.place_ids, fulfillment_info.type) 配對。fulfillment_types 由 AddLocalInventories 和 RemoveLocalInventories 更新，反映每個地點 ID 到其支援的出貨類型清單的對應，而 fulfillment_info 由 AddFulfillmentPlaces 和 RemoveFulfillmentPlaces 更新，反映每個特定出貨類型到支援該類型的地點 ID 清單的對應。不過，這兩種 API 類型都會修改相同的基礎出貨資訊，且兩種 API 類型的影響都會反映在 Product.fulfillment_info 上。

店面商品目錄更新方法

與產品目錄資訊相比，產品的店面商品目錄資訊較常異動。系統提供一組專用方法，可處理大量店面商品目錄專屬更新。這些方法具備非同步的特性，這是因為下游最佳化調整功能可以針對個別產品並行執行數百項更新作業，而且不會影響效能。

AddLocalInventories

AddLocalInventories 可用於在新地點 (以新的 place_id 表示) 建立店面商品目錄，或更新現有店面商品目錄的現有欄位。透過要求主體中的 LocalInventory 項目清單新增或更新的欄位，可透過 AddLocalInventoriesRequest.add_mask 指定。add_mask 的有效值如下：

• price_info：會覆寫 LocalInventory.price_info。
• attributes：覆寫所有 LocalInventory.attributes。系統會移除要求內容中未提及的現有屬性。
• attributes.PLACEHOLDER_NAME：只會覆寫指定的自訂屬性。如果要求中未提供現有屬性名稱，系統會刪除該屬性。只要每個屬性名稱不同，即可指定多個 attributes.PLACEHOLDER_NAME。不過，AddLocalInventoriesRequest.add_mask 無法在同一項要求中同時包含 attributes 值和 attributes.PLACEHOLDER_NAME 值。
• fulfillment_types：覆寫所有支援的執行類型。系統會移除要求主體中未提及的現有運送方式。

{
  product: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
  local_inventories: {
    place_id: "store1"
    price_info: {
      currency_code: "USD"
      price: 100
      original_price: 110
      cost: 95
    }
    fulfillment_types: "pickup-in-store"
    fulfillment_types: "ship-to-store"
  }
  local_inventories: {
    place_id: "store2"
    price_info: {
      currency_code: "USD"
      price: 200
      original_price: 210
      cost: 195
    }
    attributes: {
      key: "attr1",
      value: {
        text: "store2_value"
      }
    }
    fulfillment_types: "custom-type-1"
  }
  add_mask: {
    paths: "price_info"
    paths: "attributes.attr1"
    paths: "fulfillment_types"
  }
  add_time: {
    seconds: 100
    nanos: 100
  }
  allow_missing: true
}
  

這個範例會新增或更新指定產品的兩個店面商品目錄，並提供地點 ID "store1" 和 "store2"。AddLocalInventoriesRequest如果 store1 存在，且 store2 在要求前不存在，要求會更新 store1 的欄位，並使用指定欄位值建立 store2。

這個 AddLocalInventoriesRequest.add_mask 會指定要使用 AddLocalInventoriesRequest.local_inventories 中提供的值，更新名為 "attr1" 的單一自訂屬性 price_info 和 fulfillment_types。

attributes 是與地點相關聯的屬性，名稱和值可自訂。由於 LocalInventory 的 store1 不會在要求中提供 attr1 的值，因此如果現有 LocalInventory 的 store1 中有自訂屬性 attr1，系統會將其刪除。store2 的 attr1 屬性值會設為文字值 store2_value。store1 和 store2 上的其他現有自訂屬性則不受影響。

fulfillment_types 代表單一地點的 Product 出貨供應情形清單。這與 fulfillment_info.type 相同，且接受相同的值。這個 AddLocalInventoriesRequest 會指定 store1 支援 pickup-in-store 和 ship-to-store 出貨類型，而 store1 支援 custom-type-1。如果要求中未提及更新前存在的履行類型，系統會將其刪除。

由於 AddLocalInventoriesRequest.allow_missing 設為 true，即使產品尚不存在，系統也會儲存更新後的店面商品目錄資訊，以供日後建立產品時使用。更新會加上 AddLocalInventoriesRequest.add_time 時間戳記，以免過時的更新覆寫這些地點 ID 的指定欄位。如要進一步瞭解如何避免過時的更新，以及在建立產品前儲存店面商品目錄資訊，請參閱「店面商品目錄更新的時間戳記保護措施」和「預先載入商品目錄資訊」。

{
  product: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
  local_inventories: {
    place_id: "store3"
    attributes: {
      key: "attr1",
      value: {
        text: "attr1_value"
      }
    }
    attributes: {
      key: "attr2",
      value: {
        numbers: 123
      }
    }
  }
  add_mask: {
    paths: "attributes"
  }
  add_time: {
    seconds: 100
    nanos: 100
  }
}
  

這個範例會新增或更新指定產品的單一店面商品目錄，並使用地點 ID "store3"。AddLocalInventoriesRequest由於 add_mask 包含 "attributes"，系統會刪除 store3 的所有現有自訂屬性，並替換為要求中指定的 attr1 和 attr2。請注意，由於未設定 allow_missing，因此必須存在指定的產品。否則會擲回 NOT_FOUND 錯誤。

RemoveLocalInventories

RemoveLocalInventories 可用於移除指定地點 ID 的現有店面商品目錄。

{
  product: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
  place_ids: "store1"
  place_ids: "store2"
  remove_time: {
    seconds: 100
    nanos: 100
  }
  allow_missing: true
}
  

這個範例 RemoveLocalInventoriesRequest 會移除指定產品在地點 ID 為 "store1" 和 "store2" 的地點的店面商品目錄資料。更新會加上 RemoveLocalInventoriesRequest.remove_time的時間戳記，以免過時的更新覆寫這些地點 ID 的刪除作業。如果指定地點 ID 沒有現有的店面商品目錄，要求也會將更新時間記錄到 remove_time。如要進一步瞭解更新時間戳記，請參閱店面商品目錄資料更新的時間戳記保護措施

店面商品目錄更新的時間戳記保護機制

為避免更新順序有誤，每個店面商品目錄欄位都會與最近一次更新時間相關聯。

系統會記錄每個 (place_id, price_info)、(place_id, attributes[...]) 和 (place_id, fulfillment_types[...]) 配對的最新更新時間。

呼叫端可透過 AddLocalInventories 和 RemoveLocalInventories 方法，指定發出要求時的更新時間。系統會將這個更新時間與相關庫存欄位記錄的最近更新時間進行比較，且只有在更新時間嚴格晚於最近更新時間時，才會提交更新。

舉例來說，假設地點 ID "store1" 有 price_info，且最後記錄的更新時間設為時間 T。如果 RemoveLocalInventoriesRequest.place_ids 包含 "store1"，則只有在 RemoveLocalInventoriesRequest.remove_time 晚於時間 T 時，要求才會從 "store1" 移除 price_info。RemoveLocalInventoriesRequest 也是如此。

在時間戳記保護機制下，RemoveLocalInventoriesRequest 可能只會移除 LocalInventory 的特定欄位，而非所有欄位。假設地點 ID 為 "store1" 的店面商品目錄有 price_info，且最後記錄的更新時間設為 T1，而名稱為 "attr1" 的現有自訂屬性最後記錄的更新時間為 T2。如果 RemoveLocalInventoriesRequest.place_ids 包含 "store1"，且 remove_time 設為 T3 (其中 T1 < T3 < T2)，則 store_1 的 price_info 會移除，但其屬性 attr1 不會受到影響。

預先載入商品目錄資訊

呼叫者可透過任一店面商品目錄更新方法，在要求中設定 allow_missing。如果 allow_missing 設為 true，系統會根據方法規格，將對不存在的 Product 進行的店面商品目錄更新，視為對現有 Product 進行的更新。如果未在上述時間範圍內使用 CreateProduct 建立相應的 Product，店面商品目錄資訊最多只會保留兩天。