Hinweis
Bevor Sie Speisekarten mit der Food Ordering AI Agent API aufnehmen und verwalten können, müssen Sie Folgendes tun:
Aktivieren Sie die Food Ordering KI-Agent API:
gcloud services enable foodorderingaiagent.googleapis.com --project=PROJECTPrüfen Sie, ob Sie die erforderlichen IAM-Berechtigungen haben. Weisen Sie dem Nutzer oder Dienstkonto, der bzw. das mit der API interagiert, die folgende IAM-Rolle (Identity and Access Management) zu:
- Food Ordering Agent Admin (
roles/foodorderingaiagent.admin): Diese Rolle bietet vollständigen Zugriff zum Erstellen, Lesen, Aktualisieren und Löschen aller Food Ordering KI-Agent-Ressourcen, einschließlich Marken, Geschäften und Speisekarten.
Sie können IAM-Rollen über die Google Cloud Console, das
gcloud-Befehlszeilentool oder die IAM API zuweisen. Weitere Informationen finden Sie unter IAM-Rolle zuweisen.So weisen Sie die Rolle über die Google Cloud Console zu:
- Rufen Sie in der Google Cloud Console die Seite IAM auf.
- Klicken Sie auf Hinzufügen.
- Geben Sie das Hauptkonto (E-Mail-Adresse des Nutzers oder Dienstkontos) ein.
- Wählen Sie die Rolle Food Ordering KI-Agent-Administrator aus.
- Klicken Sie auf Speichern.
Ohne die entsprechenden Berechtigungen werden API-Aufrufe zum Erstellen oder Ändern von Marken, Geschäften oder Speisekarten abgelehnt. Die Rolle
Food Ordering Agent Viewerreicht für die in diesem Leitfaden beschriebenen Aufgaben nicht aus, da sie nur Lesezugriff gewährt.- Food Ordering Agent Admin (
Übersicht
Die Food Ordering AI Agent Menu API ist flexibel und kann verschiedene Speisekartenstrukturen verarbeiten, von kurzen Listen mit eigenständigen Artikeln bis hin zu komplexen Speisekarten mit verschachtelten Modifikatoren und Kombinationsgerichten. Die API basiert auf einigen wichtigen Konzepten:
- Menü: Der übergeordnete Container für alle bestellbaren Entitäten.
- Artikel: Ein bestellbares Produkt auf oberster Ebene aus der Speisekarte, z. B. ein Gericht, eine Vorspeise oder ein Produkt, das einzeln bestellt werden kann.
Items können aufModifierGroups verweisen. - ModifierGroup: Eine Sammlung von
Modifier-Optionen, die auf einItemoder ein anderesModifierangewendet werden können (Verschachtelung möglich). Beispiele: „Beilage auswählen“, „Zutaten hinzufügen“ oder „Geschmacksrichtung des Getränks auswählen“. - Modifikator: Eine einzelne Option innerhalb einer
ModifierGroup, z. B. „Pommes frites“, „Extra Käse“ oder „Cola“. Modifikatoren können den Preis anpassen und auch eigene verschachtelteModifierGroups haben. - MenuCategory: Wird verwendet, um
Items in Abschnitte für die Anzeige und das Verständnis der Anzeige zu unterteilen (z.B. „Vorspeisen“, „Burger“, „Getränke“).
Wichtige Konzepte und Struktur
In diesem Abschnitt werden die Kernkomponenten des Schemas der Food Ordering AI Agent Menu API und ihre Struktur beschrieben. Das Verständnis dieser Konzepte ist entscheidend, um Ihre Speisekarten-Daten korrekt zu modellieren.
Elemente
Jeder einzelne Artikel auf Ihrer Speisekarte sollte als Item definiert werden. Wichtige Felder:
id: Eine eindeutige Kennung innerhalb der Speisekarte.display_name: Der Name, der für Kunden sichtbar ist.base_price: Der Basispreis des Artikels.modifier_groups: Verweise aufModifierGroups, die auf diesen Artikel angewendet werden können.category_ids: Verweise aufMenuCategory-IDs, zu denen dieses Element gehört.availability: Gibt an, wann der Artikel verfügbar ist (z.B. nach Status oder Tageszeit). Wenn keine Angabe gemacht wird, ist der StandardwertSTATUS_AVAILABLE.
Modifikatoren und Modifikatorgruppen
Mit Modifikatoren können Artikel angepasst werden.
ModifierGroups definieren eine Reihe von Auswahlmöglichkeiten, einschließlich Einschränkungen wie Mindest- oder Höchstauswahl. Muss mindestens einModifierenthalten.Modifiers stehen für die tatsächlichen Optionen. Sie können einenprice_adjustmenthaben und rekursiv auf andereModifierGroups für verschachtelte Anpassungen verweisen (z.B. kann einItem„Menü“ eineModifierGroup„Getränk auswählen“ haben und dieModifier„Limonade“ in dieser Gruppe kann eineModifierGroup„Geschmacksrichtung auswählen“ haben).
Beispiel 1: Toppings
Ein „Bacon Cheeseburger“ Item kann auf „Toppings“ ModifierGroup verweisen. Diese ModifierGroup würde Modifiers wie „Extra Käse“, „Keine Zwiebeln“ usw. enthalten.
Beispiel 2: Kombi-Menüs
Einige Menüs haben komplexe Strukturen, die aus mehreren verschachtelten Auswahlmöglichkeiten bestehen, z. B. Kombinationsgerichte oder „Kombis“. Kombinationen können als Item mit mehreren ModifierGroups modelliert werden, die die Komponenten der Kombination darstellen. Beispiel: Ein „Burger-Menü“ (Item), das aus einem festen Hauptgericht und mehreren Optionen für Beilage und Getränk besteht, könnte so modelliert werden:
- Eine
ModifierGroupfür die Beilage (z.B. „Beilagen“).- Jede Beilage wird als
Modifiermodelliert (z.B. „Pommes frites“, „Salat“).- Jede Getränkeoption kann auf verschachtelte
ModifierGroups verweisen (z.B. „Eisoptionen“, „Getränkegröße“), die wiederum aufModifiers verweisen (z.B. „Kein Eis“, „Großes Getränk“).
- Jede Getränkeoption kann auf verschachtelte
- Jede Beilage wird als
- Eine
ModifierGroupfür das Getränk (z.B. „Getränke“).- Jede Getränkeoption wird als
Modifiermodelliert.- Jede Getränkeoption kann auf verschachtelte
ModifierGroups verweisen (z.B. „Eisoptionen“, „Getränkegröße“), die wiederum aufModifiers verweisen (z.B. „Kein Eis“, „Großes Getränk“).
- Jede Getränkeoption kann auf verschachtelte
- Jede Getränkeoption wird als
- Ein
ModifierGroupfür Toppings auf dem Hauptgericht. (z.B. „Extra Käse“, „Bacon“).
Verfügbarkeit
Mit der Nachricht Availability für Items und Modifiers können Sie Folgendes angeben:
status:STATUS_AVAILABLE,STATUS_OUT_OF_STOCKusw.daypart_availability: Links zu bestimmten Tageszeit-IDs, wenn der Artikel nur zu bestimmten Zeiten verfügbar ist (z.B. „Frühstücksmenü“).
Integrationsattribute
Item-, Modifier- und ModifierGroup-Nachrichten enthalten ein integration_attributes-Feld. Dieses Feld (ItemIntegrationAttributes, ModifierIntegrationAttributes usw.) enthält einen google.protobuf.Struct namens custom_integration_attributes. Sie können damit beliebige Schlüssel/Wert-Daten speichern, z. B.:
- IDs aus Ihrem Kassensystem.
- SKUs oder andere interne Codes
- Alle anderen Metadaten, die für die nachgelagerte Bestellverarbeitung oder POS-Integration erforderlich sind.
Diese Daten werden vom KI-Agenten undurchsichtig weitergegeben.
Labels
Sie können das Feld labels in der Ressource Menu verwenden, um Metadaten an Menüs anzuhängen, die bei der Integration und Fehlerbehebung helfen.
Labels sind eine praktische Funktion und haben keine Auswirkungen auf das Verhalten des KI-Agenten.
Speisekarte erstellen
Speisekarten werden über den RPC-Aufruf CreateMenu in der MenuService aufgenommen.
Schritte
- Daten transformieren: Wandeln Sie Ihre vorhandenen Speisekarten-Daten (aus Ihrem Kassensystem, Ihrer API oder einer anderen Quelle) in die durch die
google.cloud.foodorderingaiagent.v1beta.Menu-Nachricht definierte Struktur um. Dazu müssen Sie Ihre Artikel, Modifikatoren, Kategorien und Preise den entsprechenden API-Nachrichtentypen zuordnen. CreateMenuRequesterstellen:- Legen Sie das Feld
parentfest (z.B.projects/PROJECT/locations/LOCATION). - Füllen Sie das Feld
menumit Ihrem transformiertenMenu-Objekt aus. - Geben Sie optional einen
menu_idan.
- Legen Sie das Feld
- API aufrufen: Senden Sie die
CreateMenuRequestan den EndpunktMenuService.CreateMenu. Die API bereinigt zuerst die Speisekarte, validiert sie dann und gibt das endgültigeMenu-Objekt zurück. - Speisekartenaktualisierungen verarbeiten: Bei jeder Aktualisierung der Quelldaten der Speisekarte (z. B. wenn ein neues Produkt eingeführt wird oder ein Produkt nicht mehr verfügbar ist) sollte eine neue
Menuerstellt werden, die die aktualisierten Quelldaten widerspiegelt. Folgen Sie dazu der Anleitung unter Speisekartenaktualisierungen verarbeiten.
Anleitung zur Datentransformation
Die genaue Logik für die Transformation Ihrer Speisekarten-Daten hängt vom Format und der Struktur Ihres Quellsystems ab (z.B. POS-API, Datenbankschema). Hier ist ein allgemeiner Ansatz:
- Daten exportieren: Sie können einen vollständigen Export Ihrer Speisekartendaten erhalten, einschließlich aller Artikel, Modifikatoren, Preise und Beziehungen.
- Entitäten zuordnen:
- Identifizieren Sie die entsprechenden Entitäten im API-Schema des KI-Agenten für Food Ordering für jedes Element in Ihren Quelldaten. Beispielsweise werden die „Menüpunkte“ Ihres Kassensystems wahrscheinlich
Item-Objekten zugeordnet. „Bestelloptionen“ oder „Add-ons“ werdenModifiers undModifierGroups zugeordnet. - Beziehungen mithilfe von IDs herstellen. Verknüpfe beispielsweise
Items mit den entsprechendenModifierGroups über das Referenzfeldmodifier_groups.
- Identifizieren Sie die entsprechenden Entitäten im API-Schema des KI-Agenten für Food Ordering für jedes Element in Ihren Quelldaten. Beispielsweise werden die „Menüpunkte“ Ihres Kassensystems wahrscheinlich
- Verschachtelte Strukturen verarbeiten: Wenn Ihre Speisekarte verschachtelte Modifikatoren enthält (z.B. die Auswahl einer Geschmacksrichtung für das Getränk eines Kombi-Menüs), können Sie dies modellieren, indem Sie
Modifiers auf andereModifierGroups verweisen lassen. - Attribute ausfüllen: Füllen Sie Felder wie
display_name,base_price,price_adjustmentundavailabilityanhand Ihrer Quelldaten aus. - POS-IDs angeben: Speichern Sie Ihre internen POS- oder System-IDs für jeden Artikel, jede Modifikation und jede Gruppe im Feld
custom_integration_attributes. So können Sie die vom Agenten erstellteOrderwieder in die Darstellung einer endgültigen Bestellung oder eines laufenden Einkaufswagens in Ihrer Anwendung übersetzen. - Scripting: Sie müssen wahrscheinlich ein Script schreiben (z.B. in Python, Node.js, Go), um Daten aus Ihrer Quelle abzurufen, die Transformation durchzuführen und die Methode
CreateMenuaufzurufen. Dieses Skript verwendet die Clientbibliotheken von Google Cloud für die Authentifizierung und API-Interaktion.
Konzeptioneller Transformationsworkflow:
In diesem Workflow wird beschrieben, wie Speisekarten-Daten aus einem Quellsystem in das Format der Food Ordering KI-Agent API umgewandelt werden:
- Kategorien extrahieren und zuordnen:
- Identifizieren Sie Kategorien oder Abschnitte in Ihren Quelldaten (z.B. „Vorspeisen“, „Hauptgerichte“).
- Wandeln Sie jedes Objekt in ein
MenuCategory-Objekt mit einer eindeutigenidunddisplay_nameum.
- Elemente extrahieren und zuordnen:
- Identifizieren Sie verkaufbare Artikel in Ihren Quelldaten.
- Wandeln Sie jedes Objekt in ein
Item-Objekt um und füllen Sieid,display_name,base_priceundavailabilityaus. - Ordnen Sie jede
Itemmithilfe des Feldscategory_idsden entsprechenden Kategorien zu. - Speichern Sie Quellsystemkennungen (z. B. PLU oder SKU) in
item.integration_attributes.custom_integration_attributes.
- Modifikatoren extrahieren und zuordnen:
- Identifizieren Sie Artikelanpassungen, Optionen oder Add-ons in Ihren Quelldaten.
- Gruppieren Sie zusammengehörige Optionen (z.B. „Beilagen“, „Getränke“, „Zusätzliche Toppings“) in
ModifierGroup-Objekten. Definieren Sie Regeln für die minimale und maximale Auswahl für jedeModifierGroup. - Wandeln Sie jede einzelne Option (z.B. „Pommes“, „Cola“, „Extra Käse“) in
Modifier-Objekte innerhalb der entsprechendenModifierGroupum. Füllen Sieprice_adjustmentaus, falls zutreffend. - Speichern Sie die Kennungen des Quellsystems in
modifier_group.integration_attributes.custom_integration_attributesundmodifier.integration_attributes.custom_integration_attributes.
- Beziehungen aufbauen:
- Füllen Sie für jede
Itemdas Feldmodifier_groupsmit Verweisen auf dieids derModifierGroups, die für sie gelten. - Wenn ein
Modifierweitere Anpassungen zulässt (z.B. die Auswahl einer Geschmacksrichtung für einen Modifikator „Limonade“), füllen Sie das Feldmodifier_groupsaus, um verschachtelte Modifikatoren zu erstellen.
- Füllen Sie für jede
- Zusammenstellen und aufnehmen:
- Kombinieren Sie alle
MenuCategory-,Item-,ModifierGroup- undModifier-Objekte in den Listen innerhalb einer einzigenMenu-Nachricht. - Rufen Sie den RPC
CreateMenumit der vollständig zusammengestellten NachrichtMenuals Eingabe auf.
- Kombinieren Sie alle
Umgang mit Menüaktualisierungen
Menu ist unveränderlich. Nachdem eine Speisekarte mit dem RPC-Aufruf CreateMenu erstellt wurde, kann sie nicht mehr geändert werden. Wenn Sie Änderungen an einem Menü vornehmen möchten, z. B. Artikelpreise, Optionen oder Verfügbarkeit anpassen, müssen Sie eine neue Menüressource erstellen. Rufen Sie dazu noch einmal CreateMenu auf. Jede Version Ihrer Speisekarte sollte als neue Menu-Ressource mit einer eindeutigen menu_id aufgenommen werden.
Der Prozess zum Aufnehmen einer neuen Version einer Speisekarte ist identisch mit der erstmaligen Aufnahme der Speisekarte. Es werden dieselben Schritte zur Bereinigung und Validierung durchgeführt. Bei der Bearbeitung von Bestellungen entspricht das Verhalten des KI-Agenten immer der zuletzt erstellten Menu, die mit der Store verknüpft ist, auf die in der Konfiguration der Sitzung verwiesen wird.
Automatische Bereinigung von Speisekarten
Die CreateMenu API führt automatisch mehrere Bereinigungsschritte aus, um häufige Probleme zu beheben und dafür zu sorgen, dass Menüinhalte in der gesamten API einheitlich dargestellt werden. Die Validierungen werden nach diesen Bereinigungen angewendet, um die Menüintegration für Kunden zu vereinfachen:
- Standardverfügbarkeit:
Items undModifiers ohne expliziteAvailability.Statuswerden aufSTATUS_AVAILABLEgesetzt. - Nicht referenzierte Entitäten verwerfen:
Modifiers undModifierGroups, die nicht transitiv von einemItemreferenziert werden, werden aus der Speisekarte entfernt, da sie nicht bestellt werden können. - Leere Modifikatorgruppen verwerfen:
ModifierGroups, die keinemodifier_idsenthalten, werden verworfen und alle Verweise darauf werden entfernt.
Menüvalidierung
Nach der Bereinigung validiert die API die Speisekarte anhand strenger Regeln, um sicherzustellen, dass sie korrekt formatiert ist und vom KI-Agenten zuverlässig verwendet werden kann. Wenn die Validierung fehlschlägt, wird beim Aufruf von CreateMenu ein Fehler mit Details zu den Problemen zurückgegeben. Zu den wichtigsten Validierungen gehören:
- Pflichtfelder: Es wird geprüft, ob alle Pflichtfelder wie
id,display_nameundavailability.statusvorhanden sind. - Eindeutige IDs: Alle
Items,Modifiers undModifierGroups müssen innerhalb der Speisekarte eindeutige IDs haben. - Eindeutige Anzeigenamen:
- Alle
Items müssen eindeutigedisplay_names haben. - Innerhalb einer bestimmten
ModifierGroupmüssen alle enthaltenenModifiers eindeutigedisplay_names haben.
- Alle
- Referenzielle Integrität:
- Alle
modifier_group_ids, auf die vonItems oderModifiers verwiesen wird, müssen in der Speisekarte vorhanden sein. - Alle
modifier_ids, auf die vonModifierGroups verwiesen wird, müssen in der Speisekarte vorhanden sein. - In
ModifierGroupReferenceangegebene Standardmodifikatoren müssen im referenziertenModifierGroupvorhanden sein. - Wenn ein
Modifiermititem_idauf einItemverweist, muss diesesItemvorhanden sein.
- Alle
- Einschränkungen für Modifikatorgruppen:
ModifierGroups dürfen nicht leer sein.- Die minimale oder maximale Anzahl der Auswahlen innerhalb von
ModifierGroups wird auf logische Konsistenz geprüft. ItemoderModifierder Ebenemodifier_constraintswerden anhand der Einschränkungen für die Anzahl der Auswahlen der referenziertenModifierGroups validiert, um sicherzustellen, dass sie erfüllt werden können.
- Verschachtelungstiefe: Die Tiefe verschachtelter Modifikatoren ist auf maximal 5 Ebenen begrenzt (z.B.
Item->ModifierGroup->Modifier->ModifierGroup->Modifier...). - Tageszeitvalidierung: Wenn Tageszeiten in
Availabilityverwendet werden, müssen sie in der zugehörigenStore-Ressource definiert werden. - Verweise auf Modifikatorelemente: Für
Modifiers, die mititem_idauf einItemverweisen, können keine Felder wiedisplay_nameoderavailabilityfestgelegt werden, da diese vom referenziertenItemübernommen werden.
Wenn eine dieser Validierungsregeln nicht erfüllt wird, kann die Speisekarte nicht erstellt oder aktualisiert werden. Die Fehlermeldung enthält Details dazu, welche Entitäten den Verstoß verursachen.
API-Referenz
Ausführliche Informationen zu allen Nachrichten und Feldern finden Sie in der RPC-Referenz zur Food Ordering KI-Agent API.
Best Practices
- Eindeutige IDs: Achten Sie darauf, dass alle
id-Felder imMenu-Bereich (fürItem,Modifier,ModifierGroup,MenuCategory) eindeutig sind. - Klare Namen: Verwenden Sie klare, kundenfreundliche
display_names. Geben Sie für semantisch unterschiedliche Produkte unterschiedlichedisplay_names an, damit der Agent die Mehrdeutigkeit entsprechend auflösen kann. - Kombinationsmenüs effektiv modellieren: Modellieren Sie Kombinationsmenüs als
ItemmitModifierGroups, die Beilagen, Getränke und andere Optionen darstellen, wie unter Kombinationsmenüs beschrieben. So können Kundenservicemitarbeiter Kunden korrekt durch die Auswahl von Kombis führen. - Integrationsattribute verwenden: Speichern Sie alle erforderlichen POS- oder internen Systemkennungen im
custom_integration_attributes, um eine nahtlose Bestellintegration zu ermöglichen. - Verfügbarkeit verwalten: Halten Sie den Status
Availabilityauf dem neuesten Stand. - Nur bestellbare Artikel aufnehmen: Lassen Sie Einträge weg, die Kunden nicht über den Kanal bestellen können, z. B. Artikel, die nur geliefert werden, doppelte Artikel und Einträge, die keine Lebensmittel oder Getränke sind. Große Menüs können die Menge an Eingaben überschreiten, die das Modell des KI-Agenten akzeptiert. Weitere Informationen finden Sie unter Agent wiederholt eine Wiederholungsnachricht und beendet dann die Sitzung.
- Gründlich testen: Testen Sie nach der Aufnahme, ob der Agent die Speisekarte versteht, indem Sie verschiedene Bestellkombinationen ausprobieren.