Esta é a documentação do Recommendations AI, da Pesquisa de varejo e do novo Console do Retail.

Atualizar o inventário local da pesquisa de varejo

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_info
  • LocalInventory.attributes
  • LocalInventory.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: substitui LocalInventory.price_info.
  • attributes: substitui todos os LocalInventory.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ários attributes.PLACEHOLDER_NAME, desde que o nome de cada 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 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.