A Vertex AI para Pesquisa no varejo vai substituir a plataforma Retail. Estamos atualizando o conteúdo para refletir o novo branding.

Esta página foi traduzida pela API Cloud Translation.

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

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 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 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. A definição de 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 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 de inventário local de um produto podem ocorrer com muito mais frequência do que as alterações 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 suportam centenas de atualizações simultâneas por produto, sem prejudicar o desempenho.

`AddLocalInventories`

AddLocalInventories pode ser usado para criar inventários locais em novos lugares (representados por 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 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 aceitos. 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
}

Este AddLocalInventoriesRequest de exemplo adiciona ou atualiza dois inventários locais com os IDs 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 fornecidos.

Essa 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 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. Ele é o mesmo e aceita os mesmos valores de fulfillment_info.type. Esse AddLocalInventoriesRequest especifica que store1 oferece suporte aos tipos de atendimento 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 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 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 desatualizadas e armazenar informações de inventário local antes que o produto seja criado, 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
  }
}

Este AddLocalInventoriesRequest de exemplo adiciona ou atualiza um único inventário local com o ID de lugar "store3" para o produto especificado. Como o add_mask contém "attributes", todos os atributos personalizados 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
}

Este RemoveLocalInventoriesRequest de amostra remove os inventários locais de lugares com os IDs de lugar "store1" e "store2" para o 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 IDs de lugar especificados sem inventários locais, a solicitação também registra o tempo de atualização em remove_time. Para saber mais sobre os carimbos de data/hora de atualizações, 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 com o horário da última atualização registrada 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.

Com a proteção por 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 o ID do lugar "store1" tenha price_info com o horário da última atualização registrado definido como T1 e o único atributo personalizado com o nome "attr1" com o horário da última atualização registrado em T2. Se um RemoveLocalInventoriesRequest.place_ids contiver "store1" e tiver remove_time definido como T3 (onde T1 < T3 < T2), o price_info de store_1 será removido, enquanto o atributo attr1 será mantido.

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 for definido como verdadeiro, uma atualização de inventário local para um Product inexistente será 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 por CreateProduct dentro desse período.