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

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

  • Product.price_info
  • Product.availability
  • Product.available_quantity
  • Product.fulfillment_info

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 estão esgotadas. 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 em que 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

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

Tenha em atenção que é recomendável seguir o guia de atualizações de inventário local para emitir atualizações de inventário incrementais. Os métodos da API mais recentes oferecem um controlo mais detalhado dos atributos do inventário por local.

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, e pode decidir emitir atualizações que descrevam esta alteração em vez de usar o método UpdateProduct para especificar novamente as informações de processamento completas 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 da Vertex AI Search para comércio, consulte o artigo Bibliotecas cliente da Vertex AI Search para comércio. Para mais informações, consulte a documentação de referência da API JavaVertex AI Search para comércio.

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 estabelecimentos "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 um mapeamento de cada ID de local para 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 APIs 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 price_info, availability e available_quantity de forma incremental, uma vez que representam o inventário ao nível do produto, em oposição às informações ao nível do local. Além disso, pode ser desejável emitir atualizações não incrementais para fulfillment_info em vez de apenas alterações incrementais. Nestes casos, recomendamos o método SetInventory.

Java

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

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
  }

Nesta solicitação específica, os SetInventoryRequest.product.fulfillment_info campos são descrições completas dos IDs de locais elegíveis de cada tipo de processamento, em vez de 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 seSetInventory.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, o 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

Assim, quando o elemento SetInventoryRequest é processado, a atualização fulfillment_info é convertida implicitamente num elemento AddFulfillmentPlacesRequest e num elemento RemoveFulfillmentPlacesRequest para cada tipo de processamento especificado. Isto significa que, se algum 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/remoção implícita em "store1" e "pickup-in-store" não será aplicada.

Pré-carregue informações de inventário

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 da 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 pré-existentes.

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, é garantido que o Product recém-criado tem a disponibilidade definida como OUT_OF_STOCK e que nenhum ID do local suporta os tipos de preenchimento "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 do Product para sincronizar totalmente o catálogo e o inventário.

UpdateProduct

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 é garantidamente aplicada independentemente da hora da última atualização de cada campo de 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.

Embora seja possível pré-carregar informações de inventário usando UpdateProduct ao definir UpdateProductRequest.allow_missing como true para fazer um upsert, o método requer a definição de campos específicos do catálogo, como UpdateProductRequest.product.title.Product Por conseguinte, é recomendável usar 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.