Retail 将更名为 Vertex AI Search for Retail。我们正在更新内容以反映新的品牌。

更新适用于零售业的 Vertex AI Search 的本地商品目录

LocalInventory 是与特定地点相关的商品目录信息，由其 place_id 标识。例如，您可以为商店或提供特定价格的区域创建 LocalInventory。LocalInventory 具有以下字段：

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) 对。由下文所述的 AddLocalInventories 和 RemoveLocalInventories 更新的 fulfillment_types 反映了从每个地点 ID 到其支持的履单类型列表的映射，而由 AddFulfillmentPlaces 和 RemoveFulfillmentPlaces 更新的 fulfillment_info 反映了从每个特定履单类型到支持该类型的地点 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：覆盖所有支持的执行方式类型。系统会移除请求正文中未提及的现有执行方式类型。

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 是与地点相关联的属性，具有可自定义的名称和值。由于 store1 的 LocalInventory 在请求中不提供 attr1 的值，因此自定义属性 attr1 将从 store1 的现有 LocalInventory 中删除（如果存在）。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 的指定字段。如需详细了解如何在创建商品之前防止过时更新以及存储本地商品目录信息，请参阅本地商品目录更新的时间戳保护措施和预加载商品目录信息。

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 的所有现有自定义属性都将被删除，并按照请求中指定的方式替换为 attr1 和 attr2。请注意，由于未设置 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[...]) 对的最新更新时间。

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，本地商品目录信息最多会保留两天。