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

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. Os campos Product a seguir são considerados campos de inventário:

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

Tutorial de configuração do inventário

Neste tutorial, mostramos como enviar atualizações de inventário usando o 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 granular 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. Dessa forma, a pesquisa pode mostrar atualizações onde os produtos estão disponíveis e pedidos podem ser atendidos. Por exemplo, um comprador está procurando jeans azuis em uma loja, mas eles estão esgotados. Assim que o jeans estiver em estoque novamente, loja ou qualquer outra loja, o comprador vê as atualizações e pode prosseguir com as ordem.

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 atinge os mesmos resultados, mas fornece 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. Dessa forma, a Vertex AI para Pesquisa para varejo pode mostrar atualizações em que os produtos não estão disponíveis e os pedidos não podem ser atendidos. Dessa forma, a pesquisa pode mostrar atualizações quando os produtos não estão disponível e os pedidos não podem ser atendidos. Por exemplo, um comprador está procurando jeans azul em uma loja. Se o jeans ficar sem estoque na loja, o comprador vai saber disso e não poderá prosseguir com o pedido.

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

Orientações

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

Recomendamos seguir o guia de atualizações de inventário local para emitir atualizações incrementais de inventário. Os métodos mais recentes da API oferecem um controle mais preciso 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, e você pode decidir emitir atualizações que descrevem essa mudança em vez de usar o método UpdateProduct para especificar novamente as informações de fulfillment de todo o 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 varejo, consulte Bibliotecas de cliente da Pesquisa da Vertex AI para varejo. Para mais informações, consulte a documentação de referência da API Vertex AI Search for retail Java.

Para autenticar na Vertex AI para Pesquisa para Retail, 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
  }

Este exemplo de AddFulfillmentPlacesRequest adiciona um tipo de fulfillment "pickup-in-store" para colocar os IDs "store0" e "store1" do objeto especificado produto. Devido ao AddFulfillmentPlacesRequest.allow_missing é definido como verdadeiro, mesmo que o produto ainda não existir, as informações atualizadas do inventário serão armazenadas para quando o produto é 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 foi atualizado por AddFulfillmentPlaces e RemoveFulfillmentPlaces, reflete um mapeamento de cada tipo de fulfillment específico para uma lista de IDs de lugar que aceitam cada não é válido. Os dois tipos de API estão modificando as mesmas informações de cumprimento, e o efeito dos dois tipos de API é refletido por Product.fulfillment_info.

Atualizações não incrementais

price_info, availability e available_quantity não podem ser atualizados de forma incremental porque representam inventário no nível de produto, em vez de informações no nível do local. Além disso, é recomendável emitir atualizações não incrementais para fulfillment_info em vez de apenas alterações incrementais. Nesses casos, o método SetInventory é recomendado.

Java

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

Para autenticar na Pesquisa da Vertex AI para varejo, 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. Portanto, esse método pode ser usado para substituir os IDs de lugar de apenas um subconjunto de tipos de fulfillment, sem alterar os outros tipos.

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.

Portanto, quando SetInventoryRequest for processado, a atualização fulfillment_info será 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/adicionar implícita remova em "store1" e "pickup-in-store" não será aplicado.

Pré-carregar informações do inventário

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 por 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

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 é garantida para ser 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.

Embora seja possível pré-carregar informações de inventário usando UpdateProduct definindo UpdateProductRequest.allow_missing como true para realizar um comando Product, o método exige a configuração de campos de catálogo específicos, como UpdateProductRequest.product.title. Assim, é recomendável usar 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.