Atualizar o inventário local da Vertex AI para Pesquisa para Retail

LocalInventory são as informações de inventário associadas a um determinado local, identificado por seu place_id. Por exemplo, um LocalInventory pode ser criado para uma loja ou região onde um determinado preço está disponível. LocalInventory tem os seguintes campos:

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

As entradas LocalInventory existentes ficam visíveis em Product.local_inventories, com exceção de fulfillment_types que, para compatibilidade com versões anteriores, está disponível em Product.fulfillment_info. Esse campo é somente de saída. Ambiente Product.local_inventories para Product APIs CRUD ou SetInventory não tem efeito

Cada par de (LocalInventory.place_id, LocalInventory.fulfillment_types[...]) aponta para o mesmo Par (fulfillment_info.place_ids, fulfillment_info.type) mencionado no Documentação de atualização de inventário. fulfillment_types atualizado por AddLocalInventories e RemoveLocalInventories descrito abaixo reflete um mapeamento de cada ID de lugar para uma lista de tipos de fulfillment com suporte. Já fulfillment_info atualizado por AddFulfillmentPlaces e RemoveFulfillmentPlaces reflete um mapeamento de cada tipo de fulfillment específico para uma lista de IDs de lugar que aceita esse tipo. No entanto, os dois tipos de API estão modificando as mesmas informações de preenchimento subjacentes, e o efeito dos dois tipos de API será refletido em Product.fulfillment_info.

Métodos de atualização do inventário local

As mudanças nas informações de inventário local de um produto podem ocorrer com muito mais frequência do que as alterações nas informações de catálogo. Um conjunto especializado de métodos é fornecido para lidar com grandes volumes de atualizações específicas do inventário local. Esses métodos são assíncronos devido a otimizações downstream que oferecer suporte a centenas de atualizações simultâneas por produto, sem sacrificar desempenho.

AddLocalInventories

O AddLocalInventories pode ser usado para criar arquivos inventários em novos locais (representados por novos place_ids) ou atualizam os em inventários locais atuais. Os campos adicionados ou atualizados na lista de entradas LocalInventory no corpo da solicitação podem ser especificados pelo AddLocalInventoriesRequest.add_mask. Os valores de add_mask válidos são:

• price_info: substitui LocalInventory.price_info.
• attributes: substitui todos os LocalInventory.attributes. Os atributos que não forem mencionados no corpo da solicitação serão removidos.
• attributes.PLACEHOLDER_NAME: substitui apenas o atributo personalizado especificado. Se um nome de atributo existente não for fornecido na solicitação, o atributo será excluído. É possível especificar vários attributes.PLACEHOLDER_NAME, desde que cada nome de atributo seja diferente. No entanto, AddLocalInventoriesRequest.add_mask não pode incluir os valores attributes e attributes.PLACEHOLDER_NAME na mesma solicitação.
• fulfillment_types: substitui todos os tipos de fulfillment compatíveis. Os tipos de fulfillment atuais não mencionados no corpo da solicitação são removidos.

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 exemplo adiciona ou atualiza dois inventários locais com os IDs de lugar "store1" e "store2" para o produto especificado. Se store1 existir e store2 não existir antes da solicitação, a solicitação vai atualizar os campos de store1 e criar store2 com os valores de campo fornecidos.

Esse AddLocalInventoriesRequest.add_mask especifica que price_info, um único o atributo personalizado com o nome "attr1", e fulfillment_types deve ser atualizados usando os valores fornecidos no AddLocalInventoriesRequest.local_inventories.

attributes são atributos associados a um lugar com nome e valores personalizáveis. Como LocalInventory de store1 não fornece o valor de attr1 na solicitação, o atributo personalizado attr1 será excluído do existente LocalInventory de store1, se existir. O valor do atributo attr1 de store2 será definido como um valor de texto store2_value. Outros atributos personalizados existentes em store1 e store2 não são alterados.

fulfillment_types representa uma lista de disponibilidade de fulfillment para um Product em um único lugar. Ele é o mesmo e aceita os mesmos valores de fulfillment_info.type. Esse AddLocalInventoriesRequest especifica que store1 oferece suporte aos tipos de atendimento pickup-in-store e ship-to-store, enquanto store1 oferece suporte a custom-type-1. Os tipos de fulfillment que existiam antes desta atualização e não são mencionados na solicitação serão excluídos.

Como AddLocalInventoriesRequest.allow_missing é definido como verdadeiro, mesmo que o produto ainda não existir, as informações do inventário local atualizadas serão armazenados para quando o produto for criado. A atualização é carimbada com um carimbo de data/hora com AddLocalInventoriesRequest.add_time para evitar que atualizações desatualizadas substituam os campos especificados desses IDs de lugar. Para saber mais sobre como prevenir atualizações desatualizadas e o armazenamento de informações do inventário local antes que o produto seja criados, consulte Proteções de carimbo de data/hora para atualizações de inventário local e Pré-carregamento de informações de inventário.

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 exemplo de AddLocalInventoriesRequest adiciona ou atualiza um único local inventário com o ID de lugar "store3" para o produto especificado. Como o add_mask contém "attributes", todos os atributos personalizados de store3 são excluídos e substituídos por attr1 e attr2, conforme especificado na solicitação. Como allow_missing não foi definido, é necessário que o produto especificado existem. Caso contrário, um erro NOT_FOUND será gerado.

RemoveLocalInventories

RemoveLocalInventories pode ser usado para remover inventários locais em lugares com determinados IDs de lugar.

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
}
  

Esta amostra RemoveLocalInventoriesRequest remove inventários locais de lugares com os IDs de lugar "store1" e "store2" do produto especificado. A atualização é carimbada com RemoveLocalInventoriesRequest.remove_time para evitar que as atualizações desatualizadas modifiquem a exclusão desses IDs de lugar. Para IDs de lugar especificados sem inventários locais, a solicitação também registra o tempo de atualização em remove_time. Para saber mais sobre carimbos de data/hora de atualização, consulte Proteções de carimbo de data/hora para atualizações de inventário local

Proteções de carimbo de data/hora para atualizações de inventário local

Para proteger contra atualizações fora de ordem, cada campo de inventário local é associado a um horário de atualização mais recente.

O horário da última atualização é registrado para cada par de (place_id, price_info), (place_id, attributes[...]) e (place_id, fulfillment_types[...]).

Os métodos AddLocalInventories e RemoveLocalInventories permitem que o autor da chamada especifique um horário de atualização para o momento em que a solicitação é emitida. Esse tempo de atualização é comparado com o horário da atualização mais recente registrado para os campos de inventário relevantes, e a atualização será confirmada se e somente se o tempo de atualização for estritamente posterior ao da atualização mais recente.

Por exemplo, suponha que o ID do lugar "store1" tenha price_info com o horário da última atualização registrada definido como T. Se RemoveLocalInventoriesRequest.place_ids contiver "store1", a solicitação vai remover price_info de "store1" somente se o RemoveLocalInventoriesRequest.remove_time for posterior ao horário T. O mesmo vale para RemoveLocalInventoriesRequests.

Com a proteção por carimbo de data/hora, é possível que um RemoveLocalInventoriesRequest remova apenas alguns campos de um LocalInventory, em vez de todos. Suponha que um inventário local com o ID do lugar "store1" tenha price_info com o horário da última atualização registrado definido como T1 e o único atributo personalizado com o nome "attr1" com o horário da última atualização registrado em T2. Se uma RemoveLocalInventoriesRequest.place_ids contiver "store1", e tem remove_time definido como T3 (em que T1 < T3 < T2), então O elemento price_info da store_1 será removido, e o atributo attr1 será removido intocados.

Como pré-carregar informações de inventário

Cada um dos métodos de atualização de inventário local permite que o autor da chamada defina allow_missing na solicitação. Quando allow_missing é definido como verdadeiro, um a atualização do inventário para um Product inexistente é processada como se o Product existe de acordo com as especificações do método. O inventário local serão retidas por, no máximo, dois dias se as operações Product não é criado pelo CreateProduct neste período.