Atualize o inventário local para o Vertex AI Search for commerce

LocalInventory são as informações de inventário associadas a um determinado local, identificado pelo respetivo place_id. Por exemplo, pode criar um LocalInventory para uma loja ou uma 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 são visíveis através de Product.local_inventories (com exceção de fulfillment_types, que, para retrocompatibilidade, está disponível através de Product.fulfillment_info). Este campo é apenas de saída. A definição Product.local_inventories para as APIs CRUD Product ou SetInventory não tem qualquer 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 reflete um mapeamento de cada ID do local para uma lista de tipos de processamento que suporta, enquanto fulfillment_info atualizado por AddFulfillmentPlaces e RemoveFulfillmentPlaces reflete um mapeamento de cada tipo de processamento específico para uma lista de IDs de locais que suportam esse tipo. No entanto, ambos os tipos de APIs estão a modificar as mesmas informações de processamento subjacentes, e o efeito de ambos os tipos de APIs vai refletir-se em Product.fulfillment_info.

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

As alterações às informações de inventário local de um produto podem ocorrer com muito mais frequência do que as alterações às informações do respetivo catálogo. É disponibilizado um conjunto especializado de métodos para processar grandes volumes de atualizações específicas do inventário local. Estes métodos são assíncronos devido a otimizações posteriores que suportam centenas de atualizações simultâneas por produto, sem sacrificar o desempenho.

AddLocalInventories

AddLocalInventories pode ser usado para criar inventários locais em novos locais (representados com novos place_ids) ou atualizar campos existentes em inventários locais existentes. Os campos adicionados ou atualizados na lista de LocalInventory entradas no corpo do pedido podem ser especificados através de 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 existentes que não são mencionados no corpo do pedido são removidos.
  • attributes.PLACEHOLDER_NAME: substitui apenas o atributo personalizado especificado. Se não for fornecido um nome de atributo existente no pedido, o atributo é eliminado. É 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 o valor attributes e os valores attributes.PLACEHOLDER_NAME no mesmo pedido.
  • fulfillment_types: substitui todos os tipos de processamento suportados. Os tipos de processamento existentes que não são mencionados no corpo do pedido 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 exemplo AddLocalInventoriesRequest adiciona ou atualiza dois inventários locais com os IDs dos estabelecimentos "store1" e "store2" para o produto especificado. Se store1 existir e store2 não existir antes do pedido, o pedido atualiza os campos de store1 e cria store2 com os valores dos campos indicados.

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

attributes são atributos associados a um local com um nome e valores personalizáveis. Uma vez que LocalInventory de store1 não fornece o valor de attr1 no pedido, o atributo personalizado attr1 vai ser eliminado de LocalInventory de store1 existente, se existir. O elemento store2 vai ter o valor do atributo attr1 definido como um valor de texto store2_value. Os outros atributos personalizados existentes em store1 e store2 permanecem inalterados.

fulfillment_types representa uma lista de disponibilidade de processamento para um Product num único local. É igual e aceita os mesmos valores que fulfillment_info.type. Este AddLocalInventoriesRequest especifica que store1 suporta os tipos de processamento pickup-in-store e ship-to-store, enquanto store1 suporta custom-type-1. Os tipos de processamento existentes antes desta atualização que não sejam mencionados no pedido vão ser eliminados.

Uma vez que AddLocalInventoriesRequest.allow_missing está definido como verdadeiro, mesmo que o produto ainda não exista, as informações de inventário local atualizadas são armazenadas para quando o produto for criado. A atualização tem a data/hora de AddLocalInventoriesRequest.add_time para evitar que as atualizações desatualizadas substituam os campos especificados destes IDs de locais. Para saber mais sobre como evitar atualizações desatualizadas e armazenar informações de inventário local antes de o produto ser criado, consulte os artigos Proteções 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 AddLocalInventoriesRequest adiciona ou atualiza um único inventário local com o ID do local "store3" para o produto especificado. Uma vez que o elemento add_mask contém "attributes", todos os atributos personalizados existentes de store3 são eliminados e substituídos por attr1 e attr2, conforme especificado no pedido. Tenha em atenção que, uma vez que allow_missing não está definido, requer que o produto especificado exista. Caso contrário, é gerado um erro NOT_FOUND.

RemoveLocalInventories

O elemento RemoveLocalInventories pode ser usado para remover inventários locais existentes em locais com os IDs de Places indicados.

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 exemplo de RemoveLocalInventoriesRequest remove os inventários locais de locais com os IDs de locais "store1" e "store2" para o produto especificado. A atualização tem a data/hora de RemoveLocalInventoriesRequest.remove_time para evitar que atualizações desatualizadas substituam a eliminação destes IDs de locais. Para IDs de estabelecimentos especificados sem inventários locais existentes, o pedido também regista a respetiva hora de atualização como remove_time. Para saber mais sobre as indicações de tempo de atualização, consulte o artigo Proteções de indicações de tempo para atualizações de inventário local

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

Para se proteger contra atualizações desordenadas, cada campo de inventário local está associado a uma hora de atualização mais recente.

A hora da última atualização é registada para cada par (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 uma hora de atualização para quando o pedido é emitido. Esta hora de atualização é comparada com a hora de atualização mais recente registada para os campos de inventário relevantes, e a atualização é confirmada se e apenas se a hora de atualização for estritamente posterior à hora de atualização mais recente.

Por exemplo, suponha que o ID do estabelecimento "store1" tem price_info com a hora de atualização registada mais recente definida como a hora T. Se RemoveLocalInventoriesRequest.place_ids contiver "store1", a solicitação remove price_info de "store1" apenas se RemoveLocalInventoriesRequest.remove_time for posterior à hora T. O mesmo se aplica aos RemoveLocalInventoriesRequests.

Com a proteção de data/hora, é possível que um RemoveLocalInventoriesRequest remova apenas determinados campos de um LocalInventory em vez de todos. Suponhamos que um inventário local com o ID do local "store1" tem price_info com a hora da última atualização registada definida para a hora T1 e tem o único atributo personalizado existente com o nome "attr1" com a hora da última atualização registada em 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 é removido, enquanto o respetivo atributo attr1 permanece inalterado.

Pré-carregar informações de inventário

Cada um dos métodos de atualização do inventário local permite que o autor da chamada defina allow_missing no pedido. Quando allow_missing está definido como verdadeiro, 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 do inventário local são retidas durante um máximo de dois dias se o Product correspondente não for criado através do CreateProduct dentro deste período.