Atualizar o inventário local para a Vertex AI para Pesquisa para Commerce

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

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

As entradas LocalInventory atuais ficam visíveis em Product.local_inventories, exceto fulfillment_types, que, para compatibilidade com versões anteriores, está disponível em Product.fulfillment_info. Este campo é somente saída. Definir Product.local_inventories para APIs CRUD Product 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 de inventário. fulfillment_types atualizado por AddLocalInventories e RemoveLocalInventories reflete um mapeamento de cada ID de lugar para uma lista de tipos de fulfillment que ele aceita, enquanto 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 aceitam esse tipo. No entanto, os dois tipos de APIs modificam as mesmas informações de atendimento subjacentes, e o efeito de ambos os tipos de APIs será refletido em Product.fulfillment_info.

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

Alterações nas informações de inventário local de um produto podem ocorrer com muito mais frequência do que as mudanças 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 comportam centenas de atualizações simultâneas por produto sem prejudicar o desempenho.

AddLocalInventories

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

  • price_info: substitui LocalInventory.price_info.
  • attributes: substitui todos os LocalInventory.attributes. Os atributos atuais 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 não for fornecido na solicitação, o atributo 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 que não sã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
}

Esta amostra de AddLocalInventoriesRequest adiciona ou atualiza dois inventários locais com os códigos 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 especificados.

Esse AddLocalInventoriesRequest.add_mask especifica que price_info, um único atributo personalizado com o nome "attr1" e fulfillment_types precisam 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 LocalInventory de store1 se ele existir. O atributo attr1 de store2 será definido como um valor de texto store2_value. Outros atributos personalizados em store1 e store2 não são alterados.

fulfillment_types representa uma lista de disponibilidade de fulfillment para um Product em um único local. É igual e aceita os mesmos valores que fulfillment_info.type. Este AddLocalInventoriesRequest especifica que store1 é compatível com os tipos de atendimento pickup-in-store e ship-to-store, enquanto store1 é compatível com custom-type-1. Os tipos de fulfillment que existiam antes dessa atualização e não forem mencionados na solicitação serão excluídos.

Como AddLocalInventoriesRequest.allow_missing está definido como verdadeiro, mesmo que o produto ainda não exista, as informações atualizadas do inventário local serão armazenadas para quando o produto for criado. A atualização é carimbada com AddLocalInventoriesRequest.add_time para evitar que atualizações desatualizadas substituam os campos especificados desses IDs de lugar. Para saber mais sobre como evitar atualizações desatualizadas e armazenar informações de inventário local antes da criação do produto, 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
  }
}

Esta amostra de AddLocalInventoriesRequest adiciona ou atualiza um único inventário local com o ID do lugar "store3" para o produto especificado. Como o add_mask dele contém "attributes", todos os atributos personalizados atuais 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 de RemoveLocalInventoriesRequest remove os inventários locais de lugares com os códigos "store1" e "store2" do produto especificado. A atualização é carimbada com RemoveLocalInventoriesRequest.remove_time para evitar que atualizações desatualizadas substituam a exclusão desses IDs de lugar. Para IDs de lugar especificados sem inventários locais, a solicitação também registra o horário de atualização como remove_time. Para mais informações 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 e o horário da última atualização registrado tenha sido 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 que um RemoveLocalInventoriesRequest remova apenas alguns campos de um LocalInventory em vez de todos. Suponha que um inventário local com ID do lugar "store1" tenha price_info com o horário da última atualização registrado definido como T1 e tenha o único atributo personalizado com o nome "attr1" e o horário da última atualização registrado como T2. Se um RemoveLocalInventoriesRequest.place_ids contiver "store1" e tiver remove_time definido como T3 (em que T1 < T3 < T2), o price_info de store_1 será removido, enquanto o atributo attr1 permanecerá inalterado.

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 "true", uma atualização de inventário local para um Product inexistente é processada como se o Product existisse 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 usando CreateProduct dentro desse período.