Dies ist die Dokumentation für Recommendations AI, Retail Search und die neue Retail Console.

Lokales Inventar für die Einzelhandelssuche aktualisieren

LocalInventory ist die Inventarinformation zu einem bestimmten Ort, identifiziert durch seinen place_id. So kann beispielsweise ein LocalInventory für ein Geschäft oder eine Region erstellt werden, in der ein bestimmter Preis verfügbar ist. Das Feld „LocalInventory“ enthält folgende Felder:

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

Vorhandene LocalInventory-Einträge sind bis Product.local_inventories sichtbar (mit Ausnahme von fulfillment_types, die aus Gründen der Abwärtskompatibilität über Product.fulfillment_info verfügbar ist). Dieses Feld wird nur ausgegeben. 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 zur Inventaraktualisierung angegeben ist. fulfillment_types aktualisiert von AddLocalInventories und RemoveLocalInventories (siehe unten) stellt eine Zuordnung von jeder Orts-ID zu einer Liste von unterstützten Ausführungstypen dar. fulfillment_info aktualisiert von AddFulfillmentPlaces und RemoveFulfillmentPlaces stellt eine Zuordnung von jedem bestimmten Auftragsausführungstyp zu einer Liste mit Orts-IDs dar, die diesen Typ unterstützt. Allerdings ändern beide Arten von APIs dieselben zugrunde liegenden Informationen zur Auftragsausführung und die Auswirkungen beider Arten von APIs spiegelt sich in Product.fulfillment_info wider.

Methoden zur Aktualisierung des lokalen Inventars

Änderungen an Informationen zum lokalen Inventar eines Produkts können wesentlich häufiger vorkommen als Änderungen an den Kataloginformationen. Für die Verarbeitung großer Mengen lokaler inventarspezifischer Aktualisierungen stehen spezielle Methoden zur Verfügung. Diese Methoden sind asynchron, da nachgelagerte Optimierungen Hunderte gleichzeitige Aktualisierungen pro Produkt unterstützen, ohne die Leistung zu beeinträchtigen.

AddLocalInventories

AddLocalInventories kann verwendet werden, um lokales Inventar für neue Orte (durch neue place_ids dargestellt) zu erstellen oder vorhandene Felder in bestehenden lokalen Inventaren zu aktualisieren. Felder, die in der Liste der LocalInventory-Einträge im Anfragetext hinzugefügt oder aktualisiert werden, können über AddLocalInventoriesRequest.add_mask angegeben werden. Gültige add_mask-Werte sind:

  • price_info: überschreibt LocalInventory.price_info.
  • attributes: überschreibt alle LocalInventory.attributes. Vorhandene Attribute, die im Anfragetext nicht enthalten sind, werden entfernt.
  • attributes.PLACEHOLDER_NAME: überschreibt nur das angegebene benutzerdefinierte Attribut. Wenn in der Anfrage kein vorhandener Attributname angegeben ist, wird das Attribut gelöscht. Es können mehrere attributes.PLACEHOLDER_NAME angegeben werden, solange der Attributname unterschiedlich ist. AddLocalInventoriesRequest.add_mask kann jedoch nicht sowohl den Wert attributes als auch den Wert attributes.PLACEHOLDER_NAME in derselben Anfrage enthalten.
  • fulfillment_types: überschreibt alle unterstützten Ausführungstypen. Vorhandene Ausführungstypen, die nicht im Anfragetext enthalten sind, 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 nicht vor der Anfrage vorhanden ist, werden die Felder von store1 durch die Anfrage aktualisiert und store2 mit den angegebenen Feldwerten erstellt.

Diese AddLocalInventoriesRequest.add_mask gibt an, dass price_info, ein einzelnes benutzerdefiniertes Attribut mit dem Namen "attr1" und fulfillment_types mit den in AddLocalInventoriesRequest.local_inventories angegebenen Werten aktualisiert werden soll.

attributes sind Attribute, die mit einem Ort mit benutzerdefinierten Namen und Werten verknüpft sind. Da LocalInventory von store1 den Wert von attr1 in der Anfrage nicht enthält, wird das benutzerdefinierte Attribut attr1 aus der vorhandenen LocalInventory von store1 gelöscht, sofern vorhanden. Für „store2“ wird das Attribut „attr1“ auf den Textwert „store2_value“ festgelegt. Andere benutzerdefinierte Attribute für store1 und store2 bleiben unverändert.

fulfillment_types stellt eine Liste der Verfügbarkeit für die Auftragsausführung für ein Product an einem einzelnen Ort dar. Sie ist identisch und akzeptiert dieselben Werte wie für fulfillment_info.type. Diese AddLocalInventoriesRequest definiert, dass store1 pickup-in-store und ship-to-store Ausführungstypen unterstützt, während store1 custom-type-1 unterstützt. Ausführungstypen, die vor dieser Aktualisierung vorhanden sind 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. Der Zeitstempel ist mit AddLocalInventoriesRequest.add_time versehen, um zu verhindern, dass veraltete Updates die angegebenen Felder dieser Orts-IDs überschreiben. Weitere Informationen dazu, wie du veraltete Aktualisierungen verhindern und Informationen zu lokalem Inventar speichern kannst, bevor das Produkt erstellt wird, findest du unter Zeitstempelschutz für lokale Inventaraktualisierungen und Vorabladen von Inventarinformationen.

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 Ihr 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 der Fehler NOT_FOUND ausgegeben.

RemoveLocalInventories

Mit RemoveLocalInventories kann vorhandenes lokales Inventar an Orten mit bestimmten Orts-IDs entfernt werden.

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 für RemoveLocalInventoriesRequest wird das lokale Inventar für Orte mit den Orts-IDs "store1" und "store2" für das angegebene Produkt entfernt. Der Zeitstempel ist mit RemoveLocalInventoriesRequest.remove_time gekennzeichnet, um zu verhindern, dass veraltete Updates mit dem Löschen dieser Orts-IDs überschrieben werden. Bei angegebenen Orts-IDs ohne vorhandenes lokales Inventar wird in der Anfrage außerdem die Aktualisierungszeit auf remove_time erfasst. Weitere Informationen zu Updatezeitstempeln finden Sie unter Zeitstempelschutz für lokale Inventaraktualisierungen.

Zeitstempelschutz für Aktualisierungen des lokalen Inventars

Zum Schutz vor Out-of-Order-Updates wird jedem Feld mit lokalem Inventar der letzte Aktualisierungszeit zugeordnet.

Die letzte Aktualisierungszeit wird für jedes Paar (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 Ausgabe der Anfrage angeben. Diese Aktualisierungszeit wird mit der letzten Aktualisierungszeit für die relevanten Inventarfelder verglichen. Die Aktualisierung wird nur dann durchgeführt, wenn die Aktualisierungszeit ausschließlich nach der letzten Aktualisierungszeit liegt.

Angenommen, die Orts-ID "store1" hat den Wert price_info und die letzte aufgezeichnete Aktualisierungszeit ist auf T festgelegt. Wenn RemoveLocalInventoriesRequest.place_ids "store1" enthält, wird price_info nur dann aus "store1" entfernt, wenn RemoveLocalInventoriesRequest.remove_time später als T ist. Dasselbe gilt für RemoveLocalInventoriesRequest.

Unter dem Zeitstempelschutz ist es möglich, dass ein RemoveLocalInventoriesRequest nur bestimmte Felder eines LocalInventorys entfernt. Angenommen, ein lokales Inventar mit der Orts-ID "store1" hat die price_info aufgezeichnete Zeit für die letzte Aktualisierung auf die Uhrzeit T1 und ihr einziges benutzerdefiniertes Attribut mit dem Namen "attr1" hat die letzte aufgezeichnete Aktualisierungszeit um T2. Wenn eine RemoveLocalInventoriesRequest.place_ids ("store1") enthält und remove_time auf T3 (wobei T1 < T3 < T2) festgelegt ist, werden store_1-price_info 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 lokale Inventaraktualisierung auf eine nicht vorhandene Product verarbeitet, so als ob die Product gemäß den Methodenspezifikationen vorhanden wäre. Die Informationen zum lokalen Inventar werden maximal zwei Tage gespeichert, wenn die entsprechende Product nicht innerhalb dieses Zeitraums über CreateProduct erstellt wird.