Actualiza el inventario local de Vertex AI Search para comercios

LocalInventory es la información del inventario asociada con un lugar determinado, identificado por su place_id. Por ejemplo, se podría 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 existentes son visibles 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. El parámetro de configuración Product.local_inventories para las APIs de 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 de la actualización del inventario. fulfillment_types, que actualizan AddLocalInventories y RemoveLocalInventories, refleja una asignación de cada ID de lugar a una lista de tipos de entrega que admite, mientras que fulfillment_info, que actualizan 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 cumplimiento 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 nuevos place_id) 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: Sobrescribe 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: Sobrescribe solo 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 y cuando cada nombre de atributo sea diferente. Sin embargo, AddLocalInventoriesRequest.add_mask no puede incluir los valores de attributes y attributes.PLACEHOLDER_NAME en la misma solicitud.
  • fulfillment_types: Anula todos los tipos de cumplimiento admitidos. Se quitan los tipos de cumplimiento 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 lugar "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 proporcionados.

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

attributes son atributos asociados a 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. El atributo 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 a fulfillment_info.type y acepta los mismos valores. Este AddLocalInventoriesRequest especifica que store1 admite los tipos de cumplimiento pickup-in-store y ship-to-store, mientras que store1 admite custom-type-1. Se borrarán los tipos de cumplimiento existentes antes de esta actualización que no se mencionen 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 que se cree el producto, consulta Protecciones de marca de tiempo para actualizaciones de 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
  }
}

Este AddLocalInventoriesRequest de muestra agrega o actualiza un solo inventario local con el ID de lugar "store3" para el producto especificado. Dado que 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 no se configuró allow_missing, se requiere que exista el producto especificado. De lo contrario, se arroja 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 lugar "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 el borrado de estos IDs de lugar. En el caso de los IDs de lugar 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 Protecciones de marca de tiempo para actualizaciones de inventario local.

Protecciones de marca de tiempo para actualizaciones del inventario local

Para protegerte contra las actualizaciones desordenadas, cada campo de inventario local está asociado con una última hora de 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 hora de actualización.

Por ejemplo, supongamos que el ID de lugar "store1" tiene price_info y la última hora de actualización registrada se establece 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.

En la protección de marcas 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á el price_info de store_1, mientras que su atributo attr1 permanecerá intacto.

Carga previa de la información de inventario

Cada uno de los métodos de actualización del 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 con CreateProduct dentro de este período.