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

En esta página se describen los métodos para gestionar las actualizaciones de precios y cantidades en tiempo real del catálogo de Vertex AI Search for commerce mediante la API Retail.

Aunque los métodos de creación, lectura, actualización y eliminación (CRUD) de Product se usan para modificar de forma general los atributos de un Product, hay un conjunto de métodos de Product que se pueden usar para actualizar campos específicos del inventario con distintos niveles de granularidad.

Información sobre el inventario

Por lo general, el inventario hace referencia a los niveles de stock (cantidad) y al precio de los artículos de un sitio de comercio electrónico. En la API Retail, inventory hace referencia al precio, la disponibilidad, la cantidad disponible, la información de envío y los precios locales, así como a otros atributos locales. Estos campos se definen en el esquema Product con los siguientes campos:

Inventario a nivel de producto

En el caso de los comerciantes con un sitio de comercio electrónico que solo tengan un catálogo online, inventory suele representarse como los productos del catálogo. El precio, la disponibilidad y el resto de los datos se definen en cada entrada de Producto del catálogo. Los campos fulfillmentInfo y localInventories no se utilizan.

Inventario local

En el caso de los comercios que tienen varias ubicaciones, los productos siguen representándose mediante las entradas de producto del catálogo, pero se puede añadir inventario local (precio, disponibilidad y tramitación) a las ubicaciones (placeId) de un producto con el método addLocalInventories.

Hay dos campos de producto independientes que se usan para el inventario local: Product.fulfillmentInfo y Product.localInventories. Se pueden usar una o ambas, en función de los requisitos. Tanto fulfillmentInfo como localInventories son listas de ubicaciones con datos asociados.

fulfillmentInfo especifica cómo se gestiona el pedido de un producto en una ubicación concreta, mientras que localInventories especifica el precio y otros atributos personalizados de cada ubicación.

Para marcar un producto como agotado o no disponible en una ubicación concreta, se usa el método removeLocalInventories para quitar los atributos fulfillment y inventory de un producto en un placeId concreto.

Métodos de actualización de inventario

Los cambios en la información del inventario de un producto pueden producirse con mucha más frecuencia que los cambios en la información de su catálogo. Por este motivo, se proporciona un conjunto especializado de métodos para gestionar grandes volúmenes de actualizaciones específicas del inventario. Estos métodos son asíncronos debido a las optimizaciones posteriores que admiten cientos de actualizaciones simultáneas por producto sin sacrificar el rendimiento.

Actualizaciones incrementales

Siga la guía de actualizaciones de inventario local para publicar actualizaciones de inventario incrementales. Los métodos de API más recientes ofrecen un control más detallado de los atributos de inventario por sitio.

fulfillment_info se suele usar para codificar la disponibilidad de la gestión a nivel de sitio de un Product. En algunos casos, la disponibilidad de la tramitación de pedidos en determinados lugares puede cambiar. Puede decidir publicar actualizaciones que describan este cambio en lugar de usar el método UpdateProduct para volver a especificar toda la información de tramitación del pedido del producto.

En estos casos, se pueden usar los métodos AddFulfillmentPlaces y RemoveFulfillmentPlaces para actualizar de forma incremental los cambios en el cumplimiento de un producto en función de los IDs de lugar que se añadan o se quiten para un tipo de cumplimiento concreto.

Java

Para saber cómo instalar y usar la biblioteca de cliente de Vertex AI Search for commerce, consulta el artículo sobre las bibliotecas de cliente de Vertex AI Search for commerce. Para obtener más información, consulta la documentación de referencia de la API Vertex AI Search for commerce Java.

Para autenticarte en Vertex AI Search for commerce, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local. 

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
  }

En este ejemplo, AddFulfillmentPlacesRequest añade el tipo de envío "pickup-in-store" a los IDs de lugar "store0" y "store1" del producto especificado. Como AddFulfillmentPlacesRequest.allow_missing tiene el valor true, aunque el producto no exista, la información de inventario actualizada se almacenará para cuando se cree el producto. La actualización tiene la marca de tiempo AddFulfillmentPlacesRequest.add_time para evitar que las actualizaciones obsoletas anulen el estado de la solicitud de estos IDs de lugar. Estas funciones se describen con más detalle en las siguientes secciones.

El comportamiento es idéntico para RemoveFulfillmentPlacesRequest y el esquema es muy similar.

Cuando fulfillment_types se actualiza por AddLocalInventories y RemoveLocalInventories, refleja una asignación de cada ID de lugar a una lista de tipos de respuesta que admite. Cuando fulfillment_info se actualiza con AddFulfillmentPlaces y RemoveFulfillmentPlaces, refleja una asignación de cada tipo de venta específico a una lista de IDs de lugar que admite cada tipo. Ambos tipos de API modifican la misma información de cumplimiento subyacente y el efecto de ambos tipos de APIs se refleja en Product.fulfillment_info.

Actualizaciones no incrementales

Los métodos price_info, availability y available_quantity no se pueden actualizar de forma incremental porque representan el inventario a nivel de producto, no la información a nivel de lugar. También puede ser recomendable publicar actualizaciones no incrementales de fulfillment_info. En lugar de hacer solo cambios incrementales, te recomendamos que uses SetInventory.

El método setInventory es la forma preferida de actualizar el precio, la disponibilidad y la cantidad a nivel de producto cuando se requieren muchas actualizaciones frecuentes. El método setInventory es asíncrono, por lo que las actualizaciones pueden no producirse inmediatamente. La cuota predeterminada (300.000 solicitudes por minuto) admite muchas más solicitudes que UpdateProduct.

Además, el método setInventory se usa para las actualizaciones de la respuesta local cuando se incluye fulfillmentInfo en la solicitud, pero no puede actualizar los campos localInventories. Para esos atributos, usa los métodos addLocalInventories y removeLocalInventories.

El inventario local se guarda a nivel de tienda, independientemente del catálogo. En el caso de los clientes que tienen inventario online y offline, el catálogo de productos principal se puede usar para el inventario online o se puede usar un placeId específico (-1 o online, por ejemplo) para representar el inventario online. Sin embargo, utilice el catálogo principal para el inventario online, ya que los campos de inventario de productos deben rellenarse con valores priceInfo y availability válidos. Si se usa un placeId de inventario independiente para los productos online, la información principal del catálogo sobre el precio y la disponibilidad también debe estar actualizada. Para obtener más información sobre las actualizaciones de inventario local, consulte el artículo Actualizar el inventario local.

Java

Para saber cómo instalar y usar la biblioteca de cliente de Vertex AI Search for commerce, consulta el artículo sobre las bibliotecas de cliente de Vertex AI Search for commerce. Para obtener más información, consulta la documentación de referencia de la API Vertex AI Search for commerce Java.

Para autenticarte en Vertex AI Search for commerce, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo local. 

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
  }

En esta solicitud concreta, los SetInventoryRequest.product.fulfillment_info campos son descripciones completas de los IDs de lugar aptos de cada tipo de respuesta, en lugar de especificaciones incrementales. La actualización de "same-day-delivery" indica que ningún ID de sitio cumple los requisitos de este tipo de envío para este producto. El resto de los tipos de cumplimentación no se actualizan en esta solicitud. Por lo tanto, este método se puede usar para sustituir los IDs de sitio de solo un subconjunto de tipos de cumplimientos y dejar los demás tipos sin modificar.

De forma predeterminada,SetInventory actualizará todos los campos del inventario si SetInventory.set_mask no se ha definido o está vacío. Si la máscara no está vacía o si un campo de inventario no aparece explícitamente en SetInventoryRequest.set_mask, se ignorará cualquier valor especificado para ese campo de inventario en la solicitud de actualización.

Al igual que con las actualizaciones incrementales, el campo SetInventoryRequest.set_time se puede usar para definir una hora de actualización que se comparará con la última hora de actualización registrada de todos los campos de inventario actualizados.

Protecciones de marca de tiempo para las actualizaciones de inventario

Hay varias formas de actualizar los campos de inventario de un producto y, para evitar que se produzcan actualizaciones desordenadas, cada campo de inventario está asociado a una hora de última actualización.

La hora de la última actualización se registra para price_info, availability, available_quantity y cada par de (fulfillment_info.place_ids, fulfillment_info.type).

Los métodos AddFulfillmentPlaces, RemoveFulfillmentPlaces y SetInventory permiten que la persona que llama especifique 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 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 habilitado el tipo de respuesta "pickup-in- store" y que la última hora de actualización registrada es T. Si RemoveFulfillmentPlacesRequest.type = "pickup-in-store" y RemoveFulfillmentPlacesRequest.place_ids contienen "store1", la solicitud borrará "pickup-in-store" de "store1" solo si RemoveFulfillmentPlacesRequest.remove_time es posterior a la hora T. Lo mismo ocurre con AddFulfillmentPlacesRequests.

SetInventory funciona de forma similar para actualizar price_info, availability y available_quantity. Al actualizar fulfillment_info, a SetInventoryRequest se pide implícitamente que se añadan todos los IDs de sitio especificados para un tipo de respuesta determinado y que se eliminen todos los IDs de sitio existentes que no se hayan especificado.

Cuando se procesa el SetInventoryRequest, la actualización del fulfillment_info se convierte implícitamente en un AddFulfillmentPlacesRequest y un RemoveFulfillmentPlacesRequest para cada tipo de venta especificado. Esto significa que, si algún lugar "store1" con entrega "pickup-in-store" tiene una hora de última actualización T más reciente que SetInventoryRequest.set_time, no se aplicará la adición o eliminación implícita en "store1" y "pickup-in-store".

Atributos de precarga

setInventory es asíncrono, lo que significa que no se aplican controles taxonómicos ni referenciales al añadir o modificar campos de inventario. Este método no requiere que el producto al que se hace referencia en la solicitud ya exista.

De esta forma, los clientes pueden implementar patrones de precarga, lo que permite desacoplar la gestión de los campos de inventario del catálogo principal o del proceso de importación de productos. Por ejemplo, los usuarios pueden importar el contexto de disponibilidad o de precio antes de importar el producto asociado.

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

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

Cuándo usar los métodos Product

Aunque es posible actualizar los campos de inventario con los métodos CRUD de producto, el llamante debe ser consciente de los efectos en la información de inventario actual o anterior.

Estos son métodos síncronos, lo que significa que las optimizaciones de nivel inferior que se usan para los métodos de inventario no se aplican y puede resultar caro depender de estos métodos para actualizar el inventario con frecuencia. Siempre que sea posible, utilice los métodos de actualización de inventario mencionados anteriormente.

CreateProduct

Cuando se invoca CreateProduct con algún campo de inventario definido, los valores proporcionados en CreateProductRequest.product anularán los valores precargados de esos campos. Si no se define ningún campo de inventario, se usará automáticamente la información de inventario que ya exista.

Además, la hora de la última actualización de los campos de inventario anulados se restablecerá a la hora de la llamada al método.

CreateProduct con inventario precargado

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

En este ejemplo, el producto creado no tiene ningún campo de inventario definido, lo que significa que se utilizará automáticamente cualquier información de inventario precargada si se actualiza mediante los métodos de actualización de inventario. Esto puede ser útil cuando las actualizaciones de inventario se desacoplan de las actualizaciones de catálogo y quieres que un Product recién creado se sincronice con la información de inventario que ya tengas.

CreateProduct con inventario explícito

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

En este ejemplo, se crea un Product con campos de inventario definidos explícitamente. Estos campos sobrescribirán los valores que ya existan y se ignorará la hora de la última actualización de los campos correspondientes. Por lo tanto, el Product recién creado tendrá la disponibilidad definida como OUT_OF_STOCK y ningún ID de sitio admitirá los tipos de respuesta "pickup-in-store" y "same-day-delivery".

CreateProduct con información de inventario puede ser útil si no estás seguro de si toda la información de inventario precargada es precisa y prefieres definir explícitamente el inventario al crear Product para sincronizar completamente el catálogo y el inventario.

UpdateProduct

El método UpdateProduct se puede usar para actualizar atributos específicos de un elemento de catálogo. Puede hacerlo con uno o varios campos a la vez, y con productos concretos o con varios productos mediante el método de importación. Si usas el método de importación sin la máscara, se sobrescribirán los datos.

UpdateProduct se suele usar para actualizar el precio y la disponibilidad en tiempo real, pero se puede usar para actualizar cualquier campo sin tener que volver a enviar todos los datos de un producto. (a diferencia de createMethod o importProducts).

La principal ventaja de usar UpdateProduct es que se trata de una solicitud síncrona. Las actualizaciones del índice (y de la búsqueda o las recomendaciones) son casi instantáneas. Sin embargo, UpdateProduct no se ha diseñado para usarse en actualizaciones muy frecuentes. La cuota predeterminada es de 12.000 solicitudes de escritura de productos por minuto. Por lo general, solo debes usar este método cuando cambie el precio de un artículo o si cambia el estado del stock (no para cada disminución de la cantidad).

UpdateProduct solo puede modificar los atributos a nivel de producto. No se puede usar para modificar ninguno de los atributos de inventario local de localInventories ni de fulfillmentInfo.

Cuando hagas una llamada con UpdateProduct o ImportProducts, es importante que especifiques el parámetro updateMask. updateMask contiene una lista de los campos que se van a actualizar. Solo se actualizarán los campos especificados en updateMask, aunque se incluyan más campos en el cuerpo de la solicitud. Si no se incluye ningún updateMask en una solicitud de actualización o importación, todos los campos se actualizarán exactamente con lo que se envíe en el cuerpo de la solicitud.

Cuando se invoca UpdateProduct y la máscara de campo UpdateProductRequest.update_mask contiene campos de inventario, los valores proporcionados en UpdateProductRequest.product anularán los valores precargados de esos campos.

Además, la hora de la última actualización de los campos de inventario anulados se restablecerá a la hora de la llamada al método.

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

Este ejemplo es muy similar al ejemplo de SetInventory, excepto que la actualización se aplica independientemente de la hora de la última actualización de cada campo de inventario.

  • UpdateProduct para el inventario puede ser útil cuando se necesita una sincronización completa del inventario sin tener en cuenta las protecciones de marca de tiempo.

  • Si asigna el valor UpdateProductRequest.allow_missing a true para realizar una Product inserción o actualización, puede precargar información de inventario mediante UpdateProduct. Para usar este método, debes definir campos de catálogo específicos, como UpdateProductRequest.product.title. Por lo tanto, utilice los métodos de actualización de inventario para los casos prácticos de precarga.

DeleteProduct

Cuando se invoca DeleteProduct, se elimina toda la información de inventario del producto especificado en DeleteProductRequest.name, incluidos todos los registros de la hora de la última actualización de cada campo de inventario.

Consideraciones si sustituye los atributos a nivel de producto por atributos a nivel de inventario

Tenga en cuenta las siguientes consideraciones y limitaciones asociadas a cada enfoque:

Función Inventario a nivel de producto Inventario a nivel de tienda (local)
Controles de filtro de búsqueda y de aumento Sí Sí
Formato de clave de filtro y de facetado especificado en facetSpec Sí No
Disponible para las facetas de búsqueda Sí No
Devuelto en la respuesta de búsqueda Sí Sí (con variantRollupKeys)
Filtros y controles de refuerzo de Recommendations AI v2 Sí No
Función Inventario a nivel de producto Inventario a nivel de tienda (local)
Controles de filtro de búsqueda y de aumento
Formato de clave de filtro y de facetado especificado en facetSpec
Disponible para las facetas de búsqueda
Devuelto en la respuesta de búsqueda (con variantRollupKeys)
Filtros y controles de refuerzo de Recommendations AI v2

Las funcionalidades de los diferentes métodos para actualizar la disponibilidad, la gestión y el precio local de los productos se solapan en algunos aspectos:

Función UpdateProduct setInventory addLocalInventories
Actualizaciones en tiempo real
Actualizar los campos de producto
Actualizar el precio de un producto
Actualizar la disponibilidad de los productos
Actualizar fulfillmentInfo
Actualización localInventories (precios locales)
Secuenciación de marcas de tiempo

Ejemplos

En esta sección se muestra cómo actualizar el inventario de productos mediante los métodos UpdateProduct y setInventory en comandos curl.

  • UpdateProduct usa el método HTTP PATCH de la API REST para actualizar de forma síncrona y en tiempo real los campos a nivel de producto, como el precio y la disponibilidad. También se puede usar para hacer actualizaciones en lote mediante el método import con un updateMask.

  • Se muestra el método asíncrono setInventory para actualizar los campos de inventario a nivel de producto (precio, disponibilidad y cantidad) y los detalles de tramitación local mediante fulfillmentInfo, pero no puede modificar los precios locales ni los atributos almacenados en localInventories.

Usar UpdateProduct para actualizar el precio y la disponibilidad de los productos

Cuando se usa la API REST, UpdateProduct usa el método HTTP PATCH. La misma URL de endpoint que CreateProduct, GetProduct y DeleteProduct usa los métodos HTTP PUT, GET y DELETE, respectivamente. Despliega los siguientes enlaces para ver las muestras de curl correspondientes.

Usar setInventory para actualizar el precio y la disponibilidad de los productos

setInventory solo admite los siguientes campos:

  • availability
  • availableQuantity
  • priceInfo

Despliega los siguientes enlaces para ver las muestras de curl correspondientes.

En el caso del inventario local, los tipos de placeIds y de envío se pueden incluir en fulfillmentInfo, como se muestra en este ejemplo de curl:

.

Tutoriales

Sigue estos tutoriales para saber cómo usar setInventory o para añadir o quitar cumplimientos.

Tutorial para definir el inventario

En este tutorial se muestra cómo enviar actualizaciones de inventario con el método SetInventory en lugar de actualizar todo el producto.

Para seguir las instrucciones paso a paso de esta tarea directamente en el editor de Cloud Shell, haz clic en Ayúdame:

Guíame

Añadir tutorial de finalización

Te recomendamos que uses el método AddLocalInventories en lugar de AddFulfillmentPlaces. AddLocalInventories consigue los mismos resultados, pero ofrece un control más detallado sobre la ingesta de datos de inventario local. Para obtener más información, consulta la documentación de AddLocalInventories.

En este tutorial se explica cómo actualizar la información de tramitación de pedidos de productos con el método AddFulfillmentPlaces. De esta forma, la Búsqueda puede mostrar actualizaciones sobre la disponibilidad de los productos y se pueden completar los pedidos. Por ejemplo, un comprador está buscando unos vaqueros azules en una tienda, pero no hay existencias. En el momento en que los vaqueros vuelvan a estar en stock en esta tienda o en cualquier otra, el comprador verá las actualizaciones y podrá completar su pedido.

Para seguir las instrucciones paso a paso de esta tarea directamente en el editor de Cloud Shell, haz clic en Ayúdame:

Guíame

Quitar tutorial sobre la gestión de pedidos

Te recomendamos que uses el método RemoveLocalInventories en lugar de RemoveFulfillmentPlaces. RmoveLocalInventories consigue los mismos resultados, pero ofrece un control más detallado sobre la ingesta de datos de inventario local. Para obtener más información, consulta la documentación de RemoveLocalInventories.

En este tutorial se explica cómo actualizar la información de tramitación de pedidos de productos mediante el método RemoveFulfillmentPlaces. De esta forma, Vertex AI Search para el sector del comercio puede mostrar actualizaciones cuando los productos no estén disponibles y no se puedan completar los pedidos. De esta forma, la Búsqueda puede mostrar actualizaciones cuando los productos no estén disponibles y no se puedan completar los pedidos. Por ejemplo, un comprador está buscando unos vaqueros azules en una tienda. Si los vaqueros se agotan en esta tienda, el cliente lo verá y no podrá continuar con su pedido.

Para seguir las instrucciones paso a paso de esta tarea directamente en el editor de Cloud Shell, haz clic en Ayúdame:

Guíame