Aggiornare l'inventario locale per Vertex AI Search per il retail

LocalInventory sono le informazioni sull'inventario associate a un determinato luogo, identificato dal relativo place_id. Ad esempio, è possibile creare un LocalInventory per un negozio o una regione in cui è disponibile un determinato prezzo. LocalInventory contiene i seguenti campi:

• LocalInventory.price_info
• LocalInventory.attributes
• LocalInventory.fulfillment_types

Le voci LocalInventory esistenti sono visibili tramite Product.local_inventories (ad eccezione di fulfillment_types che, per la compatibilità con le versioni precedenti, è disponibile tramite Product.fulfillment_info). Questo campo è solo di output. L'impostazione di Product.local_inventories per le API CRUD Product o SetInventory non ha alcun effetto.

Ogni coppia (LocalInventory.place_id, LocalInventory.fulfillment_types[...]) fa riferimento alla stessa (fulfillment_info.place_ids, fulfillment_info.type) coppia indicata nella documentazione relativa all'aggiornamento dell'inventario. fulfillment_types aggiornato da AddLocalInventories e RemoveLocalInventories descritto di seguito riflette una mappatura da ogni ID luogo a un elenco di tipi di evasione degli ordini supportati, mentre fulfillment_info aggiornato da AddFulfillmentPlaces e RemoveFulfillmentPlaces riflette una mappatura da ogni tipo di evasione degli ordini specifico a un elenco di ID luogo che supportano questo tipo. Tuttavia, entrambi i tipi di API modificano le stesse informazioni di evasione sottostanti e l'effetto di entrambi i tipi di API si rifletterà suProduct.fulfillment_info.

Metodi di aggiornamento dell'inventario locale

Le modifiche alle informazioni sull'inventario locale di un prodotto possono avvenire molto più frequentemente rispetto a quelle relative alle informazioni del catalogo. Viene fornito un insieme specializzato di metodi per gestire grandi volumi di aggiornamenti specifici per l'inventario locale. Questi metodi sono asincroni grazie alle ottimizzazioni downstream che supportano centinaia di aggiornamenti simultanei per prodotto senza compromettere le prestazioni.

AddLocalInventories

AddLocalInventories può essere utilizzato per creare inventari locali in nuovi luoghi (rappresentati con nuovi place_id) o per aggiornare i campi esistenti negli inventari locali esistenti. I campi aggiunti o aggiornati nell'elenco delle voci LocalInventory nel corpo della richiesta possono essere specificati tramite AddLocalInventoriesRequest.add_mask. I valori validi di add_mask sono:

• price_info: sovrascrive LocalInventory.price_info.
• attributes: sovrascrive tutti i LocalInventory.attributes. Gli attributi esistenti non menzionati nel corpo della richiesta vengono rimossi.
• attributes.PLACEHOLDER_NAME: sovrascrive solo l'attributo personalizzato specificato. Se nella richiesta non viene fornito il nome di un attributo esistente, l'attributo viene eliminato. È possibile specificare più attributes.PLACEHOLDER_NAME, purché ogni nome dell'attributo sia diverso. Tuttavia, AddLocalInventoriesRequest.add_mask non può includere sia il valore attributes sia i valori attributes.PLACEHOLDER_NAME nella stessa richiesta.
• fulfillment_types: sovrascrive tutti i tipi di evasione degli ordini supportati. I tipi di adempimento esistenti non menzionati nel corpo della richiesta vengono rimossi.

{
  product: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
  local_inventories: {
    place_id: "store1"
    price_info: {
      currency_code: "USD"
      price: 100
      original_price: 110
      cost: 95
    }
    fulfillment_types: "pickup-in-store"
    fulfillment_types: "ship-to-store"
  }
  local_inventories: {
    place_id: "store2"
    price_info: {
      currency_code: "USD"
      price: 200
      original_price: 210
      cost: 195
    }
    attributes: {
      key: "attr1",
      value: {
        text: "store2_value"
      }
    }
    fulfillment_types: "custom-type-1"
  }
  add_mask: {
    paths: "price_info"
    paths: "attributes.attr1"
    paths: "fulfillment_types"
  }
  add_time: {
    seconds: 100
    nanos: 100
  }
  allow_missing: true
}
  

Questo esempio AddLocalInventoriesRequest aggiunge o aggiorna due inventari locali con gli ID luogo "store1" e "store2" per il prodotto specificato. Se store1 esiste e store2 non esiste prima della richiesta, la richiesta aggiornerà i campi di store1 e creerà store2 con i valori dei campi specificati.

Questo AddLocalInventoriesRequest.add_mask specifica che price_info, un singolo attributo personalizzato con il nome "attr1" e fulfillment_types devono essere aggiornati utilizzando i valori forniti in AddLocalInventoriesRequest.local_inventories.

attributes sono attributi associati a un luogo con nome e valori personalizzabili. Poiché LocalInventory di store1 non fornisce il valore di attr1 nella richiesta, l'attributo personalizzato attr1 verrà eliminato dall'LocalInventory di store1 esistente, se esistente. Il valore dell'attributo attr1 di store2 sarà impostato su un valore di testo store2_value. Gli altri attributi personalizzati esistenti su store1 e store2 rimangono invariati.

fulfillment_types rappresenta un elenco della disponibilità di evasione per un Product in un'unica posizione. È lo stesso e accetta gli stessi valori di fulfillment_info.type. Questo AddLocalInventoriesRequest specifica che store1 supporta i tipi di evasione degli ordini pickup-in-store e ship-to-store, mentre store1 supporta custom-type-1. I tipi di evasione esistenti prima di questo aggiornamento che non sono menzionati nella richiesta verranno eliminati.

Poiché AddLocalInventoriesRequest.allow_missing è impostato su true, anche se il prodotto non esiste già, le informazioni sull'inventario locale aggiornate verranno memorizzate per quando il prodotto verrà finalmente creato. L'aggiornamento è datato con AddLocalInventoriesRequest.add_time per impedire che gli aggiornamenti obsoleti sostituiscano i campi specificati di questi ID luogo. Per scoprire di più su come evitare aggiornamenti inattivi e memorizzare le informazioni sull'inventario locale prima della creazione del prodotto, consulta Protezioni dei timestamp per gli aggiornamenti dell'inventario locale e Precaricamento delle informazioni sull'inventario.

{
  product: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
  local_inventories: {
    place_id: "store3"
    attributes: {
      key: "attr1",
      value: {
        text: "attr1_value"
      }
    }
    attributes: {
      key: "attr2",
      value: {
        numbers: 123
      }
    }
  }
  add_mask: {
    paths: "attributes"
  }
  add_time: {
    seconds: 100
    nanos: 100
  }
}
  

Questo esempio AddLocalInventoriesRequest aggiunge o aggiorna un singolo inventario locale con ID luogo "store3" per il prodotto specificato. Poiché add_mask contiene "attributes", tutti gli attributi personalizzati esistenti di store3 vengono eliminati e sostituiti con attr1 e attr2 come specificato nella richiesta. Tieni presente che, poiché allow_missing non è impostato, è necessario che il prodotto specificato esista. In caso contrario, viene generato un errore NOT_FOUND.

RemoveLocalInventories

RemoveLocalInventories può essere utilizzato per rimuovere gli inventari locali esistenti in località con ID luogo specifici.

{
  product: "projects/123/locations/global/catalogs/default_catalog/branches/default_branch/products/p123"
  place_ids: "store1"
  place_ids: "store2"
  remove_time: {
    seconds: 100
    nanos: 100
  }
  allow_missing: true
}
  

Questo esempio RemoveLocalInventoriesRequest rimuove gli inventari locali per i luoghi con ID luogo "store1" e "store2" per il prodotto specificato. L'aggiornamento è contrassegnato con il timestamp RemoveLocalInventoriesRequest.remove_time per evitare che gli aggiornamenti non aggiornati sostituiscano l'eliminazione di questi ID luogo. Per gli ID luogo specificati senza inventari locali esistenti, la richiesta registra anche il relativo momento di aggiornamento come remove_time. Per saperne di più sui timestamp degli aggiornamenti, consulta Protezioni dei timestamp per gli aggiornamenti dell'inventario locale

Protezioni dei timestamp per gli aggiornamenti dell'inventario locale

Per proteggerti dagli aggiornamenti fuori ordine, a ogni campo dell'inventario locale è associata un'ora dell'ultimo aggiornamento.

L'ora dell'ultimo aggiornamento viene registrata per ogni coppia (place_id, price_info), (place_id, attributes[...]) e (place_id, fulfillment_types[...]).

I metodi AddLocalInventories e RemoveLocalInventories consentono all'utente che effettua la chiamata di specificare un'ora di aggiornamento per il momento in cui viene emessa la richiesta. Questa ora di aggiornamento viene confrontata con l'ora di aggiornamento più recente registrata per i campi dell'inventario pertinenti e l'aggiornamento viene eseguito se e solo se l'ora di aggiornamento è successiva all'ora di aggiornamento più recente.

Ad esempio, supponiamo che l'ID luogo "store1" abbia price_info con l'ora dell'ultimo aggiornamento registrato impostata sull'ora T. Se RemoveLocalInventoriesRequest.place_ids contiene "store1", la richiesta rimuoverà price_info da "store1" solo se l'ora RemoveLocalInventoriesRequest.remove_time è successiva all'ora T. Lo stesso vale per i RemoveLocalInventoriesRequest.

In caso di protezione del timestamp, è possibile che un RemoveLocalInventoriesRequest rimuova solo alcuni campi di un LocalInventory anziché tutti. Supponiamo che un inventario locale con ID luogo "store1" abbia price_info con l'ora dell'ultimo aggiornamento registrato impostata sull'ora T1 e abbia il suo unico attributo personalizzato esistente con il nome "attr1" con l'ora dell'ultimo aggiornamento registrato su T2. Se un RemoveLocalInventoriesRequest.place_ids contiene "store1" e ha remove_time impostato su T3 (dove T1 < T3 < T2), then store_1's price_info verrà rimosso, mentre il suo attributo attr1 verrà mantenuto invariato.

Precaricamento delle informazioni sull'inventario

Ciascuno dei metodi di aggiornamento dell'inventario locale consente all'utente che effettua la chiamata di impostare allow_missing nella richiesta. Quando allow_missing è impostato su true, un aggiornamento dell'inventario locale a un Product inesistente viene elaborato come se Product esistesse in base alle specifiche del metodo. Le informazioni sull'inventario locale verranno conservate per un massimo di due giorni se il corrispondente Product non viene creato tramite CreateProduct entro questo periodo di tempo.