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

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. Los siguientes campos de Product se consideran campos de inventario:

• Product.price_info
• Product.availability
• Product.available_quantity
• Product.fulfillment_info

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 mediante 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 disponibles 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

Eliminar 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 con 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á completar el 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

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 eso, 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

Le recomendamos que 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 de algunos lugares específicos puede cambiar, y puede que decida 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 de pedidos del producto.

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

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

  {
    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 una marca de tiempo de AddFulfillmentPlacesRequest.add_time para evitar que las actualizaciones obsoletas anulen el estado de la solicitud de estos IDs de sitio. Estas funciones se describen con más detalle en las secciones siguientes.

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 mediante 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 APIs 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

price_info, availability y available_quantity no se pueden actualizar de forma incremental porque representan el inventario a nivel de producto, en lugar de información a nivel de sitio. Además, puede ser conveniente enviar actualizaciones no incrementales a fulfillment_info en lugar de solo cambios incrementales. En estos casos, se recomienda el método SetInventory.

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

  {
    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 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 las actualizaciones se realicen en un orden incorrecto, cada campo de inventario está asociado a una hora de la ú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 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 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, 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 que ya existan y no se hayan especificado.SetInventoryRequest

Por lo tanto, cuando se procesa el SetInventoryRequest, la actualización fulfillment_info se convierte implícitamente en un AddFulfillmentPlacesRequest y un RemoveFulfillmentPlacesRequest para cada tipo de venta especificado. Esto significa que, si algún sitio "store1" con la opción de tramitación "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".

Precargar información de inventario

Cada uno de los métodos de actualización de inventario permite al llamador definir 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 existiera, de acuerdo con las especificaciones del método.Product La información de inventario se conservará durante un máximo de dos días si el Product correspondiente no se crea a través de CreateProduct en ese plazo.

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 productos, 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

{
  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

{
  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 tiene 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 que toda la información de inventario precargada sea precisa y prefieres definir explícitamente el inventario al crear Product para sincronizar completamente el catálogo y el inventario.

UpdateProduct

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.

{
  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, pero la actualización se aplicará con independencia 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 la marca de tiempo.

Aunque es posible precargar información del inventario mediante UpdateProduct configurando UpdateProductRequest.allow_missing como true para realizar una inserción o actualización Product, el método requiere definir campos de catálogo específicos, como UpdateProductRequest.product.title. Por lo tanto, se recomienda usar 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.