更新 AI Commerce Search 的商品目录

本页概述了如何使用 AI Commerce Search API 管理 AI Commerce Search 目录的实时价格和数量更新。

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

了解商品目录

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

商品级商品目录

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

本地商品目录

对于拥有多个地点的零售商，商品仍由目录中的 Product 条目表示，但可以使用 addLocalInventories 方法将本地商品目录（价格、库存状况和履单）添加到商品的地点 (placeId)。

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

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

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

商品目录更新方法

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

增量更新

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

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

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

Java

如需了解如何安装和使用 AI Commerce Search 客户端库，请参阅 AI Commerce Search 客户端库。 如需了解详情，请参阅 AI Commerce Search Java API 参考文档。

如需向 AI Commerce Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅 为本地开发环境设置身份验证。 

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 到其支持的履单类型列表的映射。当 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

如需了解如何安装和使用 AI Commerce Search 客户端库，请参阅 AI Commerce Search 客户端库。 如需了解详情，请参阅 AI Commerce Search Java API 参考文档。

如需向 AI Commerce Search 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅 为本地开发环境设置身份验证。 

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 适用于此产品此 履单类型。所有其他履单类型不会在此请求中更新。因此，此方法可用于仅替换部分履单类型的地点 ID，而让其他类型保持不变。

默认情况下，SetInventory 将更新所有库存字段，如果 SetInventory.set_mask 未设置或为空。如果掩码不为空或 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 会隐式要求为给定履单类型添加所有指定的地点 ID，并移除所有未指定的现有地点 ID。

处理 SetInventoryRequest 时，对于指定的每个履单类型，fulfillment_info 更新都会隐式转换为 AddFulfillmentPlacesRequest 和 RemoveFulfillmentPlacesRequest。也就是说 如果任何具有履单 "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 会 支持履单类型 "pickup-in-store" 和 "same-day-delivery"。

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

UpdateProduct

The 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 示例。

对于本地商品目录，可以在 fulfillmentInfo 中传入 placeIds 和履单类型，如以下 curl 示例所示：

教程

请按照这些教程的说明，了解如何使用 setInventory 或添加或移除履单。

教程：设置商品目录

本教程介绍了如何使用 SetInventory方法推送商品目录更新，而无需更新整个商品。

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

操作演示

教程：添加履单信息

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

本教程介绍了如何使用 AddFulfillmentPlaces 方法更新产品履单信息。这样，搜索就可以显示产品有货且订单可以履单的更新。例如，一位购物者在一家商店寻找蓝色牛仔裤，但牛仔裤缺货了。当这家商店或任何其他商店再次有货时，买家会看到更新，并可以继续下单。

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

操作演示

教程：移除履单

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

本教程介绍了如何使用 RemoveFulfillmentPlaces 方法更新产品履单信息。这样，AI Commerce Search 就可以显示产品缺货且订单无法履单的更新。这样，搜索就可以显示产品缺货且订单无法履单的更新。例如，一位购物者在一家商店寻找蓝色牛仔裤。如果这家商店的牛仔裤缺货，购物者会看到此信息，并且无法继续下单。

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

操作演示