Lokales Inventar für Vertex AI Search for Retail aktualisieren

LocalInventory sind die Inventarinformationen, die mit einem bestimmten Ort verknüpft sind, der durch seine place_id identifiziert wird. Eine LocalInventory kann beispielsweise für ein Geschäft oder eine Region erstellt werden, in der ein bestimmter Preis gilt. 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. Die Einstellung 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 zur Inventaraktualisierung erwähnt wird. fulfillment_types, das durch AddLocalInventories und RemoveLocalInventories aktualisiert wird, wie unten beschrieben, entspricht einer Zuordnung jeder Orts-ID zu einer Liste der unterstützten Auftragsausführungstypen. fulfillment_info, das durch AddFulfillmentPlaces und RemoveFulfillmentPlaces aktualisiert wird, entspricht einer Zuordnung jedes Auftragsausführungstyps zu einer Liste der Orts-IDs, die diesen Typ unterstützen. Beide API-Typen ändern jedoch dieselben zugrunde liegenden Informationen zur Auftragsausführung und die Auswirkungen beider API-Typen werden auf Product.fulfillment_info angewendet.

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 stehen spezielle Methoden zur Verfügung, um große Mengen an lokalen 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 können Sie lokale Inventare an neuen Orten erstellen (dargestellt durch neue place_ids) oder vorhandene Felder in vorhandenen 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: Alle LocalInventory.attributes werden überschrieben. Vorhandene Attribute, die im Anfragetext nicht erwähnt werden, werden entfernt.
• attributes.PLACEHOLDER_NAME: Es wird nur das angegebene benutzerdefinierte Attribut überschrieben. Wenn in der Anfrage kein vorhandener Attributname angegeben ist, wird das Attribut gelöscht. Es können mehrere attributes.PLACEHOLDER_NAME angegeben werden, solange sich die Attributnamen unterscheiden. AddLocalInventoriesRequest.add_mask darf jedoch in derselben Anfrage nicht sowohl den Wert attributes als auch die Werte attributes.PLACEHOLDER_NAME enthalten.
• fulfillment_types: Überschreibt alle unterstützten Auftragsausführungstypen. Vorhandene Auftragsausführungstypen, die im Anfragetext nicht erwähnt werden, werden entfernt.

{
  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 Standort-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 in AddLocalInventoriesRequest.local_inventories angegebenen Werten aktualisiert werden sollen.

attributes sind Attribute, die mit einem Ort mit anpassbarem Namen und Werten verknüpft sind. Da für LocalInventory von store1 in der Anfrage kein Wert für attr1 angegeben ist, wird das benutzerdefinierte Attribut attr1 aus dem vorhandenen LocalInventory von store1 gelöscht, falls es vorhanden ist. Der Wert des Attributs attr1 von store2 ist auf den Textwert store2_value festgelegt. Andere vorhandene benutzerdefinierte Attribute auf store1 und store2 bleiben unverändert.

fulfillment_types ist eine Liste der Verfügbarkeit der Auftragsausführung für eine Product an einem einzelnen Ort. Es ist dasselbe und akzeptiert dieselben Werte wie fulfillment_info.type. Diese AddLocalInventoriesRequest gibt an, dass store1 die Auftragsausführungstypen 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 in der Anfrage 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 zum Verhindern veralteter Aktualisierungen und zum Speichern von Informationen zum lokalen Inventar, bevor das Produkt erstellt wird, finden Sie unter Zeitstempelschutz für Inventaraktualisierungen und Inventarinformationen vorab laden.

{
  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 das add_mask von store3 "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 der Fehler NOT_FOUND ausgegeben.

RemoveLocalInventories

Mit RemoveLocalInventories können vorhandene lokale Inventare an Standorten mit bestimmten Orts-IDs entfernt werden.

{
  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 wird lokales Inventar für Standorte mit den Standort-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 lokale Inventaraktualisierungen.

Zeitstempelschutz für Aktualisierungen des lokalen Inventars

Zum Schutz vor Out-of-Order-Aktualisierungen ist jedes lokale Inventarfeld 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 der 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 festgelegt, 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.

Bei der Zeitstempel-Schutzfunktion kann es vorkommen, dass eine RemoveLocalInventoriesRequest nur bestimmte Felder einer LocalInventory entfernt, anstatt sie vollständig zu entfernen. Angenommen, für ein lokales Inventar mit der Orts-ID "store1" ist price_info mit der letzten aufgezeichneten Aktualisierungszeit T1 festgelegt. Das einzige vorhandene benutzerdefinierte Attribut mit dem Namen "attr1" hat die letzte aufgezeichnete Aktualisierungszeit T2. Wenn ein RemoveLocalInventoriesRequest.place_ids "store1" enthält und remove_time auf T3 (wo T1 < T3 < T2) festgelegt ist, wird 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 „wahr“ gesetzt ist, wird eine lokale Inventaraktualisierung auf ein nicht vorhandenes Product verarbeitet, als wäre das Product gemäß den Methodenspezifikationen vorhanden. Die lokalen Inventarinformationen werden maximal zwei Tage lang aufbewahrt, wenn der entsprechende Product innerhalb dieses Zeitraums nicht über CreateProduct erstellt wird.