这是 Recommendations AI、Retail Search 和新的 Retail 控制台的文档。

更新用于零售搜索的本地商品目录

LocalInventory 是与特定地点关联的商品目录信息,由其 place_id 标识。例如,可以为有特定价格的商店或区域创建 LocalInventoryLocalInventory 具有以下字段:

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

现有的 LocalInventory 条目通过 Product.local_inventories 可见(fulfillment_types 除外,为实现向后兼容性,必须通过 Product.fulfillment_info 提供)。此字段仅限输出。为 Product CRUD API 或 SetInventory 设置 Product.local_inventories 不会产生任何影响。

每个 (LocalInventory.place_id, LocalInventory.fulfillment_types[...]) 对均指向商品目录更新文档中提到的同一 (fulfillment_info.place_ids, fulfillment_info.type) 对。由 AddLocalInventoriesRemoveLocalInventories 更新的 fulfillment_types(如下所述)反映了从每个地点 ID 到其支持的 fulfillment 类型列表的映射,而由 AddFulfillmentPlacesRemoveFulfillmentPlaces 更新的 fulfillment_info 反映了从每个特定的 fulfillment 类型到支持此类类型的地点 ID 的映射。但是,这两种类型的 API 都会修改相同的底层 fulfillment 信息,并且这两种类型的 API 的效果会反映在 Product.fulfillment_info 上。

本地商品目录更新方法

与商品目录信息的更改相比,对商品本地商品目录信息的更改频率可能要高得多。Google 提供了一组专门的方法来处理大量特定于本地商品目录的更新。这些方法是异步的,因为下游优化可支持每个产品进行的数百个并发更新,同时不影响性能。

AddLocalInventories

AddLocalInventories 可用于在新位置(以新的 place_id 表示)创建本地商品目录,或更新现有本地商品目录中的现有字段。可通过 AddLocalInventoriesRequest.add_mask 指定在请求正文中的 LocalInventory 条目列表上添加或更新的字段。有效的 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:覆盖所有受支持的执行方式类型。系统会移除请求正文中未提及的现有执行方式类型。

Proto

{
  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
}
  

此示例 AddLocalInventoriesRequest 为指定商品添加或更新两个 ID 为 "store1""store2" 的本地商品目录。如果 store1 存在,并且 store2 在请求之前不存在,则请求将更新 store1 的字段,并使用给定字段值创建 store2

AddLocalInventoriesRequest.add_mask 指定应使用 AddLocalInventoriesRequest.local_inventories 中提供的值更新 price_info(名为 "attr1" 的单个自定义特性)和 fulfillment_types

attributes 是与具有可自定义名称和值的地点相关联的属性。由于 store1LocalInventory 不会在请求中提供 attr1 的值,因此自定义属性 attr1 将从 store1 的现有 LocalInventory 中删除(如果存在)。store2attr1 属性值会设为文本值 store2_valuestore1store2 上的其他现有自定义属性保持不变。

fulfillment_types 表示 Product 的 fulfillment 的可用性列表。它与 fulfillment_info.type 相同且接受相同的值。此 AddLocalInventoriesRequest 指定 store1 支持 pickup-in-storeship-to-store 执行方式类型,而 store1 支持 custom-type-1。此更新之前已存在的请求中未提及的执行方式类型将被删除。

由于 AddLocalInventoriesRequest.allow_missing 设置为 true,因此即使商品尚不存在,系统也会在商品最终创建时存储更新后的本地商品目录信息。更新的时间戳带有 AddLocalInventoriesRequest.add_time,以防止过时更新覆盖这些地点 ID 的指定字段。如需详细了解如何在创建商品之前防止过时更新和存储本地商品目录信息,请参阅本地商品目录更新的时间戳保护预加载商品目录信息

Proto

{
  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
  }
}
  

此示例 AddLocalInventoriesRequest 为指定商品添加了或更新地点 ID 为 "store3" 的单个本地商品目录。由于其 add_mask 包含 "attributes",因此 store3 的所有现有自定义属性都会被删除,并替换为请求中指定的 attr1attr2。请注意,由于 allow_missing 未设置,因此指定产品必须存在。否则会抛出 NOT_FOUND 错误。

RemoveLocalInventories

RemoveLocalInventories 可用于移除具有指定地点 ID 的地点的现有本地商品目录。

Proto

{
  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[...]) 对的最新更新时间。

AddLocalInventoriesRemoveLocalInventories 方法允许调用方指定在发出请求时的更新时间。系统会将此更新时间与相关目录字段记录的最新更新时间进行比较。当且仅当更新时间严格晚于最新更新时间时,系统才会提交更新。

例如,假设地点 ID "store1" 具有 price_info,并且上次记录的更新时间设置为 T。如果 RemoveLocalInventoriesRequest.place_ids 包含 "store1",则仅当 RemoveLocalInventoriesRequest.remove_time 晚于 T 时,请求才会从 "store1" 中移除 price_infoRemoveLocalInventoriesRequest 也是如此。

在时间戳保护下,RemoveLocalInventoriesRequest 可能只能移除 LocalInventory 的某些字段,而不是所有字段。假设具有 ID 为 "store1" 的本地商品目录中的 price_info 的上次记录更新时间设置为 T1,并且其唯一自定义名称为 "attr1" 且上次记录的更新时间为 T2。如果 RemoveLocalInventoriesRequest.place_ids 包含 "store1"remove_time 设置为 T3(其中 T1 < T3 < T2),系统将移除 store_1price_info,而其属性 attr1 不会受到影响。

预加载商品目录信息

每种本地商品目录更新方法都允许调用方在请求中设置 allow_missing。当 allow_missing 设置为 true 时,系统会按照方法规范处理 Product 的本地目录更新,就像存在 Product 一样。如果未在此时间范围内通过 CreateProduct 创建相应的 Product,本地商品目录信息将最多保留两天。