更新商家適用的 Vertex AI Search 廣告空間

本頁面說明如何使用 Retail API，管理 Vertex AI Search for commerce 目錄的即時價格和數量更新。

Product 建立、讀取、更新和刪除 (CRUD) 方法可用於廣泛修改 Product 的屬性，但有一組 Product 方法可用於更新不同精細程度的庫存特定欄位。

瞭解廣告空間

一般來說，商品目錄通常是指電子商務網站上商品的庫存量 (數量) 和價格。在 Retail API 中，inventory 是指價格、供應情形、現貨數量、出貨資訊、店面價格和額外店面屬性。這些欄位會在「產品」結構定義中定義，包含下列欄位：

產品層級的商品目錄

如果電子商務網站商家只有線上目錄，inventory 通常只代表目錄中的產品。價格、供應情形和所有其他資料，都是在目錄中的每個「產品」項目中設定。不會使用 fulfillmentInfo 和 localInventories 欄位。

店面商品目錄

如果零售商有多個地點，產品仍會以目錄中的產品項目表示，但可使用 addLocalInventories 方法，為產品的地點 (placeId) 新增店面商品目錄 (價格、供應情形和出貨)。

店面商品目錄有兩個不同的產品欄位：Product.fulfillmentInfo 和 Product.localInventories。視需求而定，您可以選擇使用其中一種或兩種方式。fulfillmentInfo 和 localInventories 都是地點清單，內含相關聯的資料。

fulfillmentInfo 會指定特定地點的產品出貨方式，而 localInventories 則會指定每個地點的價格和其他自訂屬性。

如要將產品標示為缺貨或在特定地點停售，請使用 removeLocalInventories 方法，從特定 placeId 的產品中移除 fulfillment 和 inventory。

商品目錄更新方法

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

分批更新

請按照店面商品目錄更新指南，發布增量商品目錄更新。新版 API 方法可更精細地控管各個地點的廣告空間屬性。

fulfillment_info 通常用於編碼 Product 的地點層級出貨供應情形。有時，特定地點的出貨供應情形可能會有所異動。您可以決定發布更新內容來描述這項變更，而不必使用 UpdateProduct 方法重新指定所有產品的出貨資訊。

在這種情況下，您可以使用 AddFulfillmentPlaces 和 RemoveFulfillmentPlaces 方法，根據指定出貨類型新增或移除的地點 ID，逐步更新產品的出貨資訊異動。

Java

如要瞭解如何安裝及使用 Vertex AI Search for commerce 的用戶端程式庫，請參閱「Vertex AI Search for commerce 用戶端程式庫」。詳情請參閱 Vertex AI Search for commerce Java API 參考文件。

如要向 Vertex AI Search for commerce 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

public static AddFulfillmentPlacesResponse addFulfillmentPlaces(
    Product productToUpdate, String fulfillmentInfoType, ImmutableList<String> placeIds)
    throws IOException, InterruptedException, ExecutionException {
  ProductServiceClient productClient = getProductServiceClient();

  AddFulfillmentPlacesRequest request = AddFulfillmentPlacesRequest.newBuilder()
      .setProduct(productToUpdate.getName())
      .setType(fulfillmentInfoType)
      .addAllPlaceIds(placeIds)
      .setAddTime(Timestamps.fromMillis(System.currentTimeMillis()))
      .build();

  AddFulfillmentPlacesResponse response = productClient
      .addFulfillmentPlacesAsync(request).get();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return response;
}

Proto

  {
    product: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
    type: "pickup-in-store"
    place_ids: "store0"
    place_ids: "store1"
    add_time: {
      seconds: 100
      nanos: 100
    }
    allow_missing: true
  }

這個範例 AddFulfillmentPlacesRequest 會新增履單類型 "pickup-in-store"，為指定產品放置 ID "store0" 和 "store1"。由於 AddFulfillmentPlacesRequest.allow_missing 設為 true，即使產品尚不存在，系統也會儲存更新後的庫存資訊，待產品建立後再套用。更新會加上時間戳記 AddFulfillmentPlacesRequest.add_time，以免過時的更新覆寫這些地點 ID 的出貨狀態。以下各節將詳細說明這些功能。

RemoveFulfillmentPlacesRequest 的行為與 完全相同，結構定義也十分相似。

fulfillment_types 由 AddLocalInventories 和 RemoveLocalInventories 更新時，會反映從每個地點 ID 到其支援的出貨類型清單的對應。當 AddFulfillmentPlaces 和 RemoveFulfillmentPlaces 更新 fulfillment_info 時，會反映從各個特定出貨類型到支援各類型的地點 ID 清單的對應。這兩種 API 類型都會修改相同的基礎出貨資訊，而這兩種 API 類型的影響都會反映在 Product.fulfillment_info 中。

非增量更新

price_info、availability 和 available_quantity 方法無法逐步更新，因為這些方法代表產品層級的商品目錄，而非地點層級的資訊。此外，向 fulfillment_info 發布非累加更新也是不錯的做法。建議使用 SetInventory，而非僅進行增量變更。

如果需要經常更新大量產品的價格、供應情形和數量，建議使用 setInventory 方法。setInventory 方法為非同步，因此更新可能不會立即生效。預設配額 (每分鐘 300,000 個要求) 支援的要求數量遠高於 UpdateProduct。

此外，如果要求中包含 fulfillmentInfo，系統會使用 setInventory 方法更新店面出貨資訊，但無法更新 localInventories 欄位。如要設定這些屬性，請使用 addLocalInventories 和 removeLocalInventories 方法。

店面商品目錄資料會儲存在商店層級，與目錄無關。如果顧客有線上和線下商品目錄，主要產品目錄可用於線上，或使用特定 placeId (例如 -1 或 online) 代表線上商品目錄。不過，請使用主要目錄的線上商品目錄，因為產品商品目錄欄位應填入有效的 priceInfo 和 availability 值。如果線上使用獨立的商品目錄 placeId，主要目錄的價格和供應情形資訊也應保持最新狀態。如要進一步瞭解如何更新店面商品目錄資料，請參閱這篇文章。

Java

如要瞭解如何安裝及使用 Vertex AI Search for commerce 的用戶端程式庫，請參閱「Vertex AI Search for commerce 用戶端程式庫」。詳情請參閱 Vertex AI Search for commerce Java API 參考文件。

如要向 Vertex AI Search for commerce 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

public static SetInventoryResponse setInventoryWithMask(Product productToUpdate,
    FieldMask updateMask)
    throws IOException, ExecutionException, InterruptedException {
  ProductServiceClient productClient = getProductServiceClient();

  SetInventoryRequest request = SetInventoryRequest.newBuilder()
      .setInventory(productToUpdate)
      .setSetMask(updateMask)
      .setSetTime(Timestamps.fromMillis(System.currentTimeMillis()))
      .setAllowMissing(true)
      .build();

  SetInventoryResponse response = productClient.setInventoryAsync(request).get();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return response;
}

Proto

  {
    product: {
      name: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
      availability: IN_STOCK
      fulfillment_info: {
        type: "pickup-in-store"
        place_ids: "store0"
        place_ids: "store1"
        place_ids: "store2"
        place_ids: "store3"
      }
      fulfillment_info: {
        type: "same-day-delivery"
      }
    }
    set_time: {
      seconds: 100
      nanos: 100
    }
    set_mask: {
      paths: "availability"
      paths: "fulfillment_info"
    }
    allow_missing: true
  }

在這個特定要求中，SetInventoryRequest.product.fulfillment_info 欄位是各項履行類型合格地點 ID 的完整說明， 而非增量規格。"same-day-delivery" 更新表示這個產品沒有符合這項出貨類型的地點 ID。這項要求不會更新所有其他履行類型。因此，這個方法可用於只替換部分出貨類型的地點 ID，其他類型則不受影響。

根據預設，如果 SetInventory.set_mask 未設定或空白，SetInventory 會更新所有廣告空間欄位。如果遮罩不是空白，或SetInventoryRequest.set_mask中未明確列出任何目錄欄位，系統就會在更新要求中忽略該目錄欄位的任何指定值。

與漸進式更新一樣，SetInventoryRequest.set_time 欄位可用於設定更新時間，該時間會與所有更新庫存欄位上次記錄的更新時間進行比較。

商品目錄更新的時間戳記保護措施

更新產品庫存欄位有多種不同方式，為避免更新順序有誤，每個庫存欄位都會與最近一次更新時間相關聯。

系統會記錄 price_info、availability、available_quantity 和每組 (fulfillment_info.place_ids, fulfillment_info.type) 的最新更新時間。

呼叫端可使用 AddFulfillmentPlaces、RemoveFulfillmentPlaces 和 SetInventory 方法，在發出要求時指定更新時間。系統會比較這個更新時間與相關庫存欄位記錄的最近更新時間，且只有在更新時間嚴格晚於最近更新時間時，才會提交更新。

舉例來說，假設地點 ID "store1" 已啟用出貨類型 "pickup-in- store"，且最後記錄的更新時間設為時間 T。如果 RemoveFulfillmentPlacesRequest.type = "pickup-in-store" 和 RemoveFulfillmentPlacesRequest.place_ids 包含 "store1"，則只有在 RemoveFulfillmentPlacesRequest.remove_time 晚於 T 時，要求才會從 "store1" 清除 "pickup-in-store"。AddFulfillmentPlacesRequests 也是如此。

更新 price_info、availability 和 available_quantity 的方式與 SetInventory 類似。更新 fulfillment_info 時，SetInventoryRequest 會隱含要求為指定履行類型新增所有指定的地點 ID，並移除所有未指定的現有地點 ID。

處理 SetInventoryRequest 時，系統會將 fulfillment_info 更新隱含轉換為 AddFulfillmentPlacesRequest 和 RemoveFulfillmentPlacesRequest，適用於每個指定的交車類型。也就是說，如果任何現有地點 "store1" 的履行 "pickup-in-store" 有比 SetInventoryRequest.set_time 更近的最後更新時間 T，系統就不會對 "store1" 和 "pickup-in-store" 隱含新增或移除 "pickup-in-store"。

預先載入屬性

setInventory 是非同步，也就是說，新增或修改商品目錄欄位時，系統不會強制執行任何分類或參照控制項。使用這個方法時，要求中參照的產品不一定要存在。

這可讓顧客實作預先載入模式，將目錄欄位的管理作業與主要目錄或產品匯入程序分離。舉例來說，使用者可以在匯入相關聯的產品之前，先匯入供應情形或價格背景資訊。

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

Java

public static SetInventoryResponse setInventory(Product productToUpdate)
    throws IOException, ExecutionException, InterruptedException {
  ProductServiceClient productClient = getProductServiceClient();

  SetInventoryRequest request = SetInventoryRequest.newBuilder()
      .setInventory(productToUpdate)
      .setSetTime(Timestamps.fromMillis(System.currentTimeMillis()))
      .setAllowMissing(true)
      .build();

  SetInventoryResponse response = productClient.setInventoryAsync(request).get();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return response;
}

使用 Product 方法的時機

雖然可以使用產品 CRUD 方法更新商品目錄欄位，但呼叫端應明確瞭解對現有或先前商品目錄資訊的影響。

這些是同步方法，也就是說，用於廣告空間方法的下游最佳化調整功能不適用，而且如果頻繁更新廣告空間，依賴這些方法可能會很耗費資源。請盡可能使用上述商品目錄更新方法。

CreateProduct

如果呼叫 CreateProduct 時已設定任何廣告空間欄位，CreateProductRequest.product 中提供的值會覆寫這些欄位的所有預先載入值。如未設定任何目錄欄位，系統會自動使用任何現有的目錄資訊。

此外，系統會將遭覆寫庫存欄位的最近更新時間，重設為方法呼叫時間。

CreateProduct (已預先載入廣告空間)

PROTO

{
  parent: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch"
  product_id: "p123"
  product: {
    name: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
    title: "some product"
    type: VARIANT
  }
}

在本範例中，建立的產品未設定任何庫存欄位，這表示如果使用庫存更新方法更新，系統會自動使用任何預先載入的庫存資訊。如果庫存更新與目錄更新脫鉤，且您想讓新建立的 Product 與任何現有庫存資訊同步，這項功能就非常實用。

CreateProduct (含明確廣告空間)

PROTO

{
  parent: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch"
  product_id: "p123"
  product: {
    name: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
    title: "some product"
    type: VARIANT
    availability: OUT_OF_STOCK
    fulfillment_info: {
      type: "pickup-in-store"
    }
    fulfillment_info: {
      type: "same-day-delivery"
    }
  }
}

在本範例中，系統會建立 Product，並明確設定目錄欄位。這些欄位會覆寫所有先前的值，並忽略對應欄位的最近更新時間。因此，新建立的 Product 會將供應情形設為 OUT_OF_STOCK，且沒有任何地點 ID 支援 "pickup-in-store" 和 "same-day-delivery" 履行類型。

CreateProduct，如果您不確定所有預先載入的商品目錄資訊是否正確，且偏好在建立 Product 時明確設定商品目錄，以完全同步處理目錄和商品目錄，這項功能就很有幫助。

UpdateProduct

UpdateProduct 方法可用來更新現有目錄項目的特定屬性。你可以同時為單一或多個欄位執行這項操作，也能為個別產品或使用匯入方法的多項產品執行這項操作。如果使用匯入方法時未提供遮罩，系統會覆寫資料。

UpdateProduct 通常用於即時更新價格和供應情形，但也可以用來更新任何欄位，不必再次提交產品的所有資料。(與 createMethod 或 importProducts 相較)。

使用 UpdateProduct 的主要優點是這項要求屬於同步要求。索引 (以及搜尋或建議) 的更新幾乎是即時的。不過，UpdateProduct 不適合用於頻繁更新。預設配額為每分鐘 12,000 項產品寫入要求。通常只有在商品價格或庫存狀態變更時，才需要使用這個方法 (而非每次數量減少時)。

UpdateProduct 只能修改產品層級屬性。無法用來修改 localInventories 或 fulfillmentInfo 的任何店面商品目錄屬性。

使用 UpdateProduct 或 ImportProducts 進行呼叫時，請務必指定 updateMask 參數。updateMask 包含要更新的欄位清單。即使要求主體中傳遞了更多欄位，系統也只會更新 updateMask 中指定的欄位。如果更新或匯入要求沒有 updateMask，系統會將所有欄位更新為要求主體中提交的內容。

如果叫用 UpdateProduct 且欄位遮罩 UpdateProductRequest.update_mask 包含任何目錄欄位，UpdateProductRequest.product 中提供的相應欄位值會覆寫任何預先載入的值。

此外，系統會將遭覆寫庫存欄位的最近更新時間，重設為方法呼叫時間。

PROTO

{
  product: {
    name: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
    availability: IN_STOCK
    fulfillment_info: {
      type: "pickup-in-store"
      place_ids: "store0"
      place_ids: "store1"
      place_ids: "store2"
      place_ids: "store3"
    }
    fulfillment_info: {
      type: "same-day-delivery"
    }
  }
  update_mask: {
    paths: "availability"
    paths: "fulfillment_info"
  }
}

這個範例與 SetInventory 範例非常相似，但無論各個目錄欄位的最新更新時間為何，更新都會套用。

  • 如果需要完整同步處理廣告空間資訊，但想忽略時間戳記保護措施，UpdateProduct 廣告空間就非常實用。

  • 將 UpdateProductRequest.allow_missing 設為 true 即可執行 Product 插入或更新作業，並使用 UpdateProduct 預先載入商品目錄資訊。這個方法需要設定特定目錄欄位，例如 UpdateProductRequest.product.title。因此，請使用預先載入用途的商品目錄更新方法。

DeleteProduct

呼叫 DeleteProduct 時，系統會刪除 DeleteProductRequest.name 中指定產品的所有現有商品目錄資訊，包括每個商品目錄欄位最新更新時間的所有記錄。

以庫存層級屬性取代產品層級屬性時的注意事項

請注意每種做法的相關注意事項和限制：

功能 產品層級的商品目錄 商店層級 (店面) 商品目錄
搜尋篩選器和加成控制項 是 是
facetSpec 中指定的篩選器和構面鍵格式 是 否
可用的搜尋構面 是 否
在搜尋回應中傳回 是 是 (使用 variantRollupKeys)
Recommendations AI 第 2 版篩選器和提升控制選項 是 否
功能 產品層級的商品目錄 商店層級 (店面) 商品目錄
搜尋篩選器和推薦控制選項
在 facetSpec 中指定的篩選器和構面鍵格式
可用的搜尋構面
在搜尋回應中傳回 (使用 variantRollupKeys)
Recommendations AI 第 2 版篩選器和提升控制選項

更新產品供應情形、出貨和店面價格的不同方法，在功能上有些重疊：

功能 UpdateProduct setInventory addLocalInventories
即時更新
更新任何產品欄位
更新產品價格
更新產品供應情形
更新 fulfillmentInfo
更新 localInventories (當地價格)
時間戳記順序

範例

本節將示範如何使用 curl 指令中的 UpdateProduct 和 setInventory 方法更新產品目錄。

  • UpdateProduct 會使用 REST API 的 HTTP PATCH 方法，同步即時更新產品層級的欄位，例如價格和供應情形，也可以搭配 updateMask 使用 import 方法進行批次更新。

  • 非同步 setInventory 方法用於使用 fulfillmentInfo 更新產品層級的商品目錄欄位 (價格、供應情形、數量) 和店面出貨詳細資料，但無法修改 localInventories 中儲存的店面價格或屬性。

使用 UpdateProduct 更新產品價格和供應情形

使用 REST API 時，UpdateProduct 會使用 HTTP PATCH 方法。與 CreateProduct、GetProduct、DeleteProduct 相同的端點網址，分別使用 HTTP PUT、GET 和 DELETE 方法。展開下列連結，即可查看對應的 curl 範例。

使用 setInventory 更新產品價格和供應情形

setInventory 僅支援下列欄位：

  • availability
  • availableQuantity
  • priceInfo

展開下列連結，即可查看對應的 curl 範例。

如果是店面商品目錄，則可將 placeIds 和運送方式類型傳入 fulfillmentInfo，如這個 curl 範例所示：

教學課程

請參閱這些教學課程，瞭解如何使用 setInventory，或是新增或移除出貨資訊。

教學課程：設定庫存資訊

本教學課程說明如何使用 SetInventory 方法推送商品目錄更新內容，不必更新整項產品。

如要直接在 Cloud Shell 編輯器中按照逐步指南操作，請按一下「Guide me」(逐步引導)：

逐步引導

教學課程：新增出貨地點

建議您改用 AddLocalInventories 方法，而非 AddFulfillmentPlaces。AddLocalInventories 可達到相同結果，但能更精細地控管店面商品目錄資料的擷取作業。詳情請參閱 AddLocalInventories 說明文件。

本教學課程將說明如何使用 AddFulfillmentPlaces 方法更新產品出貨資訊。這樣一來，搜尋結果就能顯示產品供應情形，以及訂單是否可出貨。舉例來說，購物者在商店尋找藍色牛仔褲，但商店缺貨。只要這間商店或任何其他商店再次進貨，購物者就會看到更新資訊，並繼續下單。

如要直接在 Cloud Shell 編輯器中按照逐步指南操作，請按一下「Guide me」(逐步引導)：

逐步引導

教學課程：移除出貨地點

建議您改用 RemoveLocalInventories 方法，而非 RemoveFulfillmentPlaces。RmoveLocalInventories 可達到相同結果，但能更精細地控管店面商品目錄資料的擷取作業。詳情請參閱 RemoveLocalInventories 說明文件。

本教學課程將說明如何使用 RemoveFulfillmentPlaces 方法更新產品出貨資訊。這樣一來，Vertex AI Search for commerce 就能顯示產品缺貨和訂單無法出貨的最新資訊。這樣一來，搜尋結果就能顯示產品缺貨或無法出貨的最新資訊。舉例來說，購物者在商店中尋找藍色牛仔褲，如果這間商店的牛仔褲缺貨，購物者會看到這項資訊，且無法繼續下單。

如要直接在 Cloud Shell 編輯器中按照逐步指南操作，請按一下「Guide me」(逐步引導)：

逐步引導