Aggiornare l'inventario per Vertex AI Search for Commerce

Mentre i metodi di creazione, lettura, aggiornamento ed eliminazione (CRUD) di Product vengono utilizzati per modificare in modo generico 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 invece di aggiornare l'intero prodotto.

Per seguire le indicazioni dettagliate per questa attività direttamente nell'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 saperne di più, 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 in cui i prodotti sono disponibili e gli ordini possono essere evasi. Ad esempio, un acquirente sta cercando jeans blu in un negozio, ma sono esauriti. Nel momento in cui i jeans tornano 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 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 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 for Commerce può mostrare gli aggiornamenti in cui i prodotti non sono disponibili e gli ordini non possono essere evasi. In questo modo, la ricerca può mostrare aggiornamenti in cui i prodotti non sono disponibili e gli ordini 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 lo vede e non può procedere con l'ordine.

Per seguire le indicazioni dettagliate per questa attività direttamente nell'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 potrebbero avvenire molto più spesso rispetto a quelle relative alle informazioni del catalogo. Pertanto, viene fornito un insieme specializzato di metodi 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 è consigliabile seguire la guida agli aggiornamenti dell'inventario locale per eseguire aggiornamenti incrementali dell'inventario. I metodi API più recenti forniscono un controllo più granulare per gli attributi dell'inventario per luogo.

fulfillment_info viene spesso utilizzato per codificare la disponibilità dell'evasione 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 pubblicare aggiornamenti che descrivono questa modifica anziché utilizzare il metodo UpdateProduct per specificare di nuovo tutte le informazioni relative all'evasione degli ordini del 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 aggiunti o rimossi per un determinato tipo di evasione.

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

  {
    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 luogo "store0" e "store1" per il prodotto specificato. Poiché AddFulfillmentPlacesRequest.allow_missing è impostato su true, anche se il prodotto non esiste ancora, le informazioni sull'inventario aggiornate verranno memorizzate per quando il prodotto verrà creato. L'aggiornamento è contrassegnato con il timestamp AddFulfillmentPlacesRequest.add_time per evitare che gli aggiornamenti obsoleti sostituiscano lo stato di evasione di questi ID luogo. Queste funzionalità sono descritte in maggior 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 che supporta. 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 supportano ogni tipo. Entrambi i tipi di API modificano le stesse informazioni di evasione 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 l'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.

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

  {
    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 ogni tipo di evasione, anziché specifiche incrementali. L'aggiornamento di "same-day-delivery" indica che nessun ID luogo è idoneo per questo tipo di evasione 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, lasciando invariati gli altri tipi.

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

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 registrata 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 proteggere dagli aggiornamenti fuori ordine, ogni campo dell'inventario è associato a un'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 al chiamante di specificare un'ora di aggiornamento per il momento in cui viene emessa la richiesta. Questa ora di aggiornamento viene confrontata con l'ora dell'ultimo aggiornamento registrata per i campi dell'inventario pertinenti e l'aggiornamento viene eseguito solo se l'ora di aggiornamento è strettamente successiva all'ora dell'ultimo aggiornamento.

Ad esempio, supponiamo che l'ID luogo "store1" abbia il tipo di evasione "pickup-in- store" abilitato, con l'ultimo orario di aggiornamento registrato impostato sull'ora T. Se RemoveFulfillmentPlacesRequest.type = "pickup-in-store" e RemoveFulfillmentPlacesRequest.place_ids contengono "store1", la richiesta cancellerà "pickup-in-store" da "store1" se e solo se RemoveFulfillmentPlacesRequest.remove_time è successivo 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, una 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.

Pertanto, quando viene elaborato SetInventoryRequest, l'aggiornamento fulfillment_info viene convertito implicitamente in AddFulfillmentPlacesRequest e RemoveFulfillmentPlacesRequest per ogni tipo di evasione degli ordini 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.

Precaricare le informazioni sull'inventario

Ciascuno dei metodi di aggiornamento dell'inventario consente al chiamante di impostare allow_missing nella richiesta. Quando allow_missing è impostato su true, un 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.

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 dei prodotti, il chiamante deve essere esplicitamente consapevole degli effetti sulle informazioni di inventario esistenti o preesistenti.

Questi sono metodi sincroni, il che significa che le ottimizzazioni downstream utilizzate per i metodi di inventario non si applicano e potrebbe diventare costoso fare affidamento su questi metodi per aggiornamenti frequenti dell'inventario. Ove possibile, preferisci utilizzare i metodi di aggiornamento dell'inventario sopra menzionati.

CreateProduct

Quando CreateProduct viene richiamato con i campi dell'inventario impostati, i valori forniti in CreateProductRequest.product sostituiranno i valori precaricati per i rispettivi campi. Se non sono impostati campi di inventario, vengono utilizzate automaticamente le informazioni di inventario preesistenti.

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

CreateProduct con inventario precaricato

{
  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, il prodotto creato non ha impostato alcun campo inventario, il che significa che tutte le informazioni sull'inventario precaricate verranno utilizzate automaticamente se aggiornate utilizzando i metodi di aggiornamento dell'inventario. Ciò può essere utile quando gli aggiornamenti dell'inventario sono separati dagli aggiornamenti del catalogo e vuoi che un Product appena creato si sincronizzi con le informazioni sull'inventario preesistenti.

CreateProduct con inventario esplicito

{
  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 dell'inventario impostati in modo esplicito. Questi campi sovrascriveranno tutti i valori preesistenti, ignorando l'ora dell'ultimo aggiornamento per i campi corrispondenti. Pertanto, è garantito che il nuovo Product abbia la disponibilità impostata su OUT_OF_STOCK e nessun ID luogo supporterà i tipi di evasione "pickup-in-store" e "same-day-delivery".

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

UpdateProduct

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

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

{
  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 deve essere applicato 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 dei timestamp.

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

DeleteProduct

Quando viene richiamato 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 dell'inventario.