Aggiornare l'inventario per Vertex AI Search per il retail

Sebbene i metodi CRUD (Create, Read, Update, Delete) di Product vengano utilizzati per modificare in modo generale gli attributi di un 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 inviare aggiornamenti dell'inventario utilizzando il metodo SetInventory anziché aggiornare l'intero prodotto.

Per seguire una guida passo passo per questa attività direttamente nel Editor di Cloud Shell, fai clic su Procedura guidata:

Procedura guidata

Tutorial sull'aggiunta di fulfillment

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

Questo tutorial mostra come aggiornare le informazioni di evasione degli ordini dei prodotti utilizzando il metodo AddFulfillmentPlaces. In questo modo, la ricerca può mostrare gli aggiornamenti relativi ai prodotti disponibili e ai relativi ordini. Ad esempio, un acquirente sta cercando jeans blu in un negozio, ma non sono disponibili. Nel momento in cui i jeans sono di nuovo disponibili in questo o in un altro negozio, lo shopper vede gli aggiornamenti e può procedere con il suo ordine.

Per seguire una guida passo passo per questa attività direttamente nel Editor di Cloud Shell, fai clic su Procedura guidata:

Procedura guidata

Tutorial sulla rimozione dei luoghi di evasione degli ordini

Ti consigliamo di utilizzare il metodo RemoveLocalInventories anziché RemoveFulfillmentPlaces. RmoveLocalInventories ottiene gli stessi risultati ma offre un controllo più granulare sull'importazione dei dati di inventario locale. Per ulteriori informazioni, 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 for Retail può mostrare aggiornamenti per le quali i prodotti non sono disponibili e gli ordini non può essere completato. In questo modo, la rete di ricerca può mostrare aggiornamenti relativi ai prodotti non disponibili e agli ordini che non possono essere evasi. Ad esempio, un acquirente sta cercando jeans blu in un negozio. Se i jeans non sono più disponibili in questo negozio, l'acquirente vede questo messaggio e non può procedere con l'ordine.

Per seguire una guida passo passo per questa attività direttamente nel Editor di Cloud Shell, fai clic su Procedura guidata:

Procedura guidata

Metodi di aggiornamento dell'inventario

Le modifiche alle informazioni sull'inventario di un prodotto possono avvenire molto più spesso di modifiche alle informazioni del catalogo. Di conseguenza, un insieme 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 compromettere le prestazioni.

Aggiornamenti incrementali

Tieni presente che consigliamo di seguire la guida agli aggiornamenti dell'inventario locale per emettere aggiornamenti incrementali dell'inventario. I metodi API più recenti offrono un controllo più granulare per gli attributi dell'inventario per località.

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 può cambiare e puoi decidere di pubblicare aggiornamenti che descrivono questa variazione anziché utilizzare il metodo UpdateProduct per specificare di nuovo le informazioni di evasione degli ordini dell'intero prodotto.

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

Java

Per scoprire come installare e utilizzare la libreria client per Vertex AI Search for Retail, consulta Vertex AI Search per le librerie client retail Per ulteriori informazioni, consulta API Java Vertex AI Search for Retail documentazione di riferimento.

Per autenticarti in Vertex AI Search per il retail, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura 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
  }

Questo esempio AddFulfillmentPlacesRequest aggiunge il tipo di evasione"pickup-in-store" agli ID posizione "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 al momento della creazione del prodotto. L'aggiornamento è contrassegnato con data e ora AddFulfillmentPlacesRequest.add_time per evitare la sostituzione di aggiornamenti inattivi lo stato di evasione di questi ID luogo. Queste funzionalità sono descritte in maggiore dettaglio nelle sezioni seguenti.

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

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

Aggiornamenti non incrementali

price_info, availability e available_quantity non possono essere aggiornati in modo incrementale perché rappresentano l'inventario a livello di prodotto, anziché le informazioni a livello di luogo. Inoltre, potrebbe essere opportuno emettere valori non incrementali aggiornamenti 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 Librerie client di Vertex AI Search per il retail. Per ulteriori informazioni, consulta API Java Vertex AI Search for Retail documentazione di riferimento.

Per autenticarti in Vertex AI Search per il retail, configura le 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, SetInventoryRequest.product.fulfillment_info sono descrizioni complete degli ID luogo idonei di ogni tipo di evasione degli ordini, a differenza delle specifiche incrementali. L'aggiornamento a "same-day-delivery" indica che nessun ID luogo è idoneo per questo tipo di evasione ordine per questo prodotto. Tutti gli altri tipi di adempimento 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, lasciando invariati gli altri tipi.

Per impostazione predefinita,SetInventory aggiorna tutti i campi dell'inventario seSetInventory.set_mask non è impostato o è vuoto. Se la maschera non è vuota o se campo inventario non è elencato in modo esplicito in SetInventoryRequest.set_mask, quindi qualsiasi valore specificato per il campo dello spazio pubblicitario verrà ignorato nell'aggiornamento richiesta.

Come per gli aggiornamenti incrementali, il campo SetInventoryRequest.set_time può essere utilizzato per impostare un'ora di aggiornamento che verrà confrontata con l'ora dell'ultimo aggiornamento registrato di tutti i campi dell'inventario aggiornati.

Protezioni dei timestamp per gli aggiornamenti dell'inventario

Esistono diversi percorsi per aggiornare i campi dell'inventario di un prodotto e per per evitare aggiornamenti non in ordine, ogni campo dell'inventario è associato a un data e ora dell'ultimo aggiornamento.

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

I metodi AddFulfillmentPlaces, RemoveFulfillmentPlaces e SetInventory consentono all'utente che chiama di specificare un'ora di aggiornamento per il momento in cui viene emessa la richiesta. L'ora di aggiornamento viene confrontata con data e ora dell'ultimo aggiornamento registrate per i campi pertinenti dell'inventario e l'aggiornamento impegnata solo se l'ora dell'aggiornamento è rigorosamente successiva all'ultimo aggiornamento nel tempo.

Ad esempio, supponiamo che per l'ID luogo "store1" sia attivato il tipo di evasione "pickup-in- store", con l'ora dell'ultimo aggiornamento registrato impostata sull'ora T. Se RemoveFulfillmentPlacesRequest.type = "pickup-in-store" e RemoveFulfillmentPlacesRequest.place_ids contengono "store1", la richiesta eliminerà "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. Quando aggiorni fulfillment_info, un SetInventoryRequest chiede implicitamente di aggiungere tutti gli ID luogo specificati per un determinato tipo di evasione e di rimuovere tutti gli ID luogo esistenti non specificati.

In questo modo, quando SetInventoryRequest viene elaborato, l'aggiornamento fulfillment_info viene implicitamente convertito in un AddFulfillmentPlacesRequest RemoveFulfillmentPlacesRequest per ogni tipo di evasione specificato. Ciò significa che se un luogo esistente "store1" con evasione "pickup-in-store" ha un'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 in la richiesta. Se il criterio allow_missing viene impostato su true, l'inventario viene aggiornato in Product inesistente verrà elaborato come se esistesse Product in base a le specifiche del metodo. Le informazioni sull'inventario verranno conservate per al massimo due giorni se il valore Product corrispondente non viene creato tramite CreateProduct in 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 dell'inventario con i metodi CRUD di Product, 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 si applicano e potrebbe essere costoso fare affidamento su questi metodi per aggiornamenti frequenti dell'inventario. Ove possibile, consigliamo di utilizzare metodi di aggiornamento dell'inventario indicati sopra.

CreateProduct

Quando CreateProduct viene richiamato con qualsiasi campo dell'inventario impostato, i valori forniti in CreateProductRequest.product sostituiranno qualsiasi valori precaricati per i rispettivi campi. Se non vengono impostati campi per l'inventario, le informazioni esistenti sull'inventario verranno utilizzate automaticamente.

Inoltre, l'ora dell'ultimo aggiornamento per i campi dell'inventario sostituito verrà viene reimpostato 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 impostati campi di inventario, il che significa che tutte le informazioni di inventario precaricate verranno utilizzate automaticamente se aggiornate utilizzando i metodi di aggiornamento dell'inventario. Questa operazione può essere utile quando gli aggiornamenti dell'inventario sono disaccoppiati dagli aggiornamenti del catalogo e vuoi sincronizzare un Product appena creato con le informazioni di inventario preesistenti.

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 creata una Product con campi dell'inventario impostati esplicitamente. Questi campi sostituiranno eventuali valori preesistenti, ignorando l'ora dell'ultimo aggiornamento per i campi corrispondenti. Pertanto, per Product appena creato è garantito che la disponibilità sia impostata su OUT_OF_STOCK e che nessun ID luogo supporti i tipi di evasione "pickup-in-store" e "same-day-delivery".

CreateProduct con informazioni sull'inventario può essere utile se non lo sei verificare che tutte le informazioni sull'inventario precaricate siano accurate e preferire Impostare esplicitamente l'inventario al momento della creazione del giorno Product per eseguire la sincronizzazione completa catalogo e inventario.

UpdateProduct

Quando viene invocato UpdateProduct e la maschera di campo UpdateProductRequest.update_mask contiene campi di inventario, i valori forniti in UpdateProductRequest.product sovrascriveranno eventuali valori precaricati per i rispettivi campi.

Inoltre, l'ora dell'ultimo aggiornamento per i campi dell'inventario sostituiti 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, tranne per il fatto che l'aggiornamento è garantito indipendentemente dall'ora dell'ultimo aggiornamento di ciascun campo dell'inventario.

UpdateProduct per l'inventario può essere utile quando viene eseguita una sincronizzazione completa dell'inventario necessarie, ignorando le protezioni timestamp.

Sebbene sia possibile precaricare le informazioni sull'inventario utilizzando UpdateProduct imposta UpdateProductRequest.allow_missing su true per eseguire Product eseguire l'upsert, il metodo richiede l'impostazione di campi del catalogo specifici come UpdateProductRequest.product.title. Pertanto, ti consigliamo di utilizzare i metodi di aggiornamento dell'inventario per i casi d'uso di precaricamento.

DeleteProduct

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