Integrazione dei dati del menu utilizzando l'API Food Ordering AI Agent

Questa guida spiega come strutturare, trasformare e importare i dati del menu del ristorante nell'API Menu dell'agente AI per l'ordinazione di cibo. In questo modo, l'agente AI può comprendere le offerte del tuo menu e prendere accuratamente gli ordini dei clienti.

Prima di iniziare

Prima di poter importare e gestire i menu utilizzando l'API Food Ordering AI Agent, devi:

1. Abilita l'API dell'agente AI Ordinazione di cibo:

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

2. Assicurati di disporre delle autorizzazioni IAM necessarie. Concedi il seguente ruolo Identity and Access Management (IAM) all'utente o al account di servizio che interagisce con l'API:

   • Amministratore agente AI Ordinazione di cibo (roles/foodorderingaiagent.admin): questo ruolo fornisce l'accesso completo per creare, leggere, aggiornare ed eliminare tutte le risorse dell'agente AI Ordinazione di cibo, inclusi brand, negozi e menu.

   Puoi concedere ruoli IAM utilizzando la console Google Cloud , lo strumento a riga di comando gcloud o l'API IAM. Per saperne di più, consulta Concedi un ruolo IAM.

   Per concedere il ruolo utilizzando la console Google Cloud :

   1. Nella console Google Cloud , vai alla pagina IAM.
   2. Fai clic su Aggiungi.
   3. Inserisci l'entità (email dell'utente o del account di servizio).
   4. Seleziona il ruolo Food Ordering AI Agent Admin.
   5. Fai clic su Salva.

   Senza le autorizzazioni appropriate, le chiamate API per creare o modificare brand, negozi o menu vengono rifiutate. Il ruolo Food Ordering Agent Viewer non è sufficiente per le attività descritte in questa guida, in quanto concede solo l'accesso di sola lettura.

Panoramica

L'API del menu dell'agente AI per l'ordinazione di cibo è progettata per essere flessibile e adattarsi a varie strutture di menu, da brevi elenchi di elementi autonomi a menu complessi con modificatori nidificati e pasti combinati. L'API si basa su alcuni concetti chiave:

• Menu:il contenitore di primo livello per tutte le entità ordinabili.
• Articolo:rappresenta un prodotto di primo livello ordinabile dal menu, ad esempio un pasto, un piatto principale o qualsiasi prodotto che può essere ordinato singolarmente. Gli Item possono fare riferimento agli ModifierGroup.
• ModifierGroup:una raccolta di opzioni Modifier che possono essere applicate a un Item o a un altro Modifier (consentendo la nidificazione). Alcuni esempi includono "Scegli la tua squadra", "Aggiungi condimenti" o "Seleziona il gusto della bevanda".
• Modificatore:una singola opzione all'interno di un ModifierGroup, ad esempio "Patatine fritte", "Formaggio extra" o "Coca-Cola". I modificatori possono modificare il prezzo e possono anche avere ModifierGroup nidificati.
• MenuCategory: utilizzato per organizzare i Item in sezioni per la visualizzazione e la comprensione della visualizzazione (ad es. "Antipasti", "Hamburger", "Bevande").

Concetti chiave e struttura

Questa sezione descrive in dettaglio i componenti principali dello schema dell'API Menu dell'agente AI per l'ordinazione di cibo e la loro struttura. Comprendere questi concetti è fondamentale per modellare correttamente i dati del menu.

Elementi

Ogni elemento distinto del menu deve essere definito come Item. I campi chiave includono:

• id: un identificatore univoco all'interno del menu.
• display_name: il nome rivolto al cliente.
• base_price: il prezzo base dell'articolo.
• modifier_groups: Riferimenti a ModifierGroup che possono essere applicati a questo articolo.
• category_ids: riferimenti agli ID MenuCategory a cui appartiene questo elemento.
• availability: specifica quando l'elemento è disponibile (ad es. per stato o fascia oraria). Se non specificato, il valore predefinito è STATUS_AVAILABLE.

Modificatori e ModifierGroups

I modificatori consentono la personalizzazione degli articoli.

• I ModifierGroup definiscono un insieme di scelte, inclusi vincoli come le selezioni minime o massime. Deve contenere almeno un Modifier.
• Modifiers represent the actual options. Possono avere un price_adjustment e possono fare riferimento in modo ricorsivo ad altri ModifierGroup per personalizzazioni nidificate (ad esempio, un Item "Menu" potrebbe avere un ModifierGroup "Scegli la tua bevanda" e la Modifier "Bibita" all'interno di questo gruppo potrebbe avere un ModifierGroup "Scegli il gusto").

Suggerimento: l'agente collabora attivamente con i clienti per soddisfare i vincoli specificati in ogni ModifierGroup. Ad esempio, se un Item (ad es. "Fajitas per due") fa riferimento a un ModifierGroup con min_selection_count 2 (ad es. "Due bevande") e un cliente ordina Item senza specificare una selezione per quel ModifierGroup (ad es. "Vorrei le fajitas per due"), l'agente collabora con il cliente per soddisfare i vincoli (ad es. "Quali due bevande vorresti?").

Esempio 1: condimenti

Un "Bacon Cheeseburger" Item potrebbe fare riferimento a un "Toppings" ModifierGroup. Questo ModifierGroup conterrà Modifier come "Formaggio extra", "Senza cipolle" e così via.

Esempio 2: pasti combinati (combo)

Alcuni menu hanno strutture complesse costituite da più scelte nidificate, come i pasti combinati o "combo". Le combinazioni possono essere modellate come un Item con diversi ModifierGroup che rappresentano i componenti della combinazione. Ad esempio, un "Combo hamburger" Item, composto da un piatto principale fisso abbinato a più opzioni per contorno e bevanda, potrebbe essere modellato con:

• Un ModifierGroup per il lato (ad es. "Side choices" (Scelte laterali).
  • Ogni opzione laterale è modellata come un Modifier (ad es. "Patatine fritte", "Insalata").
    • Ogni opzione di bevanda può fare riferimento a ModifierGroup nidificati (ad es. "Ice options", "Drink size") che a sua volta fa riferimento a Modifier (ad es. "No Ice", "Large drink").
• Un ModifierGroup per la bevanda (ad es. "Drinks" (Bevande).
  • Ogni opzione di bevanda è modellata come un Modifier.
    • Ogni opzione di bevanda può fare riferimento a ModifierGroup nidificati (ad es. "Ice options", "Drink size") che a sua volta fa riferimento a Modifier (ad es. "No Ice", "Large drink").
• Un ModifierGroup per i condimenti del piatto principale. (ad es. "Extra Cheese" (Formaggio extra), "Bacon" (Pancetta).

Disponibilità

Il messaggio Availability su Item e Modifier ti consente di specificare:

• status: STATUS_AVAILABLE, STATUS_OUT_OF_STOCK e così via.
• daypart_availability: link a ID di fasce orarie specifiche se l'articolo è disponibile solo in determinati orari (ad es. Menu colazione).

Attributi di integrazione

I messaggi Item, Modifier e ModifierGroup contengono un campo integration_attributes. Questo campo (ItemIntegrationAttributes, ModifierIntegrationAttributes e così via) contiene un google.protobuf.Struct chiamato custom_integration_attributes. Puoi utilizzarlo per archiviare dati chiave-valore arbitrari, ad esempio:

• ID del sistema point of sale (POS).
• SKU o altri codici interni.
• Qualsiasi altro metadato necessario per l'elaborazione degli ordini downstream o l'integrazione POS.

Questi dati vengono trasmessi in modo opaco dall'agente AI.

Etichette

Puoi utilizzare il campo labels nella risorsa Menu per collegare i metadati ai menu per facilitare l'integrazione e il debug.

Le etichette sono una funzionalità di comodità e non influiscono sul comportamento dell'agente AI.

Suggerimento: puoi utilizzare le etichette per annotare un Menu con l'identificatore di versione associato, il timestamp effettivo o un URL da cui sono stati recuperati i dati del menu. Ciò è utile per risalire alle sfumature del comportamento dell'agente a particolari dati di origine del menu.

Creare un menu

I menu vengono inseriti utilizzando la chiamata RPC CreateMenu all'interno di MenuService.

Passaggi

1. Trasforma i dati:converti i dati del menu esistenti (dal POS, dall'API o da un'altra origine) nella struttura definita dal messaggio google.cloud.foodorderingaiagent.v1beta.Menu. Ciò comporta la mappatura di articoli, modificatori, categorie e prezzi ai tipi di messaggi API corrispondenti.
2. Costruisci CreateMenuRequest:
   • Imposta il campo parent (ad es. projects/PROJECT/locations/LOCATION).
   • Compila il campo menu con l'oggetto Menu trasformato.
   • (Facoltativo) Fornisci un menu_id.
3. Chiama l'API:invia CreateMenuRequest all'endpoint MenuService.CreateMenu. L'API prima sanificherà il menu, poi lo convaliderà e restituirà l'oggetto Menu finale.
4. Gestisci gli aggiornamenti del menu:a ogni aggiornamento dei dati di origine del menu (ad es. quando viene introdotto un nuovo prodotto o quando un prodotto non è più disponibile), deve essere creato un nuovo Menu che rifletta i dati di origine aggiornati, seguendo la gestione degli aggiornamenti del menu.

Indicazioni per la trasformazione dei dati

La logica specifica per la trasformazione dei dati del menu dipende dal formato e dalla struttura del sistema di origine (ad es. API POS, schema del database). Ecco un approccio generale:

• Esporta dati:ottieni un'esportazione completa dei dati del menu, inclusi tutti gli articoli, i modificatori, i prezzi e le relazioni.
• Mappa entità:
  • Identifica le entità corrispondenti nello schema dell'API Food Ordering AI Agent per ogni elemento nei dati di origine. Ad esempio, le "voci di menu" del tuo POS verranno probabilmente mappate agli oggetti Item. "Opzioni ordine" o "componenti aggiuntivi" verranno mappati a Modifier e ModifierGroup.
  • Stabilisci le relazioni utilizzando gli ID. Ad esempio, collega gli Item alle ModifierGroup applicabili utilizzando il campo di riferimento modifier_groups.
• Gestisci strutture nidificate:se il menu ha modificatori nidificati (ad es. la scelta del gusto di una bibita per un pasto combinato), modella questa situazione facendo in modo che Modifiers faccia riferimento ad altri ModifierGroups.
• Compila gli attributi:compila i campi come display_name, base_price, price_adjustment e availability in base ai dati di origine.
• Includi ID POS:memorizza gli ID POS o di sistema interni per ogni articolo, modificatore e gruppo nel campo custom_integration_attributes. In questo modo, puoi tradurre l'Order prodotto dall'agente nella rappresentazione di un ordine finale o di un carrello in corso nella tua applicazione.
• Scripting:probabilmente dovrai scrivere uno script (ad es. in Python, Node.js, Go) per recuperare i dati dall'origine, eseguire la trasformazione e chiamare il metodo CreateMenu. Questo script utilizzerà le librerie client Google Cloud per l'autenticazione e l'interazione con le API.

Flusso di lavoro di trasformazione concettuale:

Questo flusso di lavoro descrive il processo di trasformazione dei dati del menu da un sistema di origine nel formato dell'API Food Ordering AI Agent:

1. Estrai e mappa le categorie:
   • Identifica le categorie o le sezioni nei dati di origine (ad es. "Antipasti", "Portate principali").
   • Trasformali in un oggetto MenuCategory con id e display_name unici.
2. Estrai e mappa elementi:
   • Identifica gli articoli vendibili nei dati di origine.
   • Trasforma ciascuno in un oggetto Item, compilando id, display_name, base_price e availability.
   • Mappa ogni Item alle relative categorie utilizzando il campo category_ids.
   • Memorizza gli identificatori del sistema di origine del negozio (come PLU o SKU) in item.integration_attributes.custom_integration_attributes.
3. Estrai e mappa i modificatori:
   • Identifica personalizzazioni, opzioni o componenti aggiuntivi degli articoli nei dati di origine.
   • Opzioni correlate al gruppo (ad es. "Side Options", "Drink Choices", "Extra Toppings") in oggetti ModifierGroup. Definisci regole di selezione minime e massime per ogni ModifierGroup.
   • Trasforma ogni singola opzione (ad es. "Patatine fritte", "Coca-Cola", "Formaggio extra") in oggetti Modifier all'interno del ModifierGroup appropriato. Compila price_adjustment, se applicabile.
   • Memorizza gli identificatori del sistema di origine in modifier_group.integration_attributes.custom_integration_attributes e modifier.integration_attributes.custom_integration_attributes.
4. Stabilisci relazioni:
   • Per ogni Item, compila il campo modifier_groups con i riferimenti ai id di ModifierGroup che lo riguardano.
   • Se un Modifier consente un'ulteriore personalizzazione (ad es. la scelta di un gusto per il modificatore "Bibita"), compila il campo modifier_groups per creare modificatori nidificati.
5. Assemblaggio e importazione:
   • Combina tutti gli oggetti MenuCategory, Item, ModifierGroup e Modifier negli elenchi all'interno di un unico messaggio Menu.
   • Chiama l'RPC CreateMenu con il messaggio Menu completamente assemblato come input.

Gestione degli aggiornamenti del menu

Menu è immutabile. Una volta creato un menu utilizzando la chiamata RPC CreateMenu, non può essere modificato. Per propagare gli aggiornamenti del menu in un menu, ad esempio modificando i prezzi degli articoli, le opzioni o la disponibilità, devi creare una nuova risorsa menu chiamando di nuovo CreateMenu. Ogni versione del menu deve essere importata come nuova risorsa Menu con un menu_id univoco.

La procedura per l'importazione di una nuova versione di un menu è identica a quella per l'importazione del menu per la prima volta e prevede gli stessi passaggi di sanificazione e convalida. Durante la gestione degli ordini, il comportamento dell'agente rifletterà sempre l'Menu creato più di recente associato all'Store a cui viene fatto riferimento nella configurazione della sessione.

Suggerimento: le etichette sono un modo utile per associare metadati che distinguono i Menu correlati. La diagnosi dei problemi operativi è spesso più semplice quando ogni Menu è annotato con informazioni che identificano l'evento che ne ha attivato la creazione e la fonte dei contenuti.

Pulizia automatica del menu

L'API CreateMenu esegue automaticamente diversi passaggi di sanificazione per correggere i problemi comuni e garantire che i contenuti del menu siano rappresentati in modo coerente in tutta l'API. Dopo queste sanifiche, vengono applicate le convalide per semplificare l'integrazione dei menu per i client:

• Disponibilità predefinita: Item e Modifier senza un Availability.Status esplicito sono impostati su STATUS_AVAILABLE.
• Elimina entità non referenziate:Modifier e ModifierGroup che non sono referenziati in modo transitivo da alcun Item vengono rimossi dal menu, in quanto non possono essere ordinati.
• Elimina gruppi di modificatori vuoti:i ModifierGroup che non contengono modifier_ids vengono eliminati e tutti i riferimenti vengono rimossi.

Convalida del menu

Dopo la sanificazione, l'API convalida il menu in base a un insieme rigoroso di regole per garantire che sia ben formato e possa essere utilizzato in modo affidabile dall'agente AI. Se la convalida non va a buon fine, la chiamata CreateMenu restituirà un errore che descrive in dettaglio i problemi. Le principali convalide includono:

• Campi obbligatori:garantisce la presenza di tutti i campi obbligatori, come id, display_name e availability.status.
• ID univoci:tutti gli Item, i Modifier e i ModifierGroup devono avere ID univoci all'interno del menu.
• Unique display names:
  • Tutti i Item devono avere display_name univoci.
  • All'interno di un determinato ModifierGroup, tutti i Modifier contenuti devono avere display_name univoci.
• Integrità referenziale:
  • Tutti i modifier_group_ids a cui fanno riferimento i Item o i Modifier devono essere presenti nel menu.
  • Tutti i modifier_ids a cui fanno riferimento i ModifierGroup devono essere presenti nel menu.
  • I modificatori predefiniti specificati in ModifierGroupReference devono esistere in ModifierGroup a cui viene fatto riferimento.
  • Se un Modifier utilizza item_id per fare riferimento a un Item, quest'ultimo deve esistere.Item
• Vincoli del gruppo di modificatori:
  • Il campo ModifierGroup non può essere vuoto.
  • I conteggi minimi o massimi di selezione all'interno di ModifierGroup vengono controllati per verificare la coerenza logica.
  • Item o Modifier livello modifier_constraints vengono convalidati in base ai vincoli di conteggio della selezione dei ModifierGroup a cui viene fatto riferimento per garantire che siano soddisfacenti.
• Profondità di nidificazione:la profondità dei modificatori nidificati è limitata (ad es. Item -> ModifierGroup -> Modifier -> ModifierGroup -> Modifier...) fino a un massimo di 5 livelli.
• Convalida delle fasce orarie:se le fasce orarie vengono utilizzate in Availability, devono essere definite nella risorsa Store associata.
• Riferimenti agli elementi modificatori: Modifierche fanno riferimento a un Item utilizzando item_id non possono avere campi come display_name o availability impostati, in quanto vengono ereditati dal Item a cui viene fatto riferimento.

Un errore in una qualsiasi di queste regole di convalida impedirà la creazione o l'aggiornamento del menu. Il messaggio di errore fornirà dettagli sulle entità che causano la violazione.

Riferimento API

Per informazioni dettagliate su tutti i messaggi e i campi, consulta il riferimento RPC dell'API Food Ordering AI Agent.

Best practice

• ID unici:assicurati che tutti i campi id nell'ambito Menu (per Item, Modifier, ModifierGroup, MenuCategory) siano unici.
• Nomi chiari:utilizza display_name chiari e adatti ai clienti. Fornisci display_name distinti per prodotti semanticamente diversi per indirizzare l'agente a disambiguare in modo appropriato.
• Combinazioni di modelli efficaci:combina i modelli come Item con ModifierGroup che rappresentano contorni, bevande e altre scelte, come descritto in Combinazioni di modelli. In questo modo, l'agente può guidare correttamente i clienti nella selezione delle combinazioni.
• Utilizza gli attributi di integrazione:memorizza gli identificatori POS o di sistema interni necessari in custom_integration_attributes per facilitare l'integrazione degli ordini.
• Gestisci disponibilità:mantieni aggiornato lo stato Availability.
• Test approfondito:dopo l'importazione, verifica la comprensione del menu da parte dell'agente con varie combinazioni di ordini.