Menüdaten mit der Food Ordering AI Agent API einbinden

In dieser Anleitung wird beschrieben, wie Sie Ihre Restaurantmenüdaten strukturieren, transformieren und in die Food Ordering AI Agent Menu API aufnehmen. So kann der KI-Agent Ihre Menüangebote verstehen und Bestellungen von Kunden korrekt entgegennehmen.

Hinweise

Bevor Sie Menüs mit der Food Ordering AI Agent API aufnehmen und verwalten können, müssen Sie Folgendes tun:

1. Aktivieren Sie die Food Ordering AI Agent API:

     gcloud services enable foodorderingaiagent.googleapis.com --project=PROJECT
   

2. Prüfen Sie, ob Sie die erforderlichen IAM-Berechtigungen haben. Weisen Sie dem Nutzer oder Dienstkonto, das mit der API interagiert, die folgende IAM-Rolle (Identity and Access Management) zu:

   • Food Ordering Agent Admin (roles/foodorderingaiagent.admin): Diese Rolle bietet vollen Zugriff zum Erstellen, Lesen, Aktualisieren und Löschen aller Ressourcen des Food Ordering AI Agent, einschließlich Marken, Geschäfte und Menüs.

   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:

   1. Rufen Sie in der Google Cloud Console die Seite IAM auf.
   2. Klicken Sie auf Hinzufügen.
   3. Geben Sie das Hauptkonto (E-Mail-Adresse des Nutzers oder Dienstkontos) ein.
   4. Wählen Sie die Rolle Food Ordering AI Agent Admin aus.
   5. Klicken Sie auf Speichern.

   Ohne die entsprechenden Berechtigungen werden API-Aufrufe zum Erstellen oder Ändern von Marken, Geschäften oder Menüs abgelehnt. Die Rolle Food Ordering Agent Viewer reicht für die in dieser Anleitung beschriebenen Aufgaben nicht aus, da sie nur Lesezugriff gewährt.

Übersicht

Die Food Ordering AI Agent Menu API ist flexibel und kann verschiedene Menüstrukturen verarbeiten, von kurzen Listen mit einzelnen Artikeln bis hin zu komplexen Menüs mit verschachtelten Modifikatoren und Kombi-Menüs. Die API basiert auf einigen wichtigen Konzepten:

• Menü:Der Container der obersten Ebene für alle bestellbaren Einheiten.
• Artikel:Stellt ein bestellbares Produkt der obersten Ebene aus dem Menü dar, z. B. ein Gericht, eine Vorspeise oder ein beliebiges Produkt, das einzeln bestellt werden kann. Items können auf ModifierGroups verweisen.
• ModifierGroup:Eine Sammlung von Modifier-Optionen, die auf ein Item oder ein anderes Modifier angewendet werden können (ermöglicht das Verschachteln). Beispiele sind „Wähle deine Seite“, „Belag hinzufügen“ oder „Getränk auswählen“.
• Modifikator:Eine einzelne Option innerhalb eines ModifierGroup, z. B. „Pommes“, „Extra Käse“ oder „Cola“. Mit Modifikatoren kann der Preis angepasst werden. Sie können auch eigene verschachtelte ModifierGroup-Elemente haben.
• MenuCategory:Wird verwendet, um Items in Abschnitte für die Anzeige und das Verständnis 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. Es ist wichtig, diese Konzepte zu verstehen, um Ihre Menüdaten richtig zu modellieren.

Elemente

Jeder einzelne Artikel auf Ihrer Speisekarte sollte als Item definiert werden. Wichtige Felder:

• id: Eine eindeutige Kennung im Menü.
• display_name: Der Name, der Kunden angezeigt wird.
• base_price: Der Grundpreis des Artikels.
• modifier_groups: Verweise auf ModifierGroups, die auf diesen Artikel angewendet werden können.
• category_ids: Verweise auf MenuCategory-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 Standardwert STATUS_AVAILABLE.

Modifikatoren und ModifierGroups

Mit Modifikatoren lassen sich Elemente anpassen.

• ModifierGroups definieren eine Reihe von Auswahlmöglichkeiten, einschließlich Einschränkungen wie Mindest- oder Höchstauswahl. Muss mindestens ein Modifier enthalten.
• Modifiers stehen für die tatsächlichen Optionen. Sie können ein price_adjustment haben und rekursiv auf andere ModifierGroup verweisen, um verschachtelte Anpassungen zu ermöglichen (z.B. kann ein Item „Menü-Kombi“ ein ModifierGroup „Getränk auswählen“ haben und das Modifier „Soda“ in dieser Gruppe kann ein ModifierGroup „Geschmack auswählen“ haben).

Tipp :Der Agent arbeitet aktiv mit Kunden zusammen, um die in den einzelnen ModifierGroup angegebenen Einschränkungen zu erfüllen. Wenn beispielsweise ein Item (z. B. „Fajitas für zwei“) auf ein ModifierGroup mit min_selection_count 2 (z. B. „Zwei Getränke“) verweist und ein Kunde Item bestellt, ohne eine Auswahl für dieses ModifierGroup anzugeben (z. B. „Ich möchte die Fajitas für zwei“), arbeitet der Kundenservicemitarbeiter mit dem Kunden zusammen, um die Einschränkungen zu erfüllen (z. B. „Welche zwei Getränke möchten Sie dazu?“).

Beispiel 1: Beläge

Ein „Bacon Cheeseburger“ Item kann sich auf „Belag“ ModifierGroup beziehen. Dieses ModifierGroup würde Modifiers wie „Extra Käse“ oder „Keine Zwiebeln“ enthalten.

Beispiel 2: Kombinationsmenüs

Einige Menüs haben komplexe Strukturen mit mehreren verschachtelten Auswahlmöglichkeiten, z. B. Kombimenüs. Kombinationen können als Item mit mehreren ModifierGroups modelliert werden, die die Komponenten der Kombination darstellen. Ein „Burger-Menü“ Item, das aus einem festen Hauptgericht in Kombination mit mehreren Optionen für Beilage und Getränk besteht, könnte so modelliert werden:

• Ein ModifierGroup für die Seite (z.B. „Side choices“).
  • Jede Seitenoption wird als Modifier modelliert (z.B. „Pommes“, „Salat“).
    • Jede Getränkeoption kann auf verschachtelte ModifierGroup-Elemente verweisen (z.B. „Ice options“ (Eisoptionen), „Drink size“ (Getränkegröße), die wiederum auf Modifiers verweisen (z.B. „No Ice“ (Kein Eis), „Large drink“ (Großes Getränk)).
• Eine ModifierGroup für das Getränk (z.B. „Drinks“).
  • Jede Getränkeoption wird als Modifier modelliert.
    • Jede Getränkeoption kann auf verschachtelte ModifierGroup-Elemente verweisen (z.B. „Eisoptionen“, „Getränkegröße“), die wiederum auf Modifier verweisen (z.B. „Kein Eis“, „Großes Getränk“).
• Ein ModifierGroup für die Beilagen zum Hauptgericht. (z. B. mit der „Extra Cheese“ (Extra Käse), „Bacon“ (Speck).

Verfügbarkeit

Mit der Availability-Nachricht für Item und Modifier können Sie Folgendes angeben:

• status: STATUS_AVAILABLE, STATUS_OUT_OF_STOCK usw.
• 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 das Feld integration_attributes. Dieses Feld (ItemIntegrationAttributes, ModifierIntegrationAttributes usw.) enthält ein google.protobuf.Struct namens custom_integration_attributes. Damit können Sie beliebige Schlüssel/Wert-Daten speichern, z. B.:

• IDs aus Ihrem Kassensystem.
• Artikelnummern oder andere interne Codes.
• Alle anderen Metadaten, die für die nachgelagerte Auftragsverarbeitung oder POS-Integration erforderlich sind.

Diese Daten werden vom KI-Agenten transparent weitergeleitet.

Labels

Mit dem Feld labels in der Menu-Ressource können Sie Menüs Metadaten hinzufügen, um die Integration und das Debugging zu erleichtern.

Labels sind eine praktische Funktion und haben keine Auswirkungen auf das Verhalten des KI-Agents.

Tipp :Sie können Labels verwenden, um eine Menu mit der zugehörigen Versions-ID, dem effektiven Zeitstempel oder einer URL zu versehen, von der die Menüdaten abgerufen wurden. Das ist hilfreich, um Nuancen des Agent-Verhaltens auf bestimmte Menüquelldaten zurückzuführen.

Menü erstellen

Menüs werden mit dem RPC-Aufruf CreateMenu in der MenuService aufgenommen.

Schritte

1. Daten transformieren:Konvertieren Sie Ihre vorhandenen Menüdaten (aus Ihrem Kassensystem, Ihrer API oder einer anderen Quelle) in die Struktur, die in der google.cloud.foodorderingaiagent.v1beta.Menu-Nachricht definiert ist. Dazu müssen Sie Ihre Artikel, Modifikatoren, Kategorien und Preise den entsprechenden API-Nachrichtentypen zuordnen.
2. CreateMenuRequest erstellen:
   • Legen Sie das Feld parent fest (z.B. projects/PROJECT/locations/LOCATION).
   • Füllen Sie das Feld menu mit Ihrem transformierten Menu-Objekt.
   • Geben Sie optional eine menu_id an.
3. API aufrufen:Senden Sie CreateMenuRequest an den Endpunkt MenuService.CreateMenu. Die API bereinigt zuerst das Menü, validiert es und gibt dann das endgültige Menu-Objekt zurück.
4. Menüaktualisierungen verarbeiten:Bei jeder Aktualisierung der Menüquelldaten (z. B. wenn ein neues Produkt eingeführt wird oder ein Produkt nicht mehr verfügbar ist) sollte ein neues Menu erstellt werden, das die aktualisierten Quelldaten widerspiegelt. Dabei ist die Verarbeitung von Menüaktualisierungen zu beachten.

Leitfaden zur Datentransformation

Die genaue Logik für die Transformation Ihrer Menüdaten hängt vom Format und der Struktur Ihres Quellsystems ab (z.B. POS API, Datenbankschema). So gehen Sie im Allgemeinen vor:

• Daten exportieren:Sie erhalten einen vollständigen Export Ihrer Menüdaten, einschließlich aller Artikel, Modifikatoren, Preise und Beziehungen.
• Kartenentitäten:
  • Ermitteln Sie für jedes Element in Ihren Quelldaten die entsprechenden Entitäten im API-Schema des KI-Agents für die Essensbestellung. Die „Speisen und Getränke“ Ihres Kassensystems werden wahrscheinlich Item-Objekten zugeordnet. „Bestelloptionen“ oder „Add-ons“ werden Modifier und ModifierGroup zugeordnet.
  • Beziehungen mithilfe von IDs herstellen Verknüpfen Sie beispielsweise Item mit den entsprechenden ModifierGroup mithilfe des Referenzfelds modifier_groups.
• Verschachtelte Strukturen verarbeiten:Wenn Ihr Menü verschachtelte Modifizierer enthält (z.B. die Auswahl eines Getränkearomas für ein Kombimenü), modellieren Sie dies, indem Sie Modifiers verwenden, die auf andere ModifierGroups verweisen.
• Attribute einfügen:Füllen Sie Felder wie display_name, base_price, price_adjustment und availability anhand Ihrer Quelldaten aus.
• POS-IDs einfügen:Speichern Sie die internen POS- oder System-IDs für jedes Element, jede Änderung und jede Gruppe im Feld custom_integration_attributes. So können Sie die von dem Agenten erstellte Order in die Darstellung einer endgültigen Bestellung oder eines Warenkorbs in Ihrer Anwendung übersetzen.
• Scripting:Sie müssen wahrscheinlich ein Skript (z.B. in Python, Node.js oder Go) schreiben, um Daten aus Ihrer Quelle abzurufen, die Transformation durchzuführen und die Methode CreateMenu aufzurufen. Dieses Skript verwendet die Google Cloud -Clientbibliotheken für die Authentifizierung und API-Interaktion.

Workflow für die konzeptionelle Transformation:

In diesem Workflow wird beschrieben, wie Menüdaten aus einem Quellsystem in das Format der Food Ordering AI Agent API umgewandelt werden:

1. Kategorien extrahieren und zuordnen:
   • Kategorien oder Abschnitte in Ihren Quelldaten identifizieren (z.B. „Vorspeisen“, „Hauptgerichte“).
   • Wandeln Sie jedes in ein MenuCategory-Objekt mit einem eindeutigen id und display_name um.
2. Elemente extrahieren und zuordnen:
   • Verkaufsfähige Artikel in Ihren Quelldaten identifizieren
   • Wandeln Sie jedes in ein Item-Objekt um und füllen Sie id, display_name, base_price und availability aus.
   • Ordnen Sie jede Item mithilfe des Felds category_ids den entsprechenden Kategorien zu.
   • Speichern Sie Quellsystem-IDs (z. B. PLU oder Artikelnummer) in item.integration_attributes.custom_integration_attributes.
3. Modifikatoren extrahieren und zuordnen:
   • Identifizieren Sie Anpassungen, Optionen oder Add-ons für Artikel in Ihren Quelldaten.
   • Verwandte Optionen gruppieren (z.B. „Side Options“, „Drink Choices“, „Extra Toppings“) in ModifierGroup-Objekte. Definieren Sie für jede ModifierGroup Regeln für die Mindest- und Höchstauswahl.
   • Jede einzelne Option transformieren (z.B. „Pommes“, „Cola“, „Extra Käse“ in Modifier-Objekte innerhalb der entsprechenden ModifierGroup. Füllen Sie price_adjustment aus, falls zutreffend.
   • Speichern Sie Quellsystem-IDs in modifier_group.integration_attributes.custom_integration_attributes und modifier.integration_attributes.custom_integration_attributes.
4. Beziehungen aufbauen:
   • Füllen Sie für jedes Item das Feld modifier_groups mit Verweisen auf die id-Elemente der ModifierGroup-Elemente aus, die darauf zutreffen.
   • Wenn für ein Modifier weitere Anpassungen möglich sind, z.B. die Auswahl einer Geschmacksrichtung für den Modifikator „Soda“, füllen Sie das Feld modifier_groups aus, um verschachtelte Modifikatoren zu erstellen.
5. Zusammenstellen und aufnehmen:
   • Kombinieren Sie alle MenuCategory-, Item-, ModifierGroup- und Modifier-Objekte in den Listen in einer einzelnen Menu-Nachricht.
   • Rufen Sie den CreateMenu-RPC mit der vollständig zusammengestellten Menu-Nachricht als Eingabe auf.

Umgang mit Speisekarten-Updates

Das Menü ist unveränderlich. Nachdem ein Menü mit dem CreateMenu-RPC-Aufruf erstellt wurde, kann es nicht mehr geändert werden. Wenn Sie Menüaktualisierungen in ein Menü übernehmen möchten, z. B. um Artikelpreise zu ändern, Optionen zu bearbeiten oder die Verfügbarkeit anzupassen, müssen Sie eine neue Menüressource erstellen, indem Sie CreateMenu noch einmal aufrufen. Jede Version Ihres Menüs muss als neue Menu-Ressource mit einer eindeutigen menu_id aufgenommen werden.

Der Prozess für die Aufnahme einer neuen Version eines Menüs ist identisch mit der ersten Aufnahme des Menüs und durchläuft dieselben Schritte für Bereinigung und Validierung. Bei der Bearbeitung von Bestellungen spiegelt das Verhalten des Kundenservicemitarbeiters immer die zuletzt erstellte Menu wider, die mit der in der Konfiguration der Sitzung referenzierten Store verknüpft ist.

Tipp :Labels sind eine hilfreiche Möglichkeit, Metadaten zu verknüpfen, die zusammengehörige Menus unterscheiden. Die Diagnose von Betriebsproblemen ist oft einfacher, wenn jede Menu mit Informationen versehen ist, die das Ereignis angeben, das ihre Erstellung ausgelöst hat, und die Quelle ihres Inhalts.

Automatische Bereinigung des Menüs

Die CreateMenu API führt automatisch mehrere Bereinigungsschritte aus, um häufige Probleme zu beheben und sicherzustellen, dass Menüinhalte in der gesamten API einheitlich dargestellt werden. Die Validierungen werden nach diesen Bereinigungen angewendet, um die Menüintegration für Clients zu vereinfachen:

• Standardverfügbarkeit:Items und Modifiers ohne explizite Availability.Status werden auf STATUS_AVAILABLE festgelegt.
• Nicht referenzierte Entitäten entfernen:Modifiers und ModifierGroups, auf die nicht transitiv von einem Item verwiesen wird, werden aus dem Menü entfernt, da sie nicht bestellt werden können.
• Leere Modifikatorgruppen entfernen:ModifierGroups, die keine modifier_ids enthalten, werden entfernt und alle Verweise darauf werden gelöscht.

Menüvalidierung

Nach der Bereinigung validiert die API das Menü anhand strenger Regeln, um sicherzustellen, dass es wohlgeformt ist und zuverlässig vom KI-Agenten verwendet werden kann. Wenn die Validierung fehlschlägt, wird beim CreateMenu-Aufruf ein Fehler mit Details zu den Problemen zurückgegeben. Wichtige Validierungen:

• Pflichtfelder:Prüft, ob alle Pflichtfelder wie id, display_name und availability.status vorhanden sind.
• Eindeutige IDs:Alle Items, Modifiers und ModifierGroups müssen im Menü eindeutige IDs haben.
• Eindeutige Anzeigenamen:
  • Alle Item müssen eindeutige display_name haben.
  • Innerhalb eines bestimmten ModifierGroup müssen alle enthaltenen Modifiers eindeutige display_names haben.
• Referenzintegrität:
  • Alle modifier_group_ids, auf die von Item oder Modifier verwiesen wird, müssen im Menü vorhanden sein.
  • Alle modifier_ids, auf die von ModifierGroups verwiesen wird, müssen im Menü vorhanden sein.
  • Die in ModifierGroupReference angegebenen Standardmodifizierer müssen in der referenzierten ModifierGroup vorhanden sein.
  • Wenn in einer Modifier mit item_id auf eine Item verwiesen wird, muss diese Item vorhanden sein.
• Einschränkungen für Modifikatorgruppen:
  • ModifierGroup darf nicht leer sein.
  • Die Mindest- oder Höchstanzahl der Auswahlen innerhalb von ModifierGroup wird auf logische Konsistenz geprüft.
  • Item- oder Modifier-Ebene modifier_constraints werden anhand der Auswahlbeschränkungen der referenzierten ModifierGroup validiert, um sicherzustellen, dass sie erfüllbar sind.
• Verschachtelungstiefe:Die Tiefe der verschachtelten Modifikatoren ist begrenzt (z.B. Item -> ModifierGroup -> Modifier -> ModifierGroup -> Modifier … bis zu maximal 5 Ebenen.
• Tageszeitsegment-Validierung:Wenn Tageszeitsegmente in Availability verwendet werden, müssen sie in der zugehörigen Store-Ressource definiert sein.
• Referenzen auf Modifikatorartikel:Modifier, die mit item_id auf ein Item verweisen, dürfen keine Felder wie display_name oder availability haben, da diese vom referenzierten Item übernommen werden.

Wenn eine dieser Validierungsregeln nicht erfüllt wird, kann das Menü nicht erstellt oder aktualisiert werden. Die Fehlermeldung enthält Details dazu, welche Einheiten den Verstoß verursachen.

API-Referenz

Vollständige Informationen zu allen Nachrichten und Feldern finden Sie in der RPC-Referenz für die Food Ordering AI Agent API.

Best Practices

• Eindeutige IDs:Achten Sie darauf, dass alle id-Felder im Menu-Bereich (für Item, Modifier, ModifierGroup, MenuCategory) eindeutig sind.
• Aussagekräftige Namen:Verwenden Sie klare, kundenfreundliche display_name. Geben Sie unterschiedliche display_name für semantisch unterschiedliche Produkte an, damit der Kundenservicemitarbeiter die Anfragen entsprechend disambiguieren kann.
• Kombinationsmahlzeiten effektiv modellieren:Modellieren Sie Kombinationsmahlzeiten als Item mit ModifierGroup als Beilagen, Getränke und andere Optionen, wie unter Kombinationsmahlzeiten beschrieben. So kann der Kundenservicemitarbeiter Kunden bei der Auswahl von Kombinationen richtig anleiten.
• Integrationsattribute verwenden:Speichern Sie alle erforderlichen POS- oder internen Systemkennzeichnungen im custom_integration_attributes, um eine nahtlose Auftragsintegration zu ermöglichen.
• Verfügbarkeit verwalten:Halten Sie den Status Availability auf dem neuesten Stand.
• Gründlich testen:Testen Sie nach der Aufnahme, wie gut der Agent das Menü mit verschiedenen Bestellkombinationen versteht.