LocalInventory são as informações do inventário associadas a um determinado
local, identificadas 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_infoLocalInventory.attributesLocalInventory.fulfillment_types
As entradas LocalInventory existentes são visíveis por meio de Product.local_inventories (exceto fulfillment_types, que, para compatibilidade com versões anteriores, está disponível por meio de Product.fulfillment_info). Esse campo é apenas para saída. Definir
Product.local_inventories para APIs Product CRUD ou SetInventory não tem
efeito.
Cada par de (LocalInventory.place_id,
LocalInventory.fulfillment_types[...]) aponta para o mesmo
par de (fulfillment_info.place_ids, fulfillment_info.type) mencionado na
documentação de atualização de inventário. A fulfillment_types atualizada por AddLocalInventories e RemoveLocalInventories descrita abaixo reflete um mapeamento de cada ID de lugar para uma lista de tipos de fulfillment compatíveis. Já a atualização de fulfillment_info por AddFulfillmentPlaces e RemoveFulfillmentPlaces reflete um mapeamento de cada tipo de fulfillment específico para uma lista de IDs de lugar compatíveis com esse tipo.
No entanto, os dois tipos das APIs estão modificando as mesmas informações de fulfillment
de base, e o efeito dos dois tipos de APIs será refletido em
Product.fulfillment_info.
Métodos de atualização de inventário local
As alterações nas informações do inventário local de um produto podem ocorrer com muito mais frequência do que as alterações nas informações do catálogo. Um conjunto especializado de métodos é fornecido para processar grandes volumes de atualizações específicas do inventário local. Esses métodos são assíncronos devido a otimizações downstream que oferecem suporte a 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 por novos place_ids) ou atualizar campos existentes em inventários locais existentes. Os campos adicionados ou atualizados na lista de entradas LocalInventory no corpo da solicitação podem ser especificados por meio de AddLocalInventoriesRequest.add_mask. Estes são os valores válidos de add_mask:
price_info: substituiLocalInventory.price_info.attributes: substitui todos osLocalInventory.attributes. Os atributos existentes que não são mencionados no corpo da solicitação sã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áriosattributes.PLACEHOLDER_NAME, desde que o nome de cada atributo seja diferente. No entanto,AddLocalInventoriesRequest.add_masknão pode incluir os valoresattributeseattributes.PLACEHOLDER_NAMEna 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
}
Neste exemplo, AddLocalInventoriesRequest adiciona ou atualiza dois inventários locais com os IDs de local "store1" e "store2" para o produto especificado. Se store1 existir e store2 não existir antes da solicitação, a solicitação atualizará os campos de store1 e criará store2 com os valores de campo fornecidos.
Esse AddLocalInventoriesRequest.add_mask especifica que price_info, um único
atributo personalizado com o nome "attr1" e fulfillment_types precisa ser
atualizado usando os valores fornecidos no
AddLocalInventoriesRequest.local_inventories.
attributes são atributos associados a um local 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 de LocalInventory de store1. O valor de atributo attr1 de store2 será definido como um valor de texto store2_value. Outros atributos personalizados existentes em store1 e store2 permanecem intocados.
fulfillment_types representa uma lista de disponibilidade de fulfillment para um
Product em um único lugar. Ele é o mesmo e aceita os mesmos valores que
fulfillment_info.type. Esse AddLocalInventoriesRequest especifica que
store1 é compatível com os tipos de fulfillment pickup-in-store e ship-to-store, enquanto
store1 é compatível com custom-type-1. Os tipos de fulfillment existentes antes dessa atualização
que não são 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 quando o produto for criado. A atualização tem 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 evitar
atualizações obsoletas 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
Como pré-carregar 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 AddLocalInventoriesRequest adiciona ou atualiza um único inventário local com ID de lugar "store3" para o produto especificado. Como o
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, ele exige que o produto especificado exista. Caso contrário, um erro NOT_FOUND será gerado.
RemoveLocalInventories
RemoveLocalInventories pode ser usado para remover inventários locais existentes em locais com determinados IDs de local.
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 inventários locais de locais com os IDs "store1" e "store2" do produto especificado. A atualização recebe um carimbo de data/hora 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 existentes, a solicitação também registra o tempo de atualização deles 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 por 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 está associado a um horário de atualização mais recente.
O horário da atualização mais recente é 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 quando a solicitação for emitida. Esse tempo de atualização é
comparado com o horário de atualização mais recente registrado para os campos de inventário
relevantes. A atualização será confirmada se e somente se o horário da atualização for estritamente
após o horário da atualização mais recente.
Por exemplo, suponha que o ID do lugar "store1" tenha price_info com a hora da última atualização registrada como a hora T. Se RemoveLocalInventoriesRequest.place_ids contiver "store1", a solicitação removerá price_info de "store1" somente se RemoveLocalInventoriesRequest.remove_time for posterior a T.
O mesmo vale para RemoveLocalInventoriesRequests.
Na proteção do carimbo de data/hora, é possível que uma
RemoveLocalInventoriesRequest remova apenas determinados campos de um
LocalInventory, em vez de todos eles Suponha que um inventário local com ID de lugar "store1" tenha price_info com o horário da última atualização definido como T1 e tenha o único atributo personalizado atual com o nome "attr1" com o horário da última atualização registrada 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 será removido, mas o atributo attr1 não
será modificado.
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, uma atualização de inventário local para uma Product não existente é processada como se a Product existisse de acordo com as especificações do método. As informações do inventário local serão retidas por no máximo dois dias se o Product correspondente não for criado por meio de CreateProduct nesse período.