Aggiornare l'inventario locale per Vertex AI Search for Commerce

AddLocalInventories

AddLocalInventories può essere utilizzato per creare inventari locali in nuove sedi (rappresentate da nuovi place_id) o 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 add_mask validi 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 un nome di attributo esistente, l'attributo viene eliminato. È possibile specificare più attributes.PLACEHOLDER_NAME, purché ogni nome di 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 supportati. I tipi di evasione esistenti che non sono 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 da LocalInventory di store1 esistente, se presente. L'attributo attr1 di store2 verrà impostato sul valore di testo store2_value. Gli altri attributi personalizzati esistenti su store1 e store2 rimangono invariati.

fulfillment_types rappresenta un elenco di disponibilità di evasione per un Product in un unico luogo. È uguale e accetta gli stessi valori di fulfillment_info.type. Questo AddLocalInventoriesRequest specifica che store1 supporta i tipi di evasione 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 ancora, le informazioni sull'inventario locale aggiornate verranno memorizzate per quando il prodotto verrà creato. L'aggiornamento è contrassegnato con il timestamp AddLocalInventoriesRequest.add_time per evitare che gli aggiornamenti obsoleti sovrascrivano i campi specificati di questi ID luogo. Per saperne di più su come evitare aggiornamenti obsoleti 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 l'ID luogo "store3" per il prodotto specificato. Poiché il suo 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, il prodotto specificato deve esistere. In caso contrario, viene generato un errore NOT_FOUND.

RemoveLocalInventories

RemoveLocalInventories può essere utilizzato per rimuovere gli inventari locali esistenti in luoghi 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 di 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 obsoleti sostituiscano l'eliminazione di questi ID luogo. Per gli ID luogo specificati senza inventari locali esistenti, la richiesta registra anche l'ora di aggiornamento su remove_time. Per saperne di più sui timestamp degli aggiornamenti, vedi Protezioni dei timestamp per gli aggiornamenti dell'inventario locale

Protezioni dei timestamp per gli aggiornamenti dell'inventario locale

Per proteggere dagli aggiornamenti fuori ordine, ogni campo dell'inventario locale è associato a 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 al chiamante di specificare un orario di aggiornamento per l'emissione della 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 il luogo con ID "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 è successivo all'ora T. Lo stesso vale per i RemoveLocalInventoriesRequest.

In Protezione timestamp, è possibile che un RemoveLocalInventoriesRequest rimuova solo determinati campi di un LocalInventory anziché tutti. Supponiamo che un inventario locale con ID luogo "store1" abbia price_info con l'ultima ora di aggiornamento registrata impostata sull'ora T1 e che l'unico attributo personalizzato esistente con nome "attr1" abbia l'ultima ora di aggiornamento registrata alle ore T2. Se un RemoveLocalInventoriesRequest.place_ids contiene "store1" e ha remove_time impostato su T3 (dove T1 < T3 < T2), allora store_1's price_info verrà rimosso, mentre il suo 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. Quando allow_missing è impostato su true, un aggiornamento dell'inventario locale a un Product inesistente viene elaborato come se il Product esistesse in base alle specifiche del metodo. Le informazioni sull'inventario locale verranno conservate per un massimo di due giorni se il Product corrispondente non viene creato utilizzando CreateProduct entro questo periodo di tempo.