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

Esta página descreve os métodos de gestão das atualizações de preços e quantidades em tempo real para o catálogo do Vertex AI Search for commerce através da Retail API.

Embora os métodos de Productcriação, leitura, atualização e eliminação (CRUD) sejam usados para modificar amplamente os atributos de um Product, existe um conjunto de métodos de Product que podem ser usados para atualizar campos específicos do inventário com vários níveis de detalhe.

Compreenda o inventário

Em termos gerais, o inventário refere-se normalmente aos níveis de stock (quantidade) e ao preço dos artigos num site de comércio eletrónico. Para a API Retail, inventory refere-se ao preço, à disponibilidade, à quantidade disponível, às informações de processamento, aos preços locais e aos atributos locais adicionais. Estes campos estão definidos no esquema Product com os seguintes campos:

Inventário ao nível do produto

Para comerciantes de sites de comércio eletrónico com apenas um catálogo online, inventory é normalmente representado apenas pelos 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 retalhistas com várias localizações, os produtos continuam a ser representados pelas entradas de produtos no catálogo, mas o inventário local (preço, disponibilidade e processamento) pode ser adicionado a localizações (placeId) para um produto com o método addLocalInventories.

Existem dois campos de produtos separados usados para o inventário local: Product.fulfillmentInfo e Product.localInventories. Pode usar uma ou ambas, consoante os requisitos. fulfillmentInfo e localInventories são listas de localizações com dados associados.

fulfillmentInfo especifica como um produto é processado numa determinada localização, enquanto localInventories especifica o preço e outros atributos personalizados para cada localização.

Para marcar um produto como esgotado ou já não disponível numa localização específica, o método removeLocalInventories é usado para remover fulfillment e inventory de um produto para um placeId específico.

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

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

Atualizações incrementais

Siga o guia de atualizações do inventário local para emitir atualizações incrementais do inventário. Os métodos da API mais recentes oferecem um controlo mais detalhado dos atributos do inventário por posicionamento.

O elemento fulfillment_info é frequentemente usado para codificar a disponibilidade de processamento ao nível do local para um Product. Em alguns casos, a disponibilidade de processamento para alguns locais específicos pode mudar. Pode optar por emitir atualizações que descrevam esta alteração, em vez de usar o método UpdateProduct para especificar novamente todas as informações de processamento do produto.

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

Java

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

Para se autenticar no Vertex AI Search para comércio, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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
  }

Este exemplo AddFulfillmentPlacesRequest adiciona o tipo de processamento "pickup-in-store" aos IDs dos locais "store0" e "store1" para o produto especificado. Uma vez que AddFulfillmentPlacesRequest.allow_missing está definido como verdadeiro, mesmo que o produto ainda não exista, as informações de inventário atualizadas são armazenadas para quando o produto for criado. A atualização tem a data/hora de AddFulfillmentPlacesRequest.add_time para evitar que atualizações desatualizadas substituam o estado de processamento destes IDs de locais. Estas funcionalidades são abordadas com maior detalhe nas secções seguintes.

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

Quando fulfillment_types é atualizado por AddLocalInventories e RemoveLocalInventories, reflete uma associação de cada ID de local a uma lista de tipos de processamento que suporta. Quando fulfillment_info é atualizado por AddFulfillmentPlaces e RemoveFulfillmentPlaces, reflete um mapeamento de cada tipo de processamento específico para uma lista de IDs de estabelecimentos que suporta cada tipo. Ambos os tipos de API estão a modificar as mesmas informações de processamento subjacentes, e o efeito de ambos os tipos de APIs reflete-se em Product.fulfillment_info.

Atualizações não incrementais

Não é possível atualizar os métodos price_info, availability e available_quantity de forma incremental, porque representam o inventário ao nível do produto e não informações ao nível do local. Também pode ser útil emitir atualizações não incrementais para fulfillment_info. Em vez de apenas alterações incrementais, recomendamos a SetInventory.

O método setInventory é a forma preferencial de atualizar o preço, a disponibilidade e a quantidade ao nível do produto quando são necessárias muitas atualizações frequentes. O método setInventory é assíncrono, pelo que as atualizações podem não ocorrer imediatamente. A quota predefinida (300 000 pedidos por minuto) suporta muito mais pedidos do que UpdateProduct.

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

O inventário local é guardado ao nível da loja, independentemente do catálogo. Para clientes com inventário online e offline, o catálogo de produtos principal pode ser usado para o inventário online ou um placeId específico (por exemplo, -1 ou online) pode ser usado para representar o inventário online. No entanto, use o catálogo principal para o inventário online, uma vez que os campos de inventário de produtos devem ser preenchidos com valores priceInfo e availability válidos. Se for usado um inventário separado placeId para online, as informações de preço e disponibilidade do catálogo principal também devem ser mantidas atualizadas. Para mais informações sobre as atualizações do inventário local, consulte o artigo Atualize o inventário local.

Java

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

Para se autenticar no Vertex AI Search para comércio, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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
  }

Neste pedido específico, os SetInventoryRequest.product.fulfillment_info campos são descrições completas dos IDs de estabelecimentos elegíveis de cada tipo de processamento, ao contrário das especificações incrementais. A atualização a "same-day-delivery" indica que nenhum ID de local é elegível para este tipo de processamento para este produto. Todos os outros tipos de processamento não são atualizados neste pedido. Assim, este método pode ser usado para substituir os IDs de estabelecimentos apenas para um subconjunto de tipos de processamento, deixando os outros tipos inalterados.

Por predefinição,SetInventory atualiza 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 de inventário será ignorado no pedido de atualização.

Tal como nas atualizações incrementais, pode usar o campo SetInventoryRequest.set_time para definir uma hora de atualização que será comparada com a hora de atualização registada mais recente de todos os campos de inventário atualizados.

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

Existem vários caminhos diferentes para atualizar os campos de inventário de um produto e, para se proteger contra atualizações desordenadas, cada campo de inventário está associado a uma hora de atualização mais recente.

A hora da última atualização é registada 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 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 apenas se a hora de atualização for estritamente posterior à hora de atualização mais recente.

Por exemplo, suponhamos que o ID do local "store1" tem o tipo de processamento de pedidos "pickup-in- store" ativado, com a hora da última atualização registada definida para a hora T. Se RemoveFulfillmentPlacesRequest.type = "pickup-in-store" e RemoveFulfillmentPlacesRequest.place_ids contiver "store1", o pedido vai limpar "pickup-in-store" de "store1" se e apenas se RemoveFulfillmentPlacesRequest.remove_time for posterior à hora T. O mesmo se aplica a AddFulfillmentPlacesRequests.

O SetInventory funciona de forma semelhante para atualizar o price_info, availability e o available_quantity. Quando atualiza fulfillment_info, está a pedir implicitamente para adicionar todos os IDs de locais especificados para um determinado tipo de processamento e remover todos os IDs de locais existentes não especificados.SetInventoryRequest

Quando o SetInventoryRequest é processado, a atualização fulfillment_info é convertida implicitamente num AddFulfillmentPlacesRequest e num RemoveFulfillmentPlacesRequest para cada tipo de processamento especificado. Isto significa que, se um local existente "store1" com o preenchimento "pickup-in-store" tiver uma hora da última atualização T mais recente do que SetInventoryRequest.set_time, a adição ou a remoção implícita em "store1" e "pickup-in-store" não é aplicada.

Atributos de pré-carregamento

setInventory é assíncrono, o que significa que não são aplicados controlos taxonómicos ou referenciais quando adiciona ou modifica campos de inventário. Este método não requer que o produto referenciado no pedido já exista.

Isto permite que os clientes implementem padrões de pré-carregamento, em que a gestão dos campos de inventário pode ser separada do processo principal de importação de produtos ou do catálogo. Por exemplo, os utilizadores podem importar o contexto de disponibilidade ou preço antes de o produto associado ser importado.

Cada um dos métodos de atualização do inventário permite ao autor da chamada definir allow_missing no pedido. Quando allow_missing está definido como verdadeiro, uma atualização do inventário para um Product inexistente é processada como se o Product existisse de acordo com as especificações do método. As informações de inventário são retidas durante um máximo de dois dias se o Product correspondente não for criado através do CreateProduct dentro deste prazo.

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 os campos de inventário com os métodos CRUD de produtos, o autor da chamada deve estar explicitamente ciente dos efeitos nas informações de inventário existentes ou pré-existentes.

Estes são métodos síncronos, o que significa que as otimizações a jusante usadas para métodos de inventário não se aplicam, e pode tornar-se caro depender destes métodos para atualizações frequentes do inventário. Sempre que possível, prefira usar os métodos de atualização do inventário mencionados acima.

CreateProduct

Quando CreateProduct é invocado com quaisquer campos de inventário definidos, os valores fornecidos em CreateProductRequest.product substituem quaisquer valores pré-carregados para esses campos respetivos. Se não forem definidos campos de inventário, são usadas automaticamente todas as informações de inventário preexistentes.

Além disso, a hora de atualização mais recente dos campos de inventário substituídos é reposta para a hora da chamada do 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
  }
}

Neste exemplo, o produto criado não tem campos de inventário definidos, o que significa que todas as informações de inventário pré-carregadas são usadas automaticamente se forem atualizadas através dos métodos de atualização de inventário. Isto pode ser útil quando as atualizações de inventário estão separadas das atualizações do catálogo e quer que um produto Product recém-criado seja sincronizado com as informações de inventário pré-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, é criado um Product com campos de inventário definidos explicitamente. Estes campos substituem todos os valores preexistentes, ignorando a hora de atualização mais recente dos campos correspondentes. Assim, o Product recém-criado tem a disponibilidade definida como OUT_OF_STOCK e nenhum ID de local suporta os tipos de processamento de pedidos "pickup-in-store" e "same-day-delivery".

CreateProduct com informações de inventário pode ser útil se não tiver a certeza de que todas as informações de inventário pré-carregadas estão corretas e preferir 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 num item do catálogo existente. Isto pode ser feito para um ou vários campos em simultâneo e para produtos individuais ou vários produtos através do método de importação. Se usar o método de importação sem a máscara, faz uma substituição.

O elemento UpdateProduct é frequentemente usado para atualizações de preços e disponibilidade em tempo real, mas pode ser usado para atualizar quaisquer campos sem ter de enviar novamente todos os dados de um produto. (em contraste com o createMethod ou o importProducts.

A principal vantagem de usar UpdateProduct é que se trata de um pedido síncrono. As atualizações ao índice (e à pesquisa ou às recomendações) são quase instantâneas. No entanto, o UpdateProduct não se destina a ser usado para atualizações muito frequentes. A quota predefinida é de 12 000 pedidos de gravação de produtos por minuto. Normalmente, é recomendável usar este método apenas quando o preço de um artigo muda ou se o estado do stock muda (não para cada diminuição da quantidade).

UpdateProduct só pode modificar os atributos ao nível do produto. Não pode ser usado para modificar nenhum dos atributos do inventário local para localInventories ou fulfillmentInfo.

Quando faz uma chamada com UpdateProduct ou ImportProducts, é importante especificar o parâmetro updateMask. updateMask contém uma lista dos campos a atualizar. Apenas os campos especificados em updateMask são atualizados, mesmo que sejam transmitidos mais campos no corpo do pedido. Se não existir nenhum updateMask para um pedido de atualização ou importação, todos os campos são atualizados exatamente para o que é enviado no corpo do pedido.

Quando UpdateProduct é invocado e a máscara de campo UpdateProductRequest.update_mask contém campos de inventário, os valores fornecidos em UpdateProductRequest.product substituem todos os valores pré-carregados para esses campos respetivos.

Além disso, a hora de atualização mais recente dos campos de inventário substituídos é reposta para a hora da chamada do 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, exceto que a atualização aplica-se independentemente da hora de atualização mais recente de cada campo do inventário.

  • UpdateProduct para o inventário pode ser útil quando é necessária uma sincronização completa das informações do inventário, ignorando as proteções de data/hora.

  • Se definir UpdateProductRequest.allow_missing como true para fazer um Product upsert, pode pré-carregar informações de inventário através de UpdateProduct. O método requer a definição de campos do catálogo específicos, como UpdateProductRequest.product.title. Por isso, use os métodos de atualização do inventário para exemplos de utilização de pré-carregamento.

DeleteProduct

Quando DeleteProduct é invocado, todas as informações de inventário existentes para o produto especificado em DeleteProductRequest.name são eliminadas, incluindo todos os registos da data/hora da última atualização de cada campo de inventário.

Considerações se substituir os atributos ao nível do produto por atributos ao nível do inventário

Tenha em atenção as seguintes considerações e limitações associadas a cada abordagem:

Funcionalidade Inventário ao nível do produto Inventário ao nível da loja (local)
Filtro de pesquisa e controlos de otimização Sim Sim
Formato da chave de filtro e faceta especificado em facetSpec Sim Não
Disponível para filtros de pesquisa Sim Não
Devolvido na resposta da pesquisa Sim Sim (através do variantRollupKeys)
Filtros e controlos de otimização da IA de recomendações v2 Sim Não
Funcionalidade Inventário ao nível do produto Inventário ao nível da loja (local)
Controlos de filtro de pesquisa e otimização
Formato da chave de filtro e faceta especificado em facetSpec
Disponível para filtros de pesquisa
Devolvido na resposta da pesquisa (a usar variantRollupKeys)
Filtros e controlos de otimização da IA de recomendações v2

Existe alguma sobreposição na funcionalidade dos diferentes métodos de atualização da disponibilidade, do processamento e do preço local dos produtos:

Funcionalidade UpdateProduct setInventory addLocalInventories
Atualizações em tempo real
Atualize quaisquer campos de produtos
Atualize o preço do produto
Atualize a disponibilidade dos produtos
Atualize fulfillmentInfo
Atualize localInventories (preços locais)
Sequência de indicações de tempo

Exemplos

Esta secção demonstra como atualizar o inventário de produtos através dos métodos UpdateProduct e setInventory em comandos curl.

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

  • O método setInventory assíncrono é apresentado para atualizar os campos de inventário ao nível do produto (preço, disponibilidade, quantidade) e os detalhes de processamento locais através de fulfillmentInfo, mas não pode modificar os preços locais nem os atributos armazenados em localInventories.

Use o UpdateProduct para atualizar o preço e a disponibilidade dos produtos

Quando usa a API REST, UpdateProduct usa o método HTTP PATCH. O mesmo URL do ponto final que CreateProduct, GetProduct e DeleteProduct usa os métodos HTTP PUT, GET e DELETE, respetivamente. Expanda os links seguintes para ver os respetivos exemplos de curl.

Use o setInventory para atualizar o preço e a disponibilidade dos produtos

O setInventory só suporta os seguintes campos:

  • availability
  • availableQuantity
  • priceInfo

Expanda os links seguintes para ver os respetivos exemplos de curl.

Para o inventário local, os tipos de placeIds e de fornecimento 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 processamentos.

Tutorial de definição do inventário

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

Para seguir orientações passo a passo para esta tarefa diretamente no editor do Cloud Shell, clique em Orientar-me:

Visita guiada

Adicione um tutorial de processamento

Recomendamos que use o método AddLocalInventories em vez de AddFulfillmentPlaces. AddLocalInventories alcança os mesmos resultados, mas oferece um controlo mais detalhado sobre o carregamento de dados de inventário local. Para mais informações, consulte a documentação do AddLocalInventories.

Este tutorial mostra como atualizar as informações de processamento de produtos através do método AddFulfillmentPlaces. Desta forma, a pesquisa pode mostrar atualizações sobre a disponibilidade dos produtos e o processamento das encomendas. Por exemplo, um comprador está à procura de calças de ganga azuis numa loja, mas não estão disponíveis. No momento em que as calças de ganga estiverem novamente em stock nesta loja ou em qualquer outra, o comprador vê as atualizações e pode avançar com a encomenda.

Para seguir orientações passo a passo para esta tarefa diretamente no editor do Cloud Shell, clique em Orientar-me:

Visita guiada

Remova o tutorial de processamento

Recomendamos que use o método RemoveLocalInventories em vez de RemoveFulfillmentPlaces. RmoveLocalInventories alcança os mesmos resultados, mas oferece um controlo mais detalhado sobre o carregamento de dados de inventário local. Para mais informações, consulte a documentação do RemoveLocalInventories.

Este tutorial mostra como atualizar as informações de processamento de produtos através do método RemoveFulfillmentPlaces. Desta forma, a Vertex AI Search for commerce pode apresentar atualizações quando os produtos não estão disponíveis e não é possível processar as encomendas. Desta forma, a pesquisa pode mostrar atualizações quando os produtos não estão disponíveis e não é possível processar as encomendas. Por exemplo, um comprador está à procura de calças de ganga azuis numa loja. Se as calças de ganga ficarem esgotadas nesta loja, o comprador vê esta informação e não pode avançar com a encomenda.

Para seguir orientações passo a passo para esta tarefa diretamente no editor do Cloud Shell, clique em Orientar-me:

Visita guiada