Intégrer les données de menu à l'aide de l'API de l'agent IA de commande de repas

Ce guide explique comment structurer, transformer et ingérer les données de votre menu de restaurant dans l'API Menu de l'agent d'IA pour la commande de repas. Vous permettez ainsi à l'agent IA de comprendre votre menu et de prendre les commandes des clients avec précision.

Avant de commencer

Avant de pouvoir ingérer et gérer des menus à l'aide de l'API Food Ordering AI Agent, vous devez d'abord :

  1. Activez l'API Food Ordering AI Agent :

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

  2. Assurez-vous de disposer des autorisations IAM nécessaires. Attribuez le rôle IAM (Identity and Access Management) suivant à l'utilisateur ou au compte de service qui interagit avec l'API :

    • Administrateur de l'agent IA pour la commande de repas (roles/foodorderingaiagent.admin) : ce rôle permet de créer, lire, mettre à jour et supprimer toutes les ressources de l'agent IA pour la commande de repas, y compris les marques, les magasins et les menus.

    Vous pouvez attribuer des rôles IAM à l'aide de la console Google Cloud , de l'outil de ligne de commande gcloud ou de l'API IAM. Pour en savoir plus, consultez Attribuer un rôle IAM.

    Pour attribuer le rôle à l'aide de la console Google Cloud  :

    1. Dans la console Google Cloud , accédez à la page IAM.
    2. Cliquez sur Ajouter.
    3. Saisissez le compte principal (adresse e-mail de l'utilisateur ou du compte de service).
    4. Sélectionnez le rôle Administrateur de l'agent d'IA pour les commandes de repas.
    5. Cliquez sur Enregistrer.

    Sans les autorisations appropriées, les appels d'API permettant de créer ou de modifier des marques, des magasins ou des menus sont refusés. Le rôle Food Ordering Agent Viewer ne suffit pas pour les tâches décrites dans ce guide, car il n'accorde qu'un accès en lecture seule.

Présentation

L'API Menu de l'agent d'IA de commande de nourriture est conçue pour être flexible et s'adapter à différentes structures de menu, qu'il s'agisse de courtes listes d'articles autonomes ou de menus complexes avec des modificateurs imbriqués et des menus combinés. L'API repose sur quelques concepts clés :

  • Menu : conteneur de premier niveau pour toutes les entités pouvant être commandées.
  • Item : représente un produit de premier niveau pouvant être commandé dans le menu, comme un plat, une entrée ou tout produit pouvant être commandé seul. Les Item peuvent faire référence aux ModifierGroup.
  • ModifierGroup : collection d'options Modifier pouvant être appliquées à un Item ou à un autre Modifier (permettant l'imbrication). Par exemple, "Choisissez votre accompagnement", "Ajouter des garnitures" ou "Sélectionnez la boisson".
  • Option : option individuelle dans un ModifierGroup, par exemple "Frites", "Fromage supplémentaire" ou "Coca-Cola". Les modificateurs peuvent ajuster le prix et avoir leurs propres ModifierGroup imbriqués.
  • MenuCategory : utilisé pour organiser les Item en sections pour l'affichage et la compréhension de l'affichage (par exemple, "Apéritifs", "Burgers", "Boissons").

Concepts clés et structure

Cette section décrit en détail les composants principaux du schéma de l'API Menu de l'agent d'IA de commande de repas et leur structure. Il est essentiel de comprendre ces concepts pour modéliser correctement les données de votre menu.

Éléments

Chaque élément distinct de votre menu doit être défini comme un Item. Voici quelques-uns des champs clés :

  • id : identifiant unique dans le menu.
  • display_name : nom visible par le client.
  • base_price : prix de base de l'article.
  • modifier_groups : références aux ModifierGroup pouvant s'appliquer à cet élément.
  • category_ids : références aux ID MenuCategory auxquels appartient cet élément.
  • availability : spécifie quand l'élément est disponible (par exemple, par état ou par tranche horaire). En l'absence de spécification, la valeur par défaut est STATUS_AVAILABLE.

Modificateurs et ModifierGroups

Les modificateurs permettent de personnaliser les éléments.

  • Les ModifierGroup définissent un ensemble de choix, y compris des contraintes telles que le nombre minimal ou maximal de sélections. Doit contenir au moins un Modifier.
  • Les Modifier représentent les options réelles. Ils peuvent avoir un price_adjustment et peuvent faire référence de manière récursive à d'autres ModifierGroup pour des personnalisations imbriquées (par exemple, un Item "Menu" peut avoir un ModifierGroup "Choisissez votre boisson", et le Modifier "Soda" de ce groupe peut avoir un ModifierGroup "Choisissez votre saveur").

Exemple 1 : Garnitures

Un "Bacon Cheeseburger" Item peut faire référence à une "Garniture" ModifierGroup. Ce ModifierGroup contiendrait des Modifier telles que "Extra fromage", "Sans oignons", etc.

Exemple 2 : Menus combinés

Certains menus ont des structures complexes composées de plusieurs choix imbriqués, comme les menus combinés. Les combos peuvent être modélisés en tant qu'Item avec plusieurs ModifierGroup représentant les composants du combo. Par exemple, un "menu Burger" Item, composé d'un plat principal fixe associé à plusieurs options pour l'accompagnement et la boisson, peut être modélisé comme suit :

  • ModifierGroup pour le côté (par exemple, "Choix secondaires").
    • Chaque option de côté est modélisée sous la forme d'un Modifier (par exemple, "Frites", "Salade").
      • Chaque option de boisson peut faire référence à des ModifierGroup imbriqués (par exemple, "Ice options", "Drink size") qui fait référence à Modifiers (par exemple, "No Ice", "Large drink", respectivement).
  • ModifierGroup pour la boisson (par exemple, "Drinks").
    • Chaque boisson est modélisée sous la forme d'un Modifier.
      • Chaque option de boisson peut faire référence à des ModifierGroup imbriqués (par exemple, "Ice options", "Drink size") qui fait référence à Modifier (par exemple, "No Ice", "Large drink").
  • ModifierGroup pour les garnitures de l'entrée. (par exemple, "Extra fromage", "Bacon").

Disponibilité

Le message Availability sur les Item et les Modifier vous permet de spécifier les éléments suivants :

  • status : STATUS_AVAILABLE, STATUS_OUT_OF_STOCK, etc.
  • daypart_availability : liens vers des ID de tranche horaire spécifiques si l'article n'est disponible qu'à certaines heures (par exemple, "Menu du petit-déjeuner").

Attributs d'intégration

Les messages Item, Modifier et ModifierGroup contiennent un champ integration_attributes. Ce champ (ItemIntegrationAttributes, ModifierIntegrationAttributes, etc.) contient un google.protobuf.Struct appelé custom_integration_attributes. Vous pouvez l'utiliser pour stocker des données clé-valeur arbitraires, par exemple :

  • ID provenant de votre système de point de vente.
  • SKU ou autres codes internes.
  • Toutes les autres métadonnées nécessaires au traitement des commandes en aval ou à l'intégration du point de vente.

Ces données sont transmises de manière opaque par l'agent d'IA.

Étiquettes

Vous pouvez utiliser le champ labels de la ressource Menu pour associer des métadonnées aux menus afin de faciliter l'intégration et le débogage.

Les libellés sont une fonctionnalité pratique et n'ont aucune incidence sur le comportement de l'agent d'IA.

Créer un menu

Les menus sont ingérés à l'aide de l'appel RPC CreateMenu dans MenuService.

Étapes

  1. Transformez vos données : convertissez les données de votre menu existant (provenant de votre système de point de vente, de votre API ou d'une autre source) dans la structure définie par le message google.cloud.foodorderingaiagent.v1beta.Menu. Cela implique de mapper vos articles, vos modificateurs, vos catégories et vos prix sur les types de messages API correspondants.
  2. Construisez CreateMenuRequest :
    • Définissez le champ parent (par exemple, projects/PROJECT/locations/LOCATION).
    • Renseignez le champ menu avec votre objet Menu transformé.
    • Vous pouvez éventuellement fournir un menu_id.
  3. Appelez l'API : envoyez CreateMenuRequest au point de terminaison MenuService.CreateMenu. L'API commence par assainir le menu, puis le valider et renvoyer l'objet Menu final.
  4. Mises à jour du menu : à chaque mise à jour des données source du menu (par exemple, lorsqu'un nouveau produit est introduit ou lorsqu'un produit devient indisponible), un nouveau Menu doit être créé pour refléter les données source mises à jour, en suivant les mises à jour du menu.

Conseils pour la transformation des données

La logique spécifique pour transformer les données de votre menu dépendra du format et de la structure de votre système source (par exemple, API de point de vente, schéma de base de données). Voici une approche générale :

  • Exporter les données : obtenez une exportation complète des données de votre menu, y compris tous les articles, les modificateurs, les prix et les relations.
  • Mappage d'entités :
    • Identifiez les entités correspondantes dans le schéma de l'API Food Ordering AI Agent pour chaque élément de vos données sources. Par exemple, les "éléments de menu" de votre point de vente seront probablement mappés sur des objets Item. Les "options de commande" ou les "modules complémentaires" seront mappés sur les Modifier et les ModifierGroup.
    • Établissez des relations à l'aide d'ID. Par exemple, associez les Item aux ModifierGroup applicables à l'aide du champ de référence modifier_groups.
  • Gérer les structures imbriquées : si votre menu comporte des modificateurs imbriqués (par exemple, le choix d'une boisson pour le soda d'un menu), modélisez-le en faisant référence à d'autres ModifierGroup dans les Modifier.
  • Renseignez les attributs : remplissez les champs tels que display_name, base_price, price_adjustment et availability en fonction de vos données sources.
  • Incluez les ID de point de vente : il est essentiel que vous stockiez les ID de point de vente ou de système internes pour chaque article, modificateur et groupe dans le champ custom_integration_attributes. Cela vous permet de traduire le Order produit par l'agent dans la représentation de votre application d'une commande finale ou d'un panier en cours.
  • Scripting : vous devrez probablement écrire un script (en Python, Node.js ou Go, par exemple) pour extraire les données de votre source, effectuer la transformation et appeler la méthode CreateMenu. Ce script utilisera les bibliothèques clientes Google Cloud pour l'authentification et l'interaction avec l'API.

Workflow de transformation conceptuelle :

Ce workflow décrit le processus de transformation des données de menu d'un système source au format de l'API Food Ordering AI Agent :

  1. Extraire et mapper les catégories :
    • Identifiez les catégories ou sections dans vos données sources (par exemple, "Entrées", "Plats").
    • Transformez chacun d'eux en objet MenuCategory avec un id et un display_name uniques.
  2. Extraire et mapper des éléments :
    • Identifiez les articles vendables dans vos données sources.
    • Transformez chacun d'eux en objet Item, en remplissant id, display_name, base_price et availability.
    • Mappez chaque Item à ses catégories à l'aide du champ category_ids.
    • Stockez les identifiants du système source (comme le code PLU ou le SKU) dans item.integration_attributes.custom_integration_attributes.
  3. Extraire et mapper les modificateurs :
    • Identifiez les personnalisations, les options ou les modules complémentaires des articles dans vos données sources.
    • Regroupez les options associées (par exemple, "Options secondaires", "Choix de boisson", "Garnitures supplémentaires") dans des objets ModifierGroup. Définissez des règles de sélection minimale et maximale pour chaque ModifierGroup.
    • Transformez chaque option individuelle (par exemple, "Frites", "Coca", "Fromage supplémentaire") dans des objets Modifier au sein de l'ModifierGroup approprié. Renseignez price_adjustment, le cas échéant.
    • Stockez les identifiants du système source dans modifier_group.integration_attributes.custom_integration_attributes et modifier.integration_attributes.custom_integration_attributes.
  4. Établir des relations
    • Pour chaque Item, renseignez son champ modifier_groups avec des références aux id de ModifierGroup qui s'y appliquent.
    • Si un Modifier permet une personnalisation plus poussée (par exemple, le choix d'un parfum pour un modificateur "Soda"), renseignez son champ modifier_groups pour créer des modificateurs imbriqués.
  5. Assembler et ingérer :
    • Combinez tous les objets MenuCategory, Item, ModifierGroup et Modifier dans les listes d'un même message Menu.
    • Appelez le RPC CreateMenu avec le message Menu entièrement assemblé comme entrée.

Gérer les mises à jour du menu

Menu est immuable. Une fois qu'un menu est créé à l'aide de l'appel RPC CreateMenu, il ne peut plus être modifié. Pour propager les modifications apportées à un menu (par exemple, les prix des articles, les options ou la disponibilité), vous devez créer une ressource de menu en appelant de nouveau CreateMenu. Chaque version de votre menu doit être ingérée en tant que nouvelle ressource Menu avec un menu_id unique.

Le processus d'ingestion d'une nouvelle version d'un menu est identique à celui de l'ingestion du menu pour la première fois. Il suit les mêmes étapes de nettoyage et de validation. Lors du traitement des commandes, le comportement de l'agent reflète toujours le Menu créé le plus récemment associé au Store référencé dans la configuration de la session.

Assainissement automatique des menus

L'API CreateMenu effectue automatiquement plusieurs étapes de nettoyage pour corriger les problèmes courants et s'assurer que le contenu du menu est représenté de manière cohérente dans l'ensemble de l'API. Les validations sont appliquées après ces assainissements pour simplifier l'intégration des menus pour les clients :

  • Disponibilité par défaut : les Item et les Modifier sans Availability.Status explicite sont définis sur STATUS_AVAILABLE.
  • Supprimer les entités non référencées : les Modifier et les ModifierGroup qui ne sont pas référencés de manière transitive par un Item sont supprimés du menu, car ils ne peuvent pas être commandés.
  • Supprimer les groupes de modificateurs vides : les ModifierGroups qui ne contiennent aucun modifier_ids sont supprimés, et toutes les références à ces groupes sont supprimées.

Après l'assainissement, l'API valide le menu en fonction d'un ensemble strict de règles pour s'assurer qu'il est bien formé et qu'il peut être utilisé de manière fiable par l'agent d'IA. Si la validation échoue, l'appel CreateMenu renvoie une erreur détaillant les problèmes. Voici quelques exemples de validations clés :

  • Champs obligatoires : vérifie que tous les champs obligatoires, comme id, display_name et availability.status, sont présents.
  • Identifiants uniques : tous les Item, Modifier et ModifierGroup doivent avoir des identifiants uniques dans le menu.
  • Noms à afficher uniques :
    • Tous les Item doivent avoir des display_name uniques.
    • Dans un ModifierGroup donné, tous les Modifier contenus doivent avoir des display_name uniques.
  • Intégrité des références
    • Tous les modifier_group_ids référencés par des Item ou des Modifier doivent exister dans le menu.
    • Tous les modifier_ids référencés par les ModifierGroup doivent exister dans le menu.
    • Les modificateurs par défaut spécifiés dans ModifierGroupReference doivent exister dans le ModifierGroup référencé.
    • Si un Modifier utilise item_id pour faire référence à un Item, ce Item doit exister.
  • Modifier les contraintes de groupe
    • Les ModifierGroup ne peuvent pas être vides.
    • La cohérence logique du nombre de sélections minimal ou maximal dans les ModifierGroup est vérifiée.
    • Les niveaux Item ou Modifier modifier_constraints sont validés par rapport aux contraintes de nombre de sélections des ModifierGroup référencés pour s'assurer qu'ils sont satisfaisants.
  • Profondeur d'imbrication : la profondeur des modificateurs imbriqués est limitée (par exemple, Item > ModifierGroup > Modifier > ModifierGroup > Modifier… (jusqu'à cinq niveaux).
  • Validation des périodes de la journée : si des périodes de la journée sont utilisées dans Availability, elles doivent être définies dans la ressource Store associée.
  • Références aux éléments de modificateur : les Modifiers faisant référence à un Item à l'aide de item_id ne peuvent pas avoir de champs tels que display_name ou availability définis, car ils sont hérités du Item référencé.

Si l'une de ces règles de validation n'est pas respectée, le menu ne pourra pas être créé ni mis à jour. Le message d'erreur indiquera les entités à l'origine du non-respect.

Documentation de référence de l'API

Pour obtenir des informations complètes sur tous les messages et champs, consultez la documentation de référence de l'API RPC de l'agent d'IA pour la commande de repas.

Bonnes pratiques

  • ID uniques : assurez-vous que tous les champs id dans le champ d'application Menu (pour Item, Modifier, ModifierGroup, MenuCategory) sont uniques.
  • Noms clairs : utilisez des display_name clairs et faciles à comprendre pour les clients. Fournissez des display_name distincts pour les produits sémantiquement différents afin d'aider l'agent à les différencier correctement.
  • Combinez efficacement les modèles : modélisez les menus combinés comme un Item avec des ModifierGroup représentant les accompagnements, les boissons et autres choix, comme décrit dans Menus combinés. Cela permet à l'agent de guider correctement les clients dans la sélection de combinaisons.
  • Utilisez les attributs d'intégration : stockez tous les identifiants de système interne ou de point de vente nécessaires dans custom_integration_attributes pour faciliter l'intégration des commandes.
  • Gérer la disponibilité : veillez à ce que l'état Availability soit à jour.
  • Effectuez des tests approfondis : après l'ingestion, testez la compréhension du menu par l'agent avec différentes combinaisons de commandes.