更新 Vertex AI Search for Commerce 的商品目录

本页面概述了如何使用 Retail API 管理 Vertex AI Search for commerce 商品目录的实时价格和数量更新。

虽然使用 Product 创建、读取、更新和删除 (CRUD) 方法可广泛修改 Product 的属性，但有一组 Product 方法可用于用于更新具有不同粒度级别的商品目录特定字段。

了解广告资源

一般来说，商品目录通常是指电子商务网站上商品的库存水平（数量）和价格。对于 Retail API，inventory 是指价格、库存状况、可供数量、履单信息、本地价格和其他本地属性。这些字段在商品架构中定义，包含以下字段：

产品级广告资源

对于仅有在线商品目录的电子商务网站商家，inventory 通常仅表示商品目录中的商品。价格、库存状况和所有其他数据均在目录中的每个商品条目中设置。fulfillmentInfo 和 localInventories 字段未被使用。

本地商品目录

对于拥有多个营业地点的零售商，商品仍由商品目录中的商品条目表示，但可以使用 addLocalInventories 方法为具有特定营业地点 ID (placeId) 的商品添加本地商品目录（价格、库存状况和配送）信息。

本地商品目录使用两个单独的商品字段：Product.fulfillmentInfo 和 Product.localInventories。您可以根据需要使用其中一种或两种。fulfillmentInfo 和 localInventories 都是包含关联数据的位置列表。

fulfillmentInfo 用于指定商品在特定地点的配送方式，而 localInventories 用于指定每个地点的价格和其他自定义属性。

如需将商品标记为缺货或在特定位置不再有售，请使用 removeLocalInventories 方法从特定 placeId 的商品中移除 fulfillment 和 inventory。

商品目录更新方法

更改产品目录信息的频率要比更改目录信息的频率高得多。因此，我们提供了一套专门的方法来处理大量特定于商品目录的更新。这些方法是异步的，因为下游优化支持每个产品数百个并发更新，而不会影响性能。

增量更新

按照本地商品目录更新指南发布增量商品目录更新。新的 API 方法可针对每个地点提供更精细的商品目录属性控制。

fulfillment_info 通常用于对 Product 的地点级 fulfillment 可用性进行编码。在某些情况下，某些特定地点的履单可用性可能会发生变化。您可以决定发出描述此更改的更新，而不是使用 UpdateProduct 方法重新指定所有商品的履单信息。

在这种情况下，AddFulfillmentPlaces 和 RemoveFulfillmentPlaces 方法可用于根据地点 ID 逐步更新商品的 fulfillment 更改为给定的 fulfillment 类型添加或移除资源。

Java

如需了解如何安装和使用 Vertex AI Search 商务解决方案客户端库，请参阅 Vertex AI Search 商务解决方案客户端库。 如需了解详情，请参阅 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 添加了 fulfillment 类型 "pickup-in-store"，以便为指定商品放置 ID "store0" 和 "store1"。由于 AddFulfillmentPlacesRequest.allow_missing 设置为 true，因此即使商品尚不存在，系统也会存储更新后的商品目录信息，以供最终创建商品时使用。更新带有 AddFulfillmentPlacesRequest.add_time 时间戳，以防止过时更新覆盖这些地点 ID 的 fulfillment 状态。以下各部分将更详细地讨论这些功能。

RemoveFulfillmentPlacesRequest 的行为完全相同，架构非常相似。

当 fulfillment_types 通过 AddLocalInventories 和 RemoveLocalInventories 进行更新时，它会反映从每个地点 ID 到其支持的 fulfillment 类型列表的映射。当 fulfillment_info 通过 AddFulfillmentPlaces 和 RemoveFulfillmentPlaces 进行更新时，它会反映从每个特定履单类型到支持每种类型的地点 ID 列表的映射。这两种 API 类型都会修改相同的底层履单信息，并且这两种 API 类型的效果都会反映在 Product.fulfillment_info 中。

非增量更新

price_info、availability 和 available_quantity 方法无法增量更新，因为它们代表商品级商品目录，而不是地点级信息。向 fulfillment_info 发出非增量更新也是不错的做法。建议使用 SetInventory，而不是仅使用增量更改。

如果需要频繁更新大量商品的价格、库存状况和数量，建议使用 setInventory 方法在商品级别更新这些信息。setInventory 方法是异步的，因此更新可能不会立即发生。默认配额（每分钟 30 万次请求）支持的请求次数远高于 UpdateProduct。

此外，当请求中包含 fulfillmentInfo 时，setInventory 方法用于本地履单更新，但无法更新 localInventories 字段。对于这些属性，请使用 addLocalInventories 和 removeLocalInventories 方法。

本地商品目录会保存在实体店一级，与商品目录无关。对于同时拥有线上和线下商品目录的客户，主商品目录可用于线上，也可使用特定 placeId（例如 -1 或 online）来表示线上商品目录。不过，请使用主目录来表示线上商品目录，因为商品目录字段应填充有效的 priceInfo 和 availability 值。如果线上商品使用单独的商品目录 placeId，那么主商品目录的价格和库存状况信息也应保持最新状态。如需详细了解本地商品目录更新，请参阅更新本地商品目录。

Java

如需了解如何安装和使用 Vertex AI Search 商务解决方案客户端库，请参阅 Vertex AI Search 商务解决方案客户端库。 如需了解详情，请参阅 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 字段是每个 fulfillment 类型符合条件的地点 ID 的完整说明，而不是增量规范。更新为 "same-day-delivery" 表示没有地点 ID 适用于此产品此 fulfillment 类型。所有其他 fulfillment 类型不会在此请求中更新。因此，此方法可用于仅替换部分配送类型的地点 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" 启用了 fulfillment 类型 "pickup-in- store"，并且上次记录的更新时间设置为 T。如果 RemoveFulfillmentPlacesRequest.type = "pickup-in-store" 和 RemoveFulfillmentPlacesRequest.place_ids 包含 "store1"，则当且仅当 RemoveFulfillmentPlacesRequest.remove_time 晚于 T 时，请求才会从 "store1" 清除 "pickup-in-store"。AddFulfillmentPlacesRequests 也是如此。

SetInventory 的运行方式与更新 price_info、availability 和 available_quantity 类似。更新 fulfillment_info 时，SetInventoryRequest 会隐式要求为给定 fulfillment 类型添加所有指定的地点 ID，并移除所有未指定的现有地点 ID。

在处理 SetInventoryRequest 时，对于指定的每个履单类型，fulfillment_info 更新都会隐式转换为 AddFulfillmentPlacesRequest 和 RemoveFulfillmentPlacesRequest。也就是说，如果任何具有 fulfillment "pickup-in-store" 的现有地点 "store1" 的上次更新时间 T 晚于 SetInventoryRequest.set_time，将不会对 "store1" 和 "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 支持 fulfillment 类型 "pickup-in-store" 和 "same-day-delivery"。

如果不确定所有预加载的商品目录信息是否准确，并且宁愿在 Product 创建时显式设置商品目录以完全同步目录和商品目录，则带有商品目录信息的 CreateProduct 可能会有所帮助。

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 v2 过滤器和提升控制变量 是 否
功能 商品级目录 实体店级（本地）商品目录
搜索过滤条件和提升控制功能
facetSpec 中指定的过滤条件和分面键格式
可用于搜索方面的
在搜索响应中返回 （使用 variantRollupKeys）
Recommendations AI v2 过滤器和提升控制变量

在更新商品供应情况、配送信息和本地价格的不同方法中，部分功能存在重叠：

功能 UpdateProduct setInventory addLocalInventories
实时更新
更新任何商品字段
更新商品价格
更新商品库存状况
更新 fulfillmentInfo
更新 localInventories（本地价格）
时间戳顺序

示例

本部分演示了如何在 curl 命令中使用 UpdateProduct 和 setInventory 方法来更新商品目录。

  • UpdateProduct 使用 REST API 的 HTTP PATCH 方法同步实时更新价格和供应情况等商品级字段，还可以通过将 import 方法与 updateMask 搭配使用来进行批量更新。

  • 异步 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 Editor 中点击操作演示：

操作演示

教程：添加履单信息

我们建议使用 AddLocalInventories 方法，而不是 AddFulfillmentPlaces。AddLocalInventories 可实现相同的结果，但可更精细地控制本地商品目录数据的提取。如需了解详情，请参阅 AddLocalInventories 文档。

本教程介绍了如何使用 AddFulfillmentPlaces 方法更新商品履单信息。这样，搜索结果中便会显示有货且可履单的商品。例如，买家在商店中寻找蓝色牛仔裤，但商店缺货。当这条牛仔裤再次在相应商店或任何其他商店上架时，买家会看到更新，并可以继续下单。

如需遵循有关此任务的分步指导，请直接在 Cloud Shell Editor 中点击操作演示：

操作演示

教程：移除履单

我们建议使用 RemoveLocalInventories 方法，而不是 RemoveFulfillmentPlaces。RmoveLocalInventories 可实现相同的结果，但可更精细地控制本地商品目录数据的提取。如需了解详情，请参阅 RemoveLocalInventories 文档。

本教程介绍了如何使用 RemoveFulfillmentPlaces 方法更新商品履单信息。这样一来，Vertex AI Search for commerce 就可以显示商品缺货和订单无法完成的更新。这样，搜索结果中就可以显示商品缺货和订单无法配送的更新信息。例如，买家在商店中寻找蓝色牛仔裤。如果该商店中的牛仔裤缺货，买家会看到此消息，并且无法继续下单。

如需遵循有关此任务的分步指导，请直接在 Cloud Shell Editor 中点击操作演示：

操作演示