Actualiza el inventario local para Vertex AI Search para la venta minorista

LocalInventory es la información del inventario asociada con un lugar determinado, que se identifica por su place_id. Por ejemplo, se podría crear un LocalInventory para una tienda o una región donde está disponible un precio determinado. LocalInventory tiene los siguientes campos:

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

Las entradas LocalInventory existentes se pueden ver a través de Product.local_inventories (con la excepción de fulfillment_types que, para la retrocompatibilidad, está disponible a través de Product.fulfillment_info). Este campo es solo de salida. No se recomienda configurar Product.local_inventories para las APIs de CRUD de Product o SetInventory.

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 de actualización del inventario. fulfillment_types actualizado por AddLocalInventories y RemoveLocalInventories que se describe a continuación refleja una asignación de cada ID de lugar a una lista de tipos de entrega que admite, mientras que fulfillment_info actualizado por AddFulfillmentPlaces y RemoveFulfillmentPlaces refleja una asignación de cada tipo de entrega específico a una lista de IDs de lugar que admite ese tipo. Sin embargo, ambos tipos de APIs modifican la misma información de entrega subyacente, y el efecto de ambos tipos de APIs se reflejará en Product.fulfillment_info.

Métodos de actualización del inventario local

Los cambios en la información del inventario local de un producto pueden ocurrir con mucha más frecuencia que los cambios en la información de su catálogo. Se proporciona un conjunto especializado de métodos para controlar 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 lugares nuevos (representados con place_id nuevos) o actualizar campos existentes en inventarios locales existentes. Los campos que se agregan o actualizan en la lista de entradas de LocalInventory en el cuerpo de la solicitud se pueden especificar a través de AddLocalInventoriesRequest.add_mask. Estos son los valores válidos de add_mask:

• price_info: reemplaza LocalInventory.price_info.
• attributes: Reemplaza todos los LocalInventory.attributes. Se quitan los atributos existentes que no se mencionan en el cuerpo de la solicitud.
• attributes.PLACEHOLDER_NAME: Solo reemplaza el atributo personalizado especificado. Si no se proporciona un nombre de atributo existente en la solicitud, se borrará el atributo. Se pueden especificar varios attributes.PLACEHOLDER_NAME, siempre que cada nombre de atributo sea diferente. Sin embargo, AddLocalInventoriesRequest.add_mask no puede incluir el valor attributes y los valores attributes.PLACEHOLDER_NAME en la misma solicitud.
• fulfillment_types: Reemplaza todos los tipos de entrega admitidos. Se quitan los tipos de entrega existentes 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
}
  

Este AddLocalInventoriesRequest de muestra agrega o actualiza dos inventarios locales con los IDs de lugares "store1" y "store2" para el producto especificado. Si store1 existe y store2 no existe antes de la solicitud, la solicitud actualizará los campos de store1 y creará store2 con los valores de campo determinados.

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

attributes son atributos asociados con un lugar con nombre y valores personalizables. Dado que LocalInventory de store1 no proporciona el valor de attr1 en la solicitud, el atributo personalizado attr1 se borrará del LocalInventory existente de store1 si existe. store2 tendrá el valor de su atributo attr1 establecido en un valor de texto store2_value. Los demás atributos personalizados existentes en store1 y store2 no se modifican.

fulfillment_types representa una lista de disponibilidad de entrega para 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 entrega pickup-in-store y ship-to-store, mientras que store1 admite custom-type-1. Se borrarán los tipos de entrega que existían antes de esta actualización y que no se mencionan en la solicitud.

Dado que AddLocalInventoriesRequest.allow_missing se establece como verdadero, incluso si el producto aún no existe, la información del inventario local actualizada se almacenará cuando se cree el producto. La actualización tiene una marca de tiempo con AddLocalInventoriesRequest.add_time para evitar que las actualizaciones inactivas anulen los campos especificados de estos IDs de lugar. Para obtener más información sobre cómo evitar actualizaciones obsoletas y almacenar información del inventario local antes de crear el producto, consulta Protección de marcas de tiempo para actualizaciones de inventario local y Carga información del inventario previamente.

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

Este AddLocalInventoriesRequest de muestra agrega o actualiza un solo inventario local con el ID de lugar "store3" para el producto especificado. Como su add_mask contiene "attributes", se borran todos los atributos personalizados existentes de store3 y se reemplazan por attr1 y attr2, como se especifica en la solicitud. Ten en cuenta que, como allow_missing no está configurado, requiere que exista el producto especificado. De lo contrario, se genera un error NOT_FOUND.

RemoveLocalInventories

RemoveLocalInventories se puede usar para quitar los inventarios locales existentes en 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
}
  

Este RemoveLocalInventoriesRequest de muestra quita los inventarios locales de los lugares con los IDs de lugares "store1" y "store2" para el producto especificado. La actualización tiene una marca de tiempo con RemoveLocalInventoriesRequest.remove_time para evitar que las actualizaciones inactivas anulen la eliminación de estos IDs de lugar. En el caso de los IDs de lugares especificados sin inventarios locales existentes, 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 actualización, consulta Protección de marcas de tiempo para actualizaciones de inventario local.

Protecciones de marca de tiempo para actualizaciones de inventario local

Para protegerte contra las actualizaciones desordenadas, cada campo de inventario local está asociado con una última actualización.

Se registra la hora de actualización más reciente de cada par de (place_id, price_info), (place_id, attributes[...]) y (place_id, fulfillment_types[...]).

Los métodos AddLocalInventories y RemoveLocalInventories permiten que el emisor especifique una hora de actualización cuando se emite la solicitud. Esta hora de actualización se compara con la última hora de actualización registrada para los campos de inventario relevantes y la actualización se confirma solo si la hora de actualización es posterior a la última actualización.

Por ejemplo, supongamos que el ID de lugar "store1" tiene price_info con la última hora de actualización registrada establecida en la hora T. Si RemoveLocalInventoriesRequest.place_ids contiene "store1", la solicitud quitará price_info de "store1" solo si RemoveLocalInventoriesRequest.remove_time es posterior a la hora T. Lo mismo sucede con los RemoveLocalInventoriesRequest.

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

Carga previa de la información de inventario

Cada uno de los métodos de actualización de inventario local permite que el emisor configure allow_missing en la solicitud. Cuando allow_missing se establece como verdadero, una actualización del inventario local a un Product inexistente 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 a través de CreateProduct dentro de este período.