Actualizar el inventario local de Vertex AI Search para el sector del comercio

LocalInventory es la información de inventario asociada a un lugar determinado, identificado por su place_id. Por ejemplo, se puede crear un LocalInventory para una tienda o una región en la que esté disponible un precio determinado. LocalInventory tiene los siguientes campos:

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

Las entradas de LocalInventory se pueden ver a través de Product.local_inventories (excepto fulfillment_types, que, por motivos de compatibilidad con versiones anteriores, está disponible a través de Product.fulfillment_info). Este campo es de solo salida. El ajuste Product.local_inventories para las APIs CRUD de Product o SetInventory no tiene ningún efecto.

Cada par (LocalInventory.place_id, LocalInventory.fulfillment_types[...]) apunta al mismo par (fulfillment_info.place_ids, fulfillment_info.type) que se menciona en la documentación sobre actualizaciones de inventario. fulfillment_types actualizado por AddLocalInventories y RemoveLocalInventories refleja una asignación de cada ID de sitio a una lista de tipos de venta que admite, mientras que fulfillment_info actualizado por AddFulfillmentPlaces y RemoveFulfillmentPlaces refleja una asignación de cada tipo de venta específico a una lista de IDs de sitio que admite dicho tipo. Sin embargo, ambos tipos de APIs modifican la misma información de cumplimiento subyacente, y el efecto de ambos tipos de APIs se reflejará en Product.fulfillment_info.

Métodos de actualización del inventario local

La información del inventario local de un producto puede cambiar con mucha más frecuencia que la información del catálogo. Se proporciona un conjunto especializado de métodos para gestionar grandes volúmenes de actualizaciones específicas del inventario local. Estos métodos son asíncronos debido a las optimizaciones posteriores que admiten cientos de actualizaciones simultáneas por producto sin sacrificar el rendimiento.

AddLocalInventories

AddLocalInventories se puede usar para crear inventarios locales en sitios nuevos (representados con nuevos place_id) o para actualizar campos de inventarios locales que ya tengas. Los campos que se añaden o actualizan en la lista de entradas LocalInventory del cuerpo de la solicitud se pueden especificar mediante AddLocalInventoriesRequest.add_mask. Los valores add_mask válidos son los siguientes:

  • price_info: sobrescribe LocalInventory.price_info.
  • attributes: sobrescribe todos los LocalInventory.attributes. Se eliminan los atributos que no se mencionan en el cuerpo de la solicitud.
  • attributes.PLACEHOLDER_NAME: sobrescribe solo el atributo personalizado especificado. Si no se proporciona un nombre de atributo en la solicitud, el atributo se elimina. Se pueden especificar varios attributes.PLACEHOLDER_NAME, siempre que cada nombre de atributo sea diferente. Sin embargo, AddLocalInventoriesRequest.add_mask no puede incluir los valores attributes y attributes.PLACEHOLDER_NAME en la misma solicitud.
  • fulfillment_types: sobrescribe todos los tipos de cumplimientos admitidos. Se eliminan los tipos de respuesta que no se mencionan en el cuerpo de la solicitud.

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
}

En este ejemplo, AddLocalInventoriesRequest se añaden o actualizan dos inventarios locales con los IDs de lugar "store1" y "store2" del producto especificado. Si store1 existe y store2 no existía antes de la solicitud, la solicitud actualizará los campos de store1 y creará store2 con los valores de campo proporcionados.

Este AddLocalInventoriesRequest.add_mask especifica que price_info, un atributo personalizado único con el nombre "attr1", y fulfillment_types deben actualizarse con los valores proporcionados en AddLocalInventoriesRequest.local_inventories.

attributes son atributos asociados a un lugar con nombre y valores personalizables. Como LocalInventory de store1 no proporciona el valor de attr1 en la solicitud, el atributo personalizado attr1 se eliminará de LocalInventory de store1 si existe. store2 tendrá el valor del atributo attr1 definido como el valor de texto store2_value. Los demás atributos personalizados de store1 y store2 no se modifican.

fulfillment_types representa una lista de disponibilidad de un Product en un solo lugar. Es igual y acepta los mismos valores que fulfillment_info.type. Este AddLocalInventoriesRequest especifica que store1 admite los tipos de procesamiento pickup-in-store y ship-to-store, mientras que store1 admite custom-type-1. Los tipos de cumplimentación que existían antes de esta actualización y que no se mencionan en la solicitud se eliminarán.

Como AddLocalInventoriesRequest.allow_missing tiene el valor true, aunque el producto aún no exista, la información de inventario local actualizada se almacenará para cuando se cree el producto. La actualización tiene una marca de tiempo AddLocalInventoriesRequest.add_time para evitar que las actualizaciones obsoletas sobrescriban los campos especificados de estos IDs de lugar. Para obtener más información sobre cómo evitar que las actualizaciones se queden obsoletas y cómo almacenar información del inventario local antes de que se cree el producto, consulte los artículos Protecciones de marca de tiempo para las actualizaciones del inventario local y Precarga de información del inventario.

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

En este ejemplo AddLocalInventoriesRequest se añade o se actualiza un solo inventario local con el ID de sitio "store3" del producto especificado. Como add_mask contiene "attributes", se eliminan todos los atributos personalizados de store3 y se sustituyen por attr1 y attr2, tal como se especifica en la solicitud. Ten en cuenta que, como no se ha definido allow_missing, es necesario que el producto especificado exista. De lo contrario, se produce un error NOT_FOUND.

RemoveLocalInventories

RemoveLocalInventories se puede usar para quitar inventarios locales de lugares con IDs de lugar determinados.

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
}

En este ejemplo de RemoveLocalInventoriesRequest se eliminan los inventarios locales de los sitios con los IDs "store1" y "store2" del producto especificado. La actualización tiene la marca de tiempo RemoveLocalInventoriesRequest.remove_time para evitar que las actualizaciones obsoletas anulen la eliminación de estos IDs de lugar. En el caso de los IDs de lugar especificados que no tengan inventarios locales, la solicitud también registra su hora de actualización en remove_time. Para obtener más información sobre las marcas de tiempo de las actualizaciones, consulte Protecciones de marcas de tiempo para las actualizaciones de inventario local.

Protecciones de marca de tiempo para las actualizaciones de inventario local

Para protegerse frente a las actualizaciones desordenadas, cada campo de inventario local está asociado a la hora de la última actualización.

Se registra la hora de la última actualización de cada par (place_id, price_info), (place_id, attributes[...]) y (place_id, fulfillment_types[...]).

Los métodos AddLocalInventories y RemoveLocalInventories permiten al llamador especificar una hora de actualización para cuando se emita la solicitud. Esta hora de actualización se compara con la hora de actualización más reciente registrada en los campos de inventario correspondientes, y la actualización se confirma si y solo si la hora de actualización es posterior a la hora de actualización más reciente.

Por ejemplo, supongamos que el ID de sitio "store1" tiene price_info y que la última hora de actualización registrada es T. Si RemoveLocalInventoriesRequest.place_ids contiene "store1", la solicitud retirará price_info de "store1" solo si RemoveLocalInventoriesRequest.remove_time es posterior a la hora T. Lo mismo ocurre con los RemoveLocalInventoriesRequests.

Con la protección de la marca de tiempo, es posible que un RemoveLocalInventoriesRequest solo quite determinados campos de un LocalInventory en lugar de todos. Supongamos que un inventario local con el ID de sitio "store1" tiene price_info con la última hora de actualización registrada T1 y que su único atributo personalizado es "attr1", cuya última hora de actualización registrada es T2. Si un RemoveLocalInventoriesRequest.place_ids contiene "store1" y tiene remove_time definido como T3 (donde T1 < T3 < T2), se quitará el price_info de store_1, pero su atributo attr1 no se modificará.

Precarga de información de inventario

Cada uno de los métodos de actualización de inventario local permite al llamador definir allow_missing en la solicitud. Si allow_missing tiene el valor true, una actualización de inventario local de un Product que no existe se procesa como si el Product existiera según las especificaciones del método. La información del inventario local se conservará durante un máximo de dos días si el Product correspondiente no se crea con CreateProduct en ese plazo.