Lokales Inventar für Vertex AI Search for Commerce aktualisieren

LocalInventory sind die Inventarinformationen, die mit einem bestimmten Ort verknüpft sind, der durch seine place_id identifiziert wird. So könnte beispielsweise ein LocalInventory für ein Geschäft oder eine Region erstellt werden, in der ein bestimmter Preis verfügbar ist. LocalInventory hat die folgenden Felder:

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

Vorhandene LocalInventory-Einträge sind über Product.local_inventories sichtbar (mit Ausnahme von fulfillment_types, das aus Gründen der Abwärtskompatibilität über Product.fulfillment_info verfügbar ist). Dieses Feld dient nur der Ausgabe. Das Festlegen von Product.local_inventories für Product-CRUD-APIs oder SetInventory hat keine Auswirkungen.

Jedes (LocalInventory.place_id, LocalInventory.fulfillment_types[...])-Paar verweist auf dasselbe (fulfillment_info.place_ids, fulfillment_info.type)-Paar, das in der Dokumentation zu Inventaraktualisierungen erwähnt wird. fulfillment_types, aktualisiert von AddLocalInventories und RemoveLocalInventories, spiegelt eine Zuordnung von jeder Orts-ID zu einer Liste der unterstützten Auftragsausführungstypen wider, während fulfillment_info, aktualisiert von AddFulfillmentPlaces und RemoveFulfillmentPlaces, eine Zuordnung von jedem bestimmten Auftragsausführungstyp zu einer Liste von Orts-IDs widerspiegelt, die diesen Typ unterstützen. Beide API-Typen ändern jedoch dieselben zugrunde liegenden Informationen zur Erfüllung und die Auswirkungen beider API-Typen werden in Product.fulfillment_info berücksichtigt.

Methoden zur Aktualisierung des lokalen Inventars

Änderungen an den Informationen zum lokalen Inventar eines Produkts können wesentlich häufiger erfolgen als Änderungen an seinen Kataloginformationen. Es steht ein spezieller Satz von Methoden zur Verfügung, um große Mengen an inventarspezifischen Updates zu bewältigen. Diese Methoden sind asynchron aufgrund von nachgelagerten Optimierungen, die Hunderte von gleichzeitigen Aktualisierungen pro Produkt unterstützen, ohne die Leistung zu beeinträchtigen.

AddLocalInventories

Mit AddLocalInventories lassen sich lokale Inventare an neuen Orten (mit neuen place_id) erstellen oder vorhandene Felder in bestehenden lokalen Inventaren aktualisieren. Felder, die der Liste der LocalInventory-Einträge im Anfragetext hinzugefügt oder aktualisiert werden, können über AddLocalInventoriesRequest.add_mask angegeben werden. Gültige Werte für add_mask sind:

  • price_info: überschreibt LocalInventory.price_info.
  • attributes: überschreibt alle LocalInventory.attributes. Vorhandene Attribute, die nicht im Anfragetext erwähnt werden, werden entfernt.
  • attributes.PLACEHOLDER_NAME: Überschreibt nur das angegebene benutzerdefinierte Attribut. Wenn in der Anfrage kein vorhandener Attributname angegeben wird, wird das Attribut gelöscht. Es können mehrere attributes.PLACEHOLDER_NAME angegeben werden, sofern sich die Attributnamen voneinander unterscheiden. AddLocalInventoriesRequest.add_mask darf jedoch nicht sowohl den Wert attributes als auch die Werte attributes.PLACEHOLDER_NAME in derselben Anfrage enthalten.
  • fulfillment_types: Überschreibt alle unterstützten Auftragsausführungstypen. Vorhandene Auftragsausführungstypen, die nicht im Anfragetext erwähnt werden, werden entfernt.

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
}

In diesem Beispiel AddLocalInventoriesRequest werden zwei lokale Inventare mit den Orts-IDs "store1" und "store2" für das angegebene Produkt hinzugefügt oder aktualisiert. Wenn store1 vorhanden ist und store2 vor der Anfrage nicht vorhanden ist, werden durch die Anfrage die Felder von store1 aktualisiert und store2 mit den angegebenen Feldwerten erstellt.

Mit diesem AddLocalInventoriesRequest.add_mask wird angegeben, dass price_info, ein einzelnes benutzerdefiniertes Attribut mit dem Namen "attr1" und fulfillment_types mit den im AddLocalInventoriesRequest.local_inventories angegebenen Werten aktualisiert werden sollen.

attributes sind Attribute, die einem Ort zugeordnet sind und deren Name und Werte angepasst werden können. Da LocalInventory von store1 den Wert von attr1 in der Anfrage nicht enthält, wird das benutzerdefinierte Attribut attr1 aus dem vorhandenen LocalInventory von store1 gelöscht, sofern es vorhanden ist. Für store2 wird der Wert des Attributs attr1 auf den Textwert store2_value festgelegt. Andere vorhandene benutzerdefinierte Attribute für store1 und store2 bleiben unverändert.

fulfillment_types steht für eine Liste der Verfügbarkeit der Auftragsausführung für ein Product an einem einzelnen Ort. Es ist dasselbe und akzeptiert dieselben Werte wie fulfillment_info.type. Mit diesem AddLocalInventoriesRequest wird angegeben, dass store1 die Fulfillment-Typen pickup-in-store und ship-to-store unterstützt, während store1 custom-type-1 unterstützt. Auftragsausführungstypen, die vor dieser Aktualisierung vorhanden waren und nicht im Antrag erwähnt werden, werden gelöscht.

Da AddLocalInventoriesRequest.allow_missing auf „true“ gesetzt ist, werden die aktualisierten Informationen zum lokalen Inventar auch bei der Erstellung des Produkts gespeichert, auch wenn das Produkt noch nicht vorhanden ist. Die Aktualisierung ist mit einem Zeitstempel versehen, der mit AddLocalInventoriesRequest.add_time versehen ist, um zu verhindern, dass veraltete Aktualisierungen die angegebenen Felder dieser Orts-IDs überschreiben. Weitere Informationen dazu, wie Sie veraltete Aktualisierungen verhindern und lokale Inventarinformationen speichern, bevor das Produkt erstellt wird, finden Sie unter Zeitstempelschutz für Aktualisierungen des lokalen Inventars und Inventarinformationen vorab laden.

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

In diesem Beispiel AddLocalInventoriesRequest wird ein einzelnes lokales Inventar mit der Orts-ID "store3" für das angegebene Produkt hinzugefügt oder aktualisiert. Da add_mask "attributes" enthält, werden alle vorhandenen benutzerdefinierten Attribute von store3 gelöscht und durch attr1 und attr2 ersetzt, wie in der Anfrage angegeben. Da allow_missing nicht festgelegt ist, muss das angegebene Produkt vorhanden sein. Andernfalls wird ein NOT_FOUND-Fehler ausgegeben.

RemoveLocalInventories

Mit RemoveLocalInventories können Sie vorhandenes lokales Inventar an Orten mit den angegebenen Orts-IDs entfernen.

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
}

In diesem Beispiel RemoveLocalInventoriesRequest werden lokale Inventare für Orte mit den Orts-IDs "store1" und "store2" für das angegebene Produkt entfernt. Die Aktualisierung ist mit einem Zeitstempel versehen, der mit RemoveLocalInventoriesRequest.remove_time versehen ist, um zu verhindern, dass veraltete Aktualisierungen das Löschen dieser Orts-IDs überschreiben. Für angegebene Orts-IDs ohne vorhandenes lokales Inventar wird in der Anfrage auch die Aktualisierungszeit auf remove_time festgelegt. Weitere Informationen zu Zeitstempeln für Aktualisierungen finden Sie unter Zeitstempelschutz für Aktualisierungen des lokalen Inventars.

Zeitstempelschutz für Aktualisierungen des lokalen Inventars

Zum Schutz vor Out-of-Order-Aktualisierungen ist jedes Feld für lokales Inventar mit einer letzten Aktualisierungszeit verknüpft.

Die letzte Aktualisierungszeit wird für jedes Paar von (place_id, price_info), (place_id, attributes[...]) und (place_id, fulfillment_types[...]) aufgezeichnet.

Mit den Methoden AddLocalInventories und RemoveLocalInventories kann der Aufrufer eine Aktualisierungszeit für die Anfrage angeben. Diese Aktualisierungszeit wird mit der letzten Aktualisierungszeit für die relevanten Inventarfelder verglichen und die Aktualisierung wird nur dann durchgeführt, wenn die Aktualisierungszeit ausschließlich hinter der letzten Aktualisierungszeit liegt.

Beispiel: Für die Orts-ID "store1" ist price_info aktiviert, wobei die letzte aufgezeichnete Aktualisierungszeit auf Zeit T gesetzt ist. Wenn RemoveLocalInventoriesRequest.place_ids "store1" enthält, wird in der Anfrage price_info nur dann aus "store1" entfernt, wenn die RemoveLocalInventoriesRequest.remove_time hinter der Uhrzeit T liegt. Dasselbe gilt für RemoveLocalInventoriesRequest.

Beim Schutz von Zeitstempeln kann es vorkommen, dass durch ein RemoveLocalInventoriesRequest nur bestimmte Felder eines LocalInventory entfernt werden, nicht alle. Angenommen, ein lokales Inventar mit der Orts-ID "store1" hat price_info mit der letzten aufgezeichneten Aktualisierungszeit T1 und das einzige vorhandene benutzerdefinierte Attribut mit dem Namen "attr1" mit der letzten aufgezeichneten Aktualisierungszeit T2. Wenn ein RemoveLocalInventoriesRequest.place_ids "store1" enthält und remove_time auf T3 festgelegt ist (wobei T1 < T3 < T2), wird das price_info von store_1 entfernt, während das Attribut attr1 unverändert bleibt.

Inventarinformationen vorab laden

Bei jeder Methode zur Aktualisierung des lokalen Inventars kann der Aufrufer allow_missing in der Anfrage festlegen. Wenn allow_missing auf „true“ gesetzt ist, wird eine Aktualisierung des lokalen Inventars für ein nicht vorhandenes Product so verarbeitet, als wäre das Product gemäß den Methodenspezifikationen vorhanden. Die Informationen zum lokalen Inventar werden maximal zwei Tage lang aufbewahrt, wenn der entsprechende Product innerhalb dieses Zeitraums nicht über CreateProduct erstellt wird.