Aggiorna l'inventario per Retail

Anche se i metodi Product per la creazione, la lettura, l'aggiornamento e l'eliminazione (CRUD) vengono utilizzati per modificare rapidamente gli attributi di un Product, è disponibile un insieme di metodi Product per l'aggiornamento di 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 istruzioni 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 dei prodotti disponibili localmente. Per ulteriori informazioni, consulta la documentazione di AddLocalInventories.

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

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

Procedura guidata

Tutorial sulla rimozione di fulfillment

Ti consigliamo di utilizzare il metodo RemoveLocalInventories anziché RemoveFulfillmentPlaces. RmoveLocalInventories ottiene gli stessi risultati, ma offre un controllo più granulare sull'importazione dei dati dei prodotti disponibili localmente. Per ulteriori informazioni, consulta la documentazione di RemoveLocalInventories.

Questo tutorial mostra come aggiornare le informazioni di evasione dei prodotti utilizzando il metodo RemoveFulfillmentPlaces. In questo modo, Retail può mostrare gli aggiornamenti in cui i prodotti non sono disponibili e gli ordini non possono essere gestiti. Ad esempio, un acquirente sta cercando dei jeans blu in un negozio. Se i jeans non sono più disponibili in questo negozio, Retail mostra gli aggiornamenti e l'acquirente non può procedere con l'ordine.

Per seguire le istruzioni 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 possono avvenire molto più spesso rispetto alle modifiche 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 emettere aggiornamenti incrementali dell'inventario. I metodi API più recenti offrono 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 può variare. Puoi decidere di emettere aggiornamenti che descrivono questa modifica anziché utilizzare il metodo UpdateProduct per specificare nuovamente le informazioni di evasione dell'intero prodotto.

In questi casi, i metodi AddFulfillmentPlaces e RemoveFulfillmentPlaces possono essere utilizzati per aggiornare in modo incrementale le modifiche di evasione di un prodotto in base agli ID luogo che vengono aggiunti o rimossi per un determinato tipo di evasione degli ordini.

Java

Per scoprire come installare e utilizzare la libreria client per Retail, consulta Librerie client di Retail. Per scoprire di più, consulta la documentazione di riferimento per l'API Retail Java.

Per eseguire l'autenticazione nel settore retail, configura le Credenziali predefinite dell'applicazione. Per saperne di più, 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
  }

Questo esempio AddFulfillmentPlacesRequest aggiunge il tipo di evasione "pickup-in-store" per inserire gli ID "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 la creazione del prodotto. L'aggiornamento è contrassegnato con AddFulfillmentPlacesRequest.add_time per evitare che gli aggiornamenti inattivi sostituiscano lo stato di evasione di questi ID luogo. Queste funzionalità sono illustrate 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 specifico a un elenco di ID luogo che supporta ogni tipo. Entrambi i tipi di API stanno modificando 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é le informazioni a livello di luogo. Inoltre, potrebbe essere opportuno inviare 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 Retail, consulta Librerie client di Retail. Per scoprire di più, consulta la documentazione di riferimento per l'API Retail Java.

Per eseguire l'autenticazione nel settore retail, configura le Credenziali predefinite dell'applicazione. Per saperne di più, 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 ogni tipo di evasione degli ordini, anziché specifiche incrementali. L'aggiornamento a "same-day-delivery" indica che nessun ID luogo è idoneo per questo tipo di evasione per questo prodotto. Tutti gli altri tipi di evasione non sono aggiornati in questa richiesta. Di conseguenza, puoi utilizzare questo metodo per sostituire gli ID posizione solo per un sottoinsieme di tipi di evasione, lasciando intatti 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 espressamente 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 orario che corrisponderà all'ora dell'ultimo aggiornamento registrato di tutti i campi aggiornati dell'inventario.

Protezioni timestamp per gli aggiornamenti dell'inventario

Esistono diversi percorsi per aggiornare i campi dell'inventario di un prodotto e, per proteggerli da aggiornamenti fuori ordine, ogni campo dell'inventario è associato a un'ora di aggiornamento più recente.

Viene registrata l'ora dell'ultimo aggiornamento 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'ora di aggiornamento per l'emissione della richiesta. L'ora dell'aggiornamento viene confrontata con l'ora dell'ultimo aggiornamento registrata per i campi dell'inventario pertinenti e viene eseguita solo se l'ora dell'aggiornamento è rigorosamente 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'ora dell'ultimo aggiornamento registrata impostata su 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 è 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 richiede implicitamente l'aggiunta di tutti gli ID luogo specificati per un determinato tipo di evasione e rimuove tutti gli ID luogo esistenti non specificati.

Di conseguenza, quando SetInventoryRequest viene elaborato, l'aggiornamento di fulfillment_info viene convertito implicitamente in AddFulfillmentPlacesRequest e RemoveFulfillmentPlacesRequest per ogni tipo di evasione specificato. Ciò significa che se qualsiasi 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 dell'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 Product non elaborato viene elaborato come se il Product fosse esistente secondo le specifiche del metodo. Le informazioni sull'inventario verranno conservate per un massimo di due giorni se il corrispondente Product 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 dell'inventario con i metodi CRUD di prodotto, il chiamante deve essere esplicitamente a conoscenza degli effetti sulle informazioni di inventario esistenti o preesistenti.

Si tratta di metodi sincroni, il che significa che le ottimizzazioni a valle utilizzate per i metodi di inventario non si applicano e potrebbe diventare costoso affidarsi a questi metodi per aggiornamenti frequenti dell'inventario. Dove possibile, utilizza i metodi di aggiornamento dell'inventario indicati in precedenza.

CreateProduct

Quando il campo CreateProduct viene richiamato con qualsiasi campo dell'inventario impostato, i valori forniti in CreateProductRequest.product sostituiscono eventuali valori precaricati per i rispettivi campi. Se non è impostato alcun campo dell'inventario, vengono utilizzate automaticamente tutte le informazioni sull'inventario preesistenti.

Inoltre, l'ultimo aggiornamento dei campi dell'inventario sovrascritto verrà reimpostato sull'ora della chiamata del 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 qualsiasi informazione di inventario precaricata verrà utilizzata automaticamente se aggiornata utilizzando i metodi di aggiornamento dell'inventario. Ciò può essere utile quando gli aggiornamenti dell'inventario sono disaccoppiati dagli aggiornamenti del catalogo e vuoi che una Product appena creata venga sincronizzata con eventuali 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 creato un Product con campi di inventario impostati esplicitamente. Questi campi sostituiscono eventuali valori preesistenti, ignorando l'ora dell'ultimo aggiornamento per i campi corrispondenti. Pertanto, la disponibilità di Product nuovi elementi è garantita per la disponibilità impostata su OUT_OF_STOCK e 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 sull'inventario precaricate siano precise e preferisci impostare esplicitamente l'inventario al momento della creazione per Product per 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 specificati in UpdateProductRequest.product sostituiscono tutti i valori precaricati per i rispettivi campi.

Inoltre, l'ultimo aggiornamento dei campi dell'inventario sovrascritto verrà reimpostato sull'ora della chiamata del 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 viene garantito per essere applicato indipendentemente dall'ora dell'ultimo aggiornamento di ciascun campo dell'inventario.

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

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

DeleteProduct

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