Atualizar o inventário da Vertex AI para Pesquisa para Commerce

Nesta página, descrevemos os métodos para gerenciar atualizações de preço e quantidade em tempo real para o catálogo da Vertex AI Search for commerce usando a API Retail.

Embora os métodos de criação, leitura, atualização e exclusão (CRUD, na sigla em inglês) Product sejam usados para modificar amplamente os atributos de um Product, há um conjunto de métodos Product que pode ser usado para atualizar campos específicos de inventário com níveis diferentes de granularidade.

Entender o inventário

Em termos gerais, o inventário geralmente se refere aos níveis de estoque (quantidade) e ao preço dos itens em um site de e-commerce. Para a API Retail, inventory se refere a preço, disponibilidade, quantidade disponível, informações de atendimento, preços locais e outros atributos locais. Esses campos são definidos no esquema do produto com os seguintes campos:

Inventário no nível do produto

Para comerciantes de sites de e-commerce com apenas um catálogo on-line, inventory geralmente é representado como os produtos no catálogo. O preço, a disponibilidade e todos os outros dados são definidos em cada entrada de Produto no catálogo. Os campos fulfillmentInfo e localInventories não são usados.

Inventário local

Para varejistas com várias lojas, os produtos ainda são representados pelas entradas de produto no catálogo, mas o inventário local (preço, disponibilidade e atendimento) pode ser adicionado aos locais (placeId) de um produto com o método addLocalInventories.

Há dois campos de produto separados usados para inventário local: Product.fulfillmentInfo e Product.localInventories. Um ou os dois podem ser usados, dependendo dos requisitos. fulfillmentInfo e localInventories são listas de locais com dados associados.

fulfillmentInfo especifica como um produto é atendido em um local específico, enquanto localInventories especifica o preço e outros atributos personalizados para cada local.

Para marcar um produto como esgotado ou não disponível em um local específico, o método removeLocalInventories é usado para remover fulfillment e inventory de um produto para um determinado placeId.

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

Alterações nas informações de inventário de um produto podem ocorrer com muito mais frequência do que as alterações nas informações de catálogo. Assim, um conjunto especializado de métodos é fornecido para lidar com grandes volumes de atualizações específicas do inventário. Esses métodos são assíncronos devido a otimizações downstream compatíveis com centenas de atualizações simultâneas por produto, sem sacrificar o desempenho.

Atualizações incrementais

Siga o guia de atualizações de inventário local para emitir atualizações incrementais. Os métodos de API mais recentes oferecem um controle mais refinado para atributos de inventário por lugar.

fulfillment_info é usado com frequência para codificar a disponibilidade de fulfillment em nível de lugar para um Product. Em alguns casos, a disponibilidade do fulfillment para alguns locais específicos pode mudar. Você pode decidir emitir atualizações que descrevem essa mudança em vez de usar o método UpdateProduct para especificar novamente todas as informações de fulfillment do produto.

Nesses casos, os métodos AddFulfillmentPlaces e RemoveFulfillmentPlaces podem ser usados para atualizar incrementalmente as alterações de fulfillment de um produto com base nos IDs do lugar. são adicionados ou removidos para um determinado tipo de fulfillment.

Java

Para saber como instalar e usar a biblioteca de cliente da Pesquisa da Vertex AI para comércio, consulte Bibliotecas de cliente da Pesquisa da Vertex AI para comércio. Para mais informações, consulte a documentação de referência da API Vertex AI Search para comércio Java.

Para autenticar na Vertex AI Search para e-commerce, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

public static AddFulfillmentPlacesResponse addFulfillmentPlaces(
    Product productToUpdate, String fulfillmentInfoType, ImmutableList<String> placeIds)
    throws IOException, InterruptedException, ExecutionException {
  ProductServiceClient productClient = getProductServiceClient();

  AddFulfillmentPlacesRequest request = AddFulfillmentPlacesRequest.newBuilder()
      .setProduct(productToUpdate.getName())
      .setType(fulfillmentInfoType)
      .addAllPlaceIds(placeIds)
      .setAddTime(Timestamps.fromMillis(System.currentTimeMillis()))
      .build();

  AddFulfillmentPlacesResponse response = productClient
      .addFulfillmentPlacesAsync(request).get();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return response;
}

Proto

  {
    product: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
    type: "pickup-in-store"
    place_ids: "store0"
    place_ids: "store1"
    add_time: {
      seconds: 100
      nanos: 100
    }
    allow_missing: true
  }

Esta amostra de AddFulfillmentPlacesRequest adiciona o tipo de fulfillment "pickup-in-store" para inserir os códigos "store0" e "store1" do produto especificado. Como AddFulfillmentPlacesRequest.allow_missing está definido como verdadeiro, mesmo que o produto ainda não exista, as informações do inventário atualizado serão armazenadas para quando o produto for criado. A atualização é carimbada com AddFulfillmentPlacesRequest.add_time para evitar que atualizações desatualizadas modifiquem o status de fulfillment desses IDs de local. Esses recursos são discutidos com mais detalhes nas seções a seguir.

O comportamento é idêntico para RemoveFulfillmentPlacesRequest, e o esquema é muito semelhante.

Quando fulfillment_types é atualizado por AddLocalInventories e RemoveLocalInventories, ele reflete um mapeamento de cada ID de lugar para uma lista de tipos de fulfillment compatíveis. Quando fulfillment_info é atualizado por AddFulfillmentPlaces e RemoveFulfillmentPlaces, ele reflete um mapeamento de cada tipo de fulfillment específico para uma lista de IDs de lugar que oferecem suporte a cada tipo. Os dois tipos de API modificam as mesmas informações de atendimento subjacentes, e o efeito dos dois tipos de APIs é refletido por Product.fulfillment_info.

Atualizações não incrementais

Os métodos price_info, availability e available_quantity não podem ser atualizados de forma incremental porque representam inventário no nível de produto, não informações no nível do local. Também é recomendável emitir atualizações não incrementais para fulfillment_info. Em vez de apenas mudanças incrementais, recomendamos o uso de SetInventory.

O método setInventory é a maneira preferida de atualizar preço, disponibilidade e quantidade no nível do produto quando são necessárias muitas atualizações frequentes. O método setInventory é assíncrono, então as atualizações podem não acontecer imediatamente. A cota padrão (300.000 solicitações por minuto) aceita muito mais solicitações do que UpdateProduct.

Além disso, o método setInventory é usado para atualizações de atendimento local quando fulfillmentInfo está incluído na solicitação, mas não pode atualizar os campos localInventories. Para esses atributos, use os métodos addLocalInventories e removeLocalInventories.

O inventário local é salvo no nível da loja, independente do catálogo. Para clientes com inventário on-line e off-line, o catálogo principal de produtos pode ser usado para on-line ou um placeId específico (-1 ou online, por exemplo) pode ser usado para representar o inventário on-line. No entanto, use o catálogo principal para o inventário on-line, porque os campos de inventário de produtos precisam ser preenchidos com valores priceInfo e availability válidos. Se um inventário placeId separado for usado para a loja on-line, o preço e as informações de disponibilidade do catálogo principal também precisarão ser mantidos atualizados. Para saber mais sobre atualizações de inventário local, consulte Atualizar inventário local.

Java

Para saber como instalar e usar a biblioteca de cliente da Pesquisa da Vertex AI para comércio, consulte Bibliotecas de cliente da Pesquisa da Vertex AI para comércio. Para mais informações, consulte a documentação de referência da API Vertex AI Search para comércio Java.

Para autenticar na Vertex AI Search para e-commerce, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

public static SetInventoryResponse setInventoryWithMask(Product productToUpdate,
    FieldMask updateMask)
    throws IOException, ExecutionException, InterruptedException {
  ProductServiceClient productClient = getProductServiceClient();

  SetInventoryRequest request = SetInventoryRequest.newBuilder()
      .setInventory(productToUpdate)
      .setSetMask(updateMask)
      .setSetTime(Timestamps.fromMillis(System.currentTimeMillis()))
      .setAllowMissing(true)
      .build();

  SetInventoryResponse response = productClient.setInventoryAsync(request).get();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return response;
}

Proto

  {
    product: {
      name: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
      availability: IN_STOCK
      fulfillment_info: {
        type: "pickup-in-store"
        place_ids: "store0"
        place_ids: "store1"
        place_ids: "store2"
        place_ids: "store3"
      }
      fulfillment_info: {
        type: "same-day-delivery"
      }
    }
    set_time: {
      seconds: 100
      nanos: 100
    }
    set_mask: {
      paths: "availability"
      paths: "fulfillment_info"
    }
    allow_missing: true
  }

Nesta solicitação específica, os campos SetInventoryRequest.product.fulfillment_info são descrições completas dos IDs de lugar qualificados de cada tipo de fulfillment, em vez das especificações incrementais. A atualização para "same-day-delivery" indica que nenhum ID de lugar está qualificado para esse tipo de fulfillment para esse produto. Todos os outros tipos de fulfillment não são atualizados nesta solicitação. Assim, esse método pode ser usado para substituir os IDs de lugar apenas em um subconjunto de tipos de fulfillment, deixando os outros tipos intactos.

Por padrão,SetInventory atualizará todos os campos de inventário se SetInventory.set_mask não estiver definido ou estiver vazio. Se a máscara não estiver vazia ou se um campo de inventário não estiver explicitamente listado em SetInventoryRequest.set_mask, qualquer valor especificado para esse campo será ignorado na solicitação de atualização.

Assim como acontece com as atualizações incrementais, o campo SetInventoryRequest.set_time pode ser usado para definir um horário de atualização que será a última hora de atualização registrada de todos os campos de inventário atualizados.

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

Há vários caminhos diferentes para atualizar os campos de inventário de um produto. Para proteger contra atualizações fora de ordem, cada campo de inventário é associado a um horário de atualização mais recente.

O horário da última atualização é registrado para price_info, availability, available_quantity e cada par de (fulfillment_info.place_ids, fulfillment_info.type).

Os métodos AddFulfillmentPlaces, RemoveFulfillmentPlaces e SetInventory permitem que o autor da chamada especifique uma o horário de atualização do 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 o tipo de fulfillment "pickup-in- store" ativado e o horário da última atualização registrado tenha sido definido como T. Se RemoveFulfillmentPlacesRequest.type = "pickup-in-store" eRemoveFulfillmentPlacesRequest.place_ids contém"store1", a solicitação será limpa"pickup-in-store" de"store1" somente se a RemoveFulfillmentPlacesRequest.remove_time é posterior ao horárioT de dados. O mesmo acontece para AddFulfillmentPlacesRequests.

SetInventory opera de maneira semelhante para atualizar price_info, availability e available_quantity. Ao atualizar fulfillment_info, um SetInventoryRequest está solicitando implicitamente a adição de todos os IDs de lugar especificados para um determinado tipo de fulfillment e a remoção de todos os não existentes.

Quando o SetInventoryRequest é processado, a atualização fulfillment_info é convertida implicitamente em um AddFulfillmentPlacesRequest e RemoveFulfillmentPlacesRequest para cada tipo de fulfillment especificado. Isso significa que, se algum lugar "store1" atual com fulfillment "pickup-in-store" tiver um horário da última atualização T mais recente do que SetInventoryRequest.set_time, a adição ou remoção implícita em "store1" e "pickup-in-store" não será aplicada.

Atributos de pré-carga

setInventory é assíncrono, o que significa que nenhum controle taxonômico ou referencial é aplicado ao adicionar ou modificar campos de inventário. Esse método não exige que o produto referenciado na solicitação já exista.

Isso permite que os clientes implementem padrões de pré-carregamento, em que o gerenciamento de campos de inventário pode ser dissociado do catálogo principal ou do processo de importação de produtos. Por exemplo, os usuários podem importar o contexto de disponibilidade ou preço antes do produto associado.

Cada um dos métodos de atualização de inventário 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 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 serão retidas por no máximo dois dias se o Product correspondente não for criado usando CreateProduct dentro desse período.

Java

public static SetInventoryResponse setInventory(Product productToUpdate)
    throws IOException, ExecutionException, InterruptedException {
  ProductServiceClient productClient = getProductServiceClient();

  SetInventoryRequest request = SetInventoryRequest.newBuilder()
      .setInventory(productToUpdate)
      .setSetTime(Timestamps.fromMillis(System.currentTimeMillis()))
      .setAllowMissing(true)
      .build();

  SetInventoryResponse response = productClient.setInventoryAsync(request).get();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return response;
}

Quando usar os métodos Product

Embora seja possível atualizar campos de inventário com os métodos CRUD do produto, o autor da chamada precisa estar explicitamente ciente dos efeitos nas informações de inventário existentes ou preexistentes.

Esses são métodos síncronos, ou seja, as otimizações downstream usadas para métodos de inventário não se aplicam e pode ficar caro depender desses métodos para atualizações frequentes de inventário. Sempre que possível, prefira usar os métodos de atualização de inventário mencionados acima.

CreateProduct

Quando CreateProduct é invocado com qualquer campo de inventário definido, os valores fornecidos em CreateProductRequest.product modificam quaisquer valores pré-carregados para os respectivos campos. Se nenhum campo de inventário for definido, todas as informações de inventário preexistentes serão usadas automaticamente.

Além disso, o horário da atualização mais recente dos campos de inventário modificados será redefinido para a hora da chamada de método.

CreateProduct com inventário pré-carregado

PROTO

{
  parent: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch"
  product_id: "p123"
  product: {
    name: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
    title: "some product"
    type: VARIANT
  }
}

Nesse exemplo, o produto criado não tem nenhum campo de inventário definido, o que significa que as informações de inventário pré-carregadas serão usadas automaticamente se atualizadas usando os métodos de atualização de inventário. Isso pode ser útil quando as atualizações de inventário são separadas das atualizações de catálogo e você quer que um Product recém-criado seja sincronizado com as informações de inventário existentes.

CreateProduct com inventário explícito

PROTO

{
  parent: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch"
  product_id: "p123"
  product: {
    name: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
    title: "some product"
    type: VARIANT
    availability: OUT_OF_STOCK
    fulfillment_info: {
      type: "pickup-in-store"
    }
    fulfillment_info: {
      type: "same-day-delivery"
    }
  }
}

Neste exemplo, uma Product é criada com campos de inventário definidos explicitamente. Esses campos substituirão os valores preexistentes, ignorando o horário da atualização mais recente dos campos correspondentes. Assim, a Product recém-criada terá a disponibilidade definida como OUT_OF_STOCK, e nenhum ID de lugar será compatível com os tipos de fulfillment "pickup-in-store" e "same-day-delivery".

CreateProduct com informações de inventário pode ser útil se você não tiver certeza se todas as informações de inventário pré-carregadas estão corretas e prefere definir explicitamente o inventário no momento da criação de Product para sincronizar totalmente o catálogo e o inventário.

UpdateProduct

O método UpdateProduct pode ser usado para atualizar atributos específicos em um item do catálogo. Isso pode ser feito para um ou vários campos ao mesmo tempo e para produtos individuais ou usando o método de importação de vários produtos. Se você usar o método de importação sem a máscara, uma substituição será feita.

O UpdateProduct é usado com frequência para atualizações de preço e disponibilidade em tempo real, mas pode ser usado para atualizar qualquer campo sem precisar enviar todos os dados de um produto novamente. (em contraste com createMethod ou importProducts.

O principal benefício de usar UpdateProduct é que ele é uma solicitação síncrona. As atualizações no índice (e na pesquisa ou nas recomendações) são quase instantâneas. No entanto, UpdateProduct não foi projetado para atualizações muito frequentes. A cota padrão é de 12.000 solicitações de gravação de produtos por minuto. Normalmente, você só usa esse método quando o preço de um item muda ou se o estado do estoque muda (não para cada diminuição de quantidade).

UpdateProduct só pode modificar os atributos no nível do produto. Não é possível usar esse método para modificar nenhum dos atributos de inventário local de localInventories ou fulfillmentInfo.

Ao fazer uma chamada com UpdateProduct ou ImportProducts, é importante especificar o parâmetro updateMask. updateMask contém uma lista dos campos a serem atualizados. Somente os campos especificados em updateMask serão atualizados, mesmo que mais campos sejam transmitidos no corpo da solicitação. Se nenhum updateMask estiver presente em uma solicitação de atualização ou importação, todos os campos serão atualizados exatamente com o que foi enviado no corpo da solicitação.

Quando UpdateProduct é invocado e a máscara de campo UpdateProductRequest.update_mask contém qualquer campo de inventário, os valores fornecidos no UpdateProductRequest.product substituem quaisquer valores pré-carregados para os respectivos campos.

Além disso, o horário da atualização mais recente dos campos de inventário modificados será redefinido para a hora da chamada de método.

PROTO

{
  product: {
    name: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
    availability: IN_STOCK
    fulfillment_info: {
      type: "pickup-in-store"
      place_ids: "store0"
      place_ids: "store1"
      place_ids: "store2"
      place_ids: "store3"
    }
    fulfillment_info: {
      type: "same-day-delivery"
    }
  }
  update_mask: {
    paths: "availability"
    paths: "fulfillment_info"
  }
}

Este exemplo é muito semelhante ao exemplo SetInventory, mas a atualização é aplicada independentemente do horário da atualização mais recente de cada campo de inventário.

  • UpdateProduct para inventário pode ser útil quando uma sincronização completa em informações de inventário é necessária ao ignorar as proteções de carimbo de data/hora.

  • Ao definir UpdateProductRequest.allow_missing como true para realizar um comando Product, é possível pré-carregar informações de inventário usando UpdateProduct. O método exige a definição de campos específicos do catálogo, como UpdateProductRequest.product.title. Portanto, use os métodos de atualização de inventário para pré-carregar casos de uso.

DeleteProduct

Quando DeleteProduct for invocado, todas as informações de inventário existentes do produto especificado em DeleteProductRequest.name será excluído, incluindo todos os registros do horário da atualização mais recente de cada campo de inventário.

Considerações se você substituir atributos no nível do produto por atributos no nível do inventário

Confira as considerações e limitações associadas a cada abordagem:

Recurso Inventário no nível do produto Inventário no nível da loja (local)
Controles de filtro e otimização de pesquisa Sim Sim
Formato da chave de filtro e faceta especificado em facetSpec Sim Não
Disponível para refinamentos de pesquisa Sim Não
Retornado na resposta da pesquisa Sim Sim (usando variantRollupKeys)
Controles de filtros e de reforço da Recommendations AI v2 Sim Não
Recurso Inventário no nível do produto Inventário local no nível da loja
Controles de filtro de pesquisa e de reforço
Formato da chave de filtro e faceta especificado em facetSpec
Disponível para refinamentos de pesquisa
Retornado na resposta da pesquisa (usando variantRollupKeys)
Controles de filtros e de reforço da Recommendations AI v2

Há alguma sobreposição na funcionalidade dos diferentes métodos de atualização da disponibilidade, do atendimento e do preço local do produto:

Recurso UpdateProduct setInventory addLocalInventories
Atualizações em tempo real
Atualize os campos de produtos
Atualizar o preço do produto
Atualizar a disponibilidade do produto
Atualizar fulfillmentInfo
Atualizar localInventories (preços locais)
Sequenciamento de carimbo de data/hora

Exemplos

Esta seção demonstra como atualizar o inventário de produtos usando os métodos UpdateProduct e setInventory em comandos curl.

  • O UpdateProduct usa o método HTTP PATCH da API REST para atualizações síncronas e em tempo real de campos no nível do produto, como preço e disponibilidade. Ele também pode ser usado para atualizações em lote com o método import e um updateMask.

  • O método assíncrono setInventory é mostrado para atualizar campos de inventário no nível do produto (preço, disponibilidade, quantidade) e detalhes de fulfillment local usando fulfillmentInfo, mas não pode modificar preços ou atributos locais armazenados em localInventories.

Use UpdateProduct para atualizar o preço e a disponibilidade do produto

Ao usar a API REST, o UpdateProduct usa o método HTTP PATCH. O mesmo URL de endpoint que CreateProduct, GetProduct e DeleteProduct usa os métodos HTTP PUT, GET e DELETE, respectivamente. Abra os links a seguir para conferir os exemplos de curl respectivos.

Use setInventory para atualizar o preço e a disponibilidade do produto

setInventory é compatível apenas com os seguintes campos:

  • availability
  • availableQuantity
  • priceInfo

Abra os links a seguir para conferir os exemplos de curl respectivos.

Para inventário local, placeIds e tipos de atendimento podem ser transmitidos em fulfillmentInfo, como demonstra este exemplo de curl:

Tutoriais

Use estes tutoriais para saber como usar o setInventory ou adicionar ou remover atendimentos.

Tutorial de configuração do inventário

Este tutorial mostra como enviar atualizações do inventário usando o método SetInventory em vez de atualizar todo o produto.

Para seguir as instruções da tarefa diretamente no editor do Cloud Shell, clique em Orientação:

Orientações

Tutorial de adição de fulfillment

Recomendamos usar o método AddLocalInventories em vez de AddFulfillmentPlaces. O AddLocalInventories alcança os mesmos resultados, mas oferece um controle mais refinado sobre a ingestão de dados de inventário local. Para mais informações, consulte a documentaçãoAddLocalInventories.

Este tutorial mostra como atualizar as informações de fulfillment de produtos usando o método AddFulfillmentPlaces. Assim, a pesquisa pode mostrar atualizações de disponibilidade de produtos e pedidos que podem ser atendidos. Por exemplo, um comprador está procurando jeans azuis em uma loja, mas eles estão esgotados. Assim que os jeans estiverem em estoque novamente nessa loja ou em qualquer outra, o comprador vai ver as atualizações e poderá continuar com o pedido.

Para seguir as instruções da tarefa diretamente no editor do Cloud Shell, clique em Orientação:

Orientações

Tutorial de remoção de fulfillment

Recomendamos usar o método RemoveLocalInventories em vez de RemoveFulfillmentPlaces. O RmoveLocalInventories alcança os mesmos resultados, mas oferece um controle mais refinado sobre a ingestão de dados de inventário local. Para mais informações, consulte a documentaçãoRemoveLocalInventories.

Este tutorial mostra como atualizar as informações de fulfillment de produtos usando o método RemoveFulfillmentPlaces. Assim, a Vertex AI Search for commerce pode mostrar atualizações quando os produtos não estão disponíveis e os pedidos não podem ser atendidos. Assim, a pesquisa pode mostrar atualizações quando os produtos não estão disponíveis e os pedidos não podem ser atendidos. Por exemplo, um comprador está procurando calças jeans azuis em uma loja. Se o jeans ficar sem estoque nessa loja, o comprador vai ver isso e não poderá continuar com o pedido.

Para seguir as instruções da tarefa diretamente no editor do Cloud Shell, clique em Orientação:

Orientações