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 lugar, identificadas pelo 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 (LocalInventory.place_id, LocalInventory.fulfillment_types[...]) aponta para o mesmo par (fulfillment_info.place_ids, fulfillment_info.type) mencionado na documentação de atualização do 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 de inventário local

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

AddLocalInventories

AddLocalInventories pode ser usado para criar arquivos locais 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 válidos de add_mask 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 o nome de um atributo existente não for fornecido na solicitação, ele será excluído. Vários attributes.PLACEHOLDER_NAME podem ser especificados, desde que cada nome de atributo seja diferente. No entanto, AddLocalInventoriesRequest.add_mask não pode incluir o valor attributes e os valores 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 amostra adiciona ou atualiza dois inventários locais com os IDs de lugar "store1" e "store2" do 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 personalizável e valores. 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. É igual e aceita os mesmos valores que fulfillment_info.type: Esse AddLocalInventoriesRequest especifica que store1 oferece suporte aos tipos de fulfillment 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 forem 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 AddLocalInventoriesRequest.add_time para evitar que atualizações desatualizadas modifiquem 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 é add_mask contém "attributes", todos os atributos personalizados existentes de store3 são excluídos e substituídos por attr1 e attr2, conforme especificado na solicitação. Como allow_missing não está definido, o produto especificado precisa existir. 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 especificações IDs de lugar sem inventários locais, a solicitação também registra Atualizar o horário para 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 evitar atualizações fora de ordem, cada campo de inventário local é associadas ao horário da 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 permite que o autor da chamada especificar um horário de atualização para quando a solicitação for 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 de lugar "store1" tenha price_info com o último registro registrado o horário de atualização 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.

Na proteção de carimbo de data/hora, é possível RemoveLocalInventoriesRequest pode remover apenas alguns campos de um LocalInventory ao invés de tudo. Suponha que um inventário local com ID de lugar "store1" está com o horário price_info, e o horário da última atualização registrado foi definido como T1 e tem apenas o único atributo personalizado existente chamado "attr1" com o último registro registrado Horário da atualização às 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. As informações de inventário local serão retidas por no máximo dois dias se o Product correspondente não for criado por CreateProduct dentro desse período.