Aggiornare l'inventario per Vertex AI Search per la vendita al dettaglio

Mentre i metodi Product di creazione, lettura, aggiornamento ed eliminazione (CRUD) sono utilizzati per modificare in modo ampio gli attributi di Product, esiste un insieme di metodi Product che possono essere utilizzati per aggiornare i campi specifici dell'inventario con diversi livelli di granularità. I seguenti campi Product sono considerati campi dell'inventario:

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

Tutorial sulla configurazione dell'inventario

Questo tutorial mostra come eseguire il push degli aggiornamenti dell'inventario utilizzando il metodo SetInventory anziché aggiornare l'intero prodotto.

Per seguire le indicazioni dettagliate per questa attività direttamente nell'editor di Cloud Shell, fai clic su Aiuto:

Guidami

Tutorial sull'aggiunta di fulfillment

Ti consigliamo di utilizzare il metodo AddLocalInventories anziché AddFulfillmentPlaces. AddLocalInventories consente di ottenere gli stessi risultati, ma offre un controllo più granulare sull'importazione dei dati dell'inventario locale. Per saperne di più, consulta la documentazione di AddLocalInventories.

Questo tutorial mostra come aggiornare le informazioni di evasione dei prodotti utilizzando il metodo AddFulfillmentPlaces. In questo modo, la ricerca può mostrare gli aggiornamenti in cui i prodotti sono disponibili e gli ordini possono essere completati. Ad esempio, un acquirente cerca dei jeans in un negozio ma non è disponibile. Nel momento in cui i jeans sono di nuovo disponibili in questo negozio o in qualsiasi altro negozio, l'acquirente vede gli aggiornamenti e può procedere con l'ordine.

Per seguire le indicazioni dettagliate per questa attività direttamente nell'editor di Cloud Shell, fai clic su Aiuto:

Guidami

Tutorial sulla rimozione di fulfillment

Ti consigliamo di utilizzare il metodo RemoveLocalInventories anziché RemoveFulfillmentPlaces. RmoveLocalInventories consente di ottenere gli stessi risultati, ma offre un controllo più granulare sull'importazione dei dati dell'inventario locale. Per saperne di più, consulta la documentazione di RemoveLocalInventories.

Questo tutorial mostra come aggiornare le informazioni di evasione degli ordini dei prodotti utilizzando il metodo RemoveFulfillmentPlaces. In questo modo, Vertex AI Search per la vendita al dettaglio può mostrare aggiornamenti in cui i prodotti non sono disponibili e gli ordini non possono essere completati. In questo modo, la ricerca può mostrare gli aggiornamenti in cui i prodotti non sono disponibili e gli ordini non possono essere completati. Ad esempio, un acquirente cerca dei blue jeans in un negozio. Se i jeans non sono disponibili in questo negozio, l'acquirente vede l'articolo e non può procedere con l'ordine.

Per seguire le indicazioni dettagliate per questa attività direttamente nell'editor di Cloud Shell, fai clic su Aiuto:

Guidami

Metodi di aggiornamento dell'inventario

Le modifiche alle informazioni di inventario di un prodotto possono avvenire molto più spesso rispetto alle modifiche alle informazioni del catalogo. Di conseguenza, viene fornito un set di metodi specializzati per gestire grandi volumi di aggiornamenti specifici dell'inventario. Questi metodi sono asincroni grazie alle ottimizzazioni downstream che supportano centinaia di aggiornamenti simultanei per prodotto, senza sacrificare le prestazioni.

Aggiornamenti incrementali

Tieni presente che è consigliabile seguire la guida agli aggiornamenti dell'inventario locale per emettere aggiornamenti incrementali dell'inventario. I metodi dell'API più recenti forniscono un controllo più granulare per gli attributi di inventario per luogo.

fulfillment_info viene spesso utilizzato per codificare la disponibilità di evasione degli ordini a livello di luogo per un Product. In alcuni casi, la disponibilità di evasione degli ordini per alcuni luoghi specifici potrebbe cambiare e potresti decidere di emettere aggiornamenti che descrivono questa modifica anziché utilizzare il metodo UpdateProduct per specificare nuovamente le informazioni di evasione degli ordini per l'intero prodotto.

In questi casi, è possibile utilizzare i metodi AddFulfillmentPlaces e RemoveFulfillmentPlaces per aggiornare in modo incrementale le modifiche di evasione di un prodotto in base agli ID luogo aggiunti o rimossi per un determinato tipo di evasione.

Java

Per scoprire come installare e utilizzare la libreria client per Vertex AI Search per il retail, consulta Vertex AI Search per le librerie client per il retail. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Vertex AI Search per la vendita al dettaglio Java.

Per eseguire l'autenticazione in Vertex AI Search per la vendita al dettaglio, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

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
  }

In questo esempio AddFulfillmentPlacesRequest, il tipo di evasione degli ordini "pickup-in-store" viene aggiunto agli ID luogo "store0" e "store1" per il prodotto specificato. Poiché AddFulfillmentPlacesRequest.allow_missing è impostato su true, anche se il prodotto non esiste già, le informazioni aggiornate sull'inventario verranno archiviate per quando il prodotto verrà creato. L'aggiornamento ha un timestamp AddFulfillmentPlacesRequest.add_time per evitare che gli aggiornamenti inattivi sostituiscano lo stato di evasione di questi ID luogo. Queste funzionalità sono illustrate più dettagliatamente nelle sezioni seguenti.

Il comportamento è identico per RemoveFulfillmentPlacesRequest e lo schema è molto simile.

Quando l'elemento fulfillment_types viene aggiornato da AddLocalInventories e RemoveLocalInventories, riflette una mappatura da ogni ID luogo a un elenco di tipi di evasione degli ordini supportati. Quando fulfillment_info viene aggiornato da AddFulfillmentPlaces e RemoveFulfillmentPlaces, riflette una mappatura di ogni tipo di fulfillment specifico a un elenco di ID luogo che supporta ciascun tipo. Entrambi i tipi di API stanno modificando le stesse informazioni di fulfillment sottostanti e l'effetto di entrambi i tipi di API si riflette in Product.fulfillment_info.

Aggiornamenti non incrementali

price_info, availability e available_quantity non possono essere aggiornati in modo incrementale perché rappresentano un inventario a livello di prodotto, anziché informazioni a livello di luogo. Inoltre, potrebbe essere opportuno emettere aggiornamenti non incrementali a fulfillment_info anziché solo modifiche incrementali. In questi casi, è consigliato il metodo SetInventory.

Java

Per scoprire come installare e utilizzare la libreria client per Vertex AI Search per il retail, consulta Vertex AI Search per le librerie client per il retail. Per maggiori informazioni, consulta la documentazione di riferimento dell'API Vertex AI Search per la vendita al dettaglio Java.

Per eseguire l'autenticazione in Vertex AI Search per la vendita al dettaglio, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

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
  }

In questa richiesta specifica, i campi SetInventoryRequest.product.fulfillment_info sono descrizioni complete degli ID luogo idonei di ciascun tipo di evasione, anziché specifiche incrementali. L'aggiornamento a "same-day-delivery" indica che nessun ID luogo è idoneo per questo tipo di evasione degli ordini per questo prodotto. Tutti gli altri tipi di evasione non vengono aggiornati in questa richiesta. Pertanto, questo metodo può essere utilizzato per sostituire gli ID luogo solo per un sottoinsieme di tipi di evasione degli ordini, lasciando invariati gli altri tipi.

Per impostazione predefinita,SetInventory aggiornerà tutti i campi dell'inventario se SetInventory.set_mask non viene configurato o se è vuoto. Se la maschera non è vuota o se un campo dell'inventario non è elencato esplicitamente in SetInventoryRequest.set_mask, qualsiasi valore specificato per il campo dell'inventario in questione verrà ignorato nella richiesta di aggiornamento.

Come per gli aggiornamenti incrementali, il campo SetInventoryRequest.set_time può essere utilizzato per impostare un orario di aggiornamento rispetto all'ora dell'ultimo aggiornamento registrato di tutti i campi dell'inventario aggiornati.

Protezioni per i timestamp per gli aggiornamenti dell'inventario

Esistono diversi percorsi per aggiornare i campi di inventario di un prodotto e, per proteggerti dagli aggiornamenti non in ordine, ogni campo dell'inventario è associato a un orario di aggiornamento più recente.

L'ora dell'ultimo aggiornamento viene registrata per price_info, availability, available_quantity e ogni coppia di (fulfillment_info.place_ids, fulfillment_info.type).

I metodi AddFulfillmentPlaces, RemoveFulfillmentPlaces e SetInventory consentono al chiamante di specificare un orario di aggiornamento per l'invio della richiesta. La data e l'ora di aggiornamento vengono confrontate con l'ora di aggiornamento più recente registrata per i campi dell'inventario pertinenti e l'aggiornamento viene impegnato solo se l'ora dell'aggiornamento è successiva a quella dell'ultimo aggiornamento.

Ad esempio, supponiamo che per l'ID luogo "store1" sia attivato il tipo di evasione degli ordini "pickup-in- store" e che l'ora dell'ultimo aggiornamento registrato sia impostata sull'ora T. Se RemoveFulfillmentPlacesRequest.type = "pickup-in-store" e RemoveFulfillmentPlacesRequest.place_ids contengono "store1", la richiesta annullerà "pickup-in-store" da "store1" se e solo se RemoveFulfillmentPlacesRequest.remove_time è successiva all'ora T. Lo stesso vale per AddFulfillmentPlacesRequests.

SetInventory funziona in modo simile per l'aggiornamento di price_info, availability e available_quantity. Durante l'aggiornamento di fulfillment_info, un SetInventoryRequest chiede implicitamente di aggiungere tutti gli ID luogo specificati per un determinato tipo di evasione degli ordini e di rimuovere tutti gli ID luogo esistenti non specificati.

Pertanto, quando SetInventoryRequest viene elaborato, l'aggiornamento fulfillment_info viene implicitamente convertito in AddFulfillmentPlacesRequest e RemoveFulfillmentPlacesRequest per ogni tipo di evasione specificato. Ciò significa che se per qualsiasi luogo esistente "store1" con fulfillment "pickup-in-store" la data/ora dell'ultimo aggiornamento T è più recente di SetInventoryRequest.set_time, l'aggiunta/rimozione implicita su "store1" e "pickup-in-store" non verrà applicata.

Precarica le informazioni sull'inventario

Ciascuno dei metodi di aggiornamento dell'inventario consente al chiamante di impostare allow_missing nella richiesta. Quando il criterio allow_missing viene impostato su true, l'aggiornamento dell'inventario a un Product inesistente verrà elaborato come se il Product esistesse in base alle specifiche del metodo. Le informazioni sull'inventario verranno conservate per un massimo di due giorni se il Product corrispondente non viene creato tramite CreateProduct entro questo periodo di tempo.

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 utilizzare i metodi Product

Sebbene sia possibile aggiornare i campi di inventario con i metodi CRUD del prodotto, il chiamante deve essere esplicitamente consapevole degli effetti sulle informazioni di inventario esistenti o preesistenti.

Si tratta di metodi sincroni, il che significa che le ottimizzazioni downstream utilizzate per i metodi di inventario non vengono applicate e potrebbe essere costoso affidarsi a questi metodi per aggiornamenti frequenti dell'inventario. Se possibile, preferisci usare i metodi di aggiornamento dell'inventario sopra indicati.

CreateProduct

Quando viene richiamato il valore CreateProduct con uno qualsiasi dei campi dell'inventario impostati, i valori forniti in CreateProductRequest.product sostituiranno tutti i valori precaricati per i rispettivi campi. Se non vengono impostati campi sull'inventario, verranno utilizzate automaticamente tutte le informazioni preesistenti sull'inventario.

Inoltre, l'ora dell'ultimo aggiornamento dei campi dell'inventario sottoposti a override verrà reimpostata sull'ora della chiamata al metodo.

CreateProduct con inventario precaricato

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

In questo esempio, per il prodotto creato non sono stati impostati campi di inventario, il che significa che le informazioni sull'inventario precaricate verranno utilizzate automaticamente se aggiornate con i metodi di aggiornamento dell'inventario. Questo può essere utile quando gli aggiornamenti dell'inventario sono disaccoppiati dagli aggiornamenti del catalogo e vuoi che un elemento Product appena creato venga sincronizzato con qualsiasi informazione preesistente sull'inventario.

CreateProduct con inventario esplicito

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"
    }
  }
}

In questo esempio, viene creato un Product con campi di inventario impostati esplicitamente. Questi campi sostituiranno tutti i valori preesistenti, ignorando l'ora dell'ultimo aggiornamento dei campi corrispondenti. Di conseguenza, per la risorsa Product appena creata la disponibilità sarà impostata su OUT_OF_STOCK, nessun ID luogo supporterà i tipi di evasione degli ordini "pickup-in-store" e "same-day-delivery".

CreateProduct con informazioni sull'inventario può essere utile se non hai la certezza che tutte le informazioni precaricate sull'inventario siano accurate e preferisci impostare esplicitamente l'inventario al momento della creazione (Product) in modo da sincronizzare completamente il catalogo e l'inventario.

UpdateProduct

Quando viene richiamato UpdateProduct e la maschera del campo UpdateProductRequest.update_mask contiene campi di inventario, i valori forniti in UpdateProductRequest.product sostituiranno tutti i valori precaricati per i rispettivi campi.

Inoltre, l'ora dell'ultimo aggiornamento dei campi dell'inventario sottoposti a override verrà reimpostata sull'ora della chiamata al metodo.

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"
  }
}

Questo esempio è molto simile all'esempio SetInventory, ad eccezione del fatto che l'applicazione dell'aggiornamento è garantita indipendentemente dall'ora dell'ultimo aggiornamento di ogni campo dell'inventario.

UpdateProduct per l'inventario può essere utile quando è necessaria una sincronizzazione completa delle informazioni sull'inventario, ignorando le protezioni del timestamp.

Sebbene sia possibile precaricare le informazioni sull'inventario utilizzando UpdateProduct impostando UpdateProductRequest.allow_missing su true per eseguire un aumento superiore di Product, il metodo richiede di impostare campi di catalogo specifici come UpdateProductRequest.product.title. Di conseguenza, consigliamo di usare i metodi di aggiornamento dell'inventario per precaricare i casi d'uso.

DeleteProduct

Quando viene richiamato il valore DeleteProduct, verranno eliminate tutte le informazioni esistenti sull'inventario per il prodotto specificato in DeleteProductRequest.name, inclusi tutti i record relativi all'ora dell'ultimo aggiornamento per ogni campo dell'inventario.