Questa è la documentazione di Recommendations AI, Retail Search e la nuova console di Retail.

Aggiornare i prodotti disponibili localmente per la vendita al dettaglio

LocalInventory è l'inventario associato ai dati di un determinato elemento, identificato da un place_id. Ad esempio, un elemento LocalInventory potrebbe essere creato per un negozio o per un'area geografica in cui è disponibile un determinato prezzo. LocalInventory ha 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 fino al giorno Product.fulfillment_info). Questo campo è solo di output. L'impostazione di Product.local_inventories per le API CRUD di Product o SetInventory non ha alcun effetto.

Ogni coppia di (LocalInventory.place_id, LocalInventory.fulfillment_types[...]) rimanda alla stessa coppia di (fulfillment_info.place_ids, fulfillment_info.type) indicata nella documentazione sull'aggiornamento dell'inventario. fulfillment_types aggiornato da AddLocalInventories e RemoveLocalInventories descritto di seguito riflette una mappatura di ogni ID luogo a un elenco di tipi di fulfillment supportati, mentre fulfillment_info aggiornato da AddFulfillmentPlaces e RemoveFulfillmentPlaces riflette una mappatura di ogni tipo di fulfillment specifico. Tuttavia, entrambi i tipi di API cambieranno le stesse informazioni di fulfillment sottostanti e l'effetto di entrambi i tipi di API si rifletterà su Product.fulfillment_info.

Metodi di aggiornamento dell'inventario locale

Le modifiche alle informazioni di inventario locale di un prodotto possono verificarsi molto più spesso delle modifiche ai dati del suo catalogo. È disponibile un set specializzato di metodi per gestire grandi volumi di aggiornamenti specifici dell'inventario locale. Questi metodi sono asincroni a causa delle ottimizzazioni downstream che supportano centinaia di aggiornamenti simultanei per prodotto, senza sacrificare le prestazioni.

AddLocalInventories

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

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

Proto

{
  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 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 deve essere aggiornato utilizzando i valori forniti in AddLocalInventoriesRequest.local_inventories.

attributes sono attributi associati a un luogo con nomi e valori personalizzabili. Poiché LocalInventory di store1 non fornisce il valore attr1 nella richiesta, l'attributo personalizzato attr1 verrà eliminato da LocalInventory di store1, se esistente. store2 avrà il valore dell'attributo attr1 come valore di testo impostato su store2_value. Gli altri attributi personalizzati esistenti in store1 e store2 non sono stati modificati.

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

Poiché AddLocalInventoriesRequest.allow_missing è impostato su true, anche se il prodotto non esiste già, le informazioni aggiornate sull'inventario locale verranno archiviate per il momento in cui il prodotto verrà creato. L'aggiornamento contiene un timestamp con AddLocalInventoriesRequest.add_time per evitare che gli aggiornamenti obsoleti vengano sostituiti dai campi specificati di questi ID luogo. Per saperne di più su come prevenire gli aggiornamenti in sospeso e archiviare 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.

Proto

{
  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é l'elemento add_mask contiene "attributes", tutti gli attributi personalizzati esistenti di store3 vengono eliminati e sostituiti con attr1 e attr2 come specificato nella richiesta. Poiché allow_missing non è impostato, è necessario che il prodotto specificato esista. In caso contrario, viene visualizzato un errore NOT_FOUND.

RemoveLocalInventories

RemoveLocalInventories può essere utilizzato per rimuovere gli inventari locali esistenti in luoghi con ID luogo specificati.

Proto

{
  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 ha un timestamp con RemoveLocalInventoriesRequest.remove_time, che impedisce che gli aggiornamenti in tempo reale sostituiscano l'eliminazione di questi ID luogo. Per gli ID luogo specificati privi di inventari locali esistenti, la richiesta ne registra anche l'ora di aggiornamento a remove_time. Per scoprire di più sui timestamp di aggiornamento, consulta Protezioni dei timestamp per gli aggiornamenti dei prodotti disponibili localmente

Protezioni del timestamp per gli aggiornamenti dei prodotti disponibili localmente

Per proteggerti da aggiornamenti fuori ordine, ogni campo di inventario locale è associato a una data di aggiornamento più recente.

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 al chiamante di specificare un'ora di aggiornamento per l'emissione della richiesta. L'ora di aggiornamento viene confrontata con l'ora dell'ultimo aggiornamento registrata per i campi dell'inventario pertinenti e l'aggiornamento viene confermato solo se l'ora dell'aggiornamento è successiva all'ora dell'ultimo aggiornamento.

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 RemoveLocalInventoriesRequest.remove_time è successiva al periodo T. Lo stesso vale per RemoveLocalInventoriesRequest.

Sotto la protezione del timestamp, è possibile che un elemento RemoveLocalInventoriesRequest possa rimuovere solo alcuni campi di un elemento LocalInventory invece di tutto. Supponiamo che un inventario locale con ID luogo "store1" abbia price_info con l'ora dell'ultimo aggiornamento registrato impostato sull'ora T1 e abbia l'unico attributo personalizzato esistente con nome "attr1" con ora dell'ultimo aggiornamento registrato alle ore T2. Se un elemento RemoveLocalInventoriesRequest.place_ids contiene "store1" e ha l'opzione remove_time impostata su T3 (dove T1 < T3 < T2), store_1 l'elemento price_info verrà rimosso, mentre l'attributo attr1 rimarrà intatto.

Precaricamento delle informazioni sull'inventario

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