デリバリー＆テイクアウト AI エージェント API を使用してメニューデータを統合する

このガイドでは、レストランのメニューデータを構造化、変換して、Food Ordering AI Agent Menu API に取り込む方法について説明します。これにより、AI エージェントがメニューの内容を理解し、お客様からの注文を正確に受け付けることができます。

始める前に

Food Ordering AI Agent API を使用してメニューを取り込み、管理する前に、次の操作を行います。

  1. Food Ordering AI Agent API を有効にします。

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

  2. 必要な IAM 権限があることを確認します。API とやり取りするユーザーまたはサービス アカウントに、次の Identity and Access Management（IAM）ロールを付与します。

    • Food Ordering Agent 管理者（roles/foodorderingaiagent.admin）: このロールは、ブランド、店舗、メニューなど、すべての Food Ordering AI エージェント リソースの作成、読み取り、更新、削除に対する完全なアクセス権を提供します。

    IAM ロールを付与するには、 Google Cloud コンソール、gcloud コマンドライン ツール、または IAM API を使用します。詳細については、IAM ロールを付与するをご覧ください。

    Google Cloud コンソールを使用してロールを付与するには:

    1. Google Cloud コンソールで、[IAM] ページに移動します。
    2. [追加] をクリックします。
    3. プリンシパル（ユーザーまたはサービス アカウントのメールアドレス）を入力します。
    4. [Food Ordering AI Agent Admin] ロールを選択します。
    5. [保存] をクリックします。

    適切な権限がないと、ブランド、店舗、メニューの作成または変更を行う API 呼び出しは拒否されます。Food Ordering Agent Viewer ロールは読み取り専用アクセス権のみを付与するため、このガイドで説明するタスクには不十分です。

概要

Food Ordering AI Agent Menu API は、柔軟に設計されており、単品の短いリストから、ネストされた修飾子や組み合わせメニューを含む複雑なメニューまで、さまざまなメニュー構造に対応できます。API はいくつかの重要なコンセプトに基づいて構築されています。

  • メニュー: 注文可能なすべてのエンティティの最上位コンテナ。
  • Item: メニューから注文できる最上位の商品（食事、メイン料理、単品で注文できる商品など）を表します。Item は ModifierGroup を参照できます。
  • ModifierGroup: Item または別の Modifier に適用できる Modifier オプションのコレクション（ネストが可能）。例: 「Choose Your Side」（サイドメニューを選択）、「Add Toppings」（トッピングを追加）、「Select Drink Flavor」（ドリンクのフレーバーを選択）。
  • 修飾子: ModifierGroup 内の個々のオプション（「フライドポテト」、「チーズ増量」、「コーラ」など）。修飾子は価格を調整でき、独自のネストされた ModifierGroup を持つこともできます。
  • MenuCategory: Item をセクションに整理して表示し、理解を深めるために使用します（例: "Appetizers", "Burgers", "Drinks"）。

主なコンセプトと構造

このセクションでは、Food Ordering AI Agent Menu API スキーマのコア コンポーネントと、その構造について詳しく説明します。これらのコンセプトを理解することは、メニューデータを正しくモデル化するうえで重要です。

アイテム

メニューの個別のアイテムはそれぞれ Item として定義する必要があります。主なフィールドは次のとおりです。

  • id: メニュー内の一意の識別子。
  • display_name: お客様向けの名称。
  • base_price: 商品の基本価格。
  • modifier_groups: このアイテムに適用できる ModifierGroup への参照。
  • category_ids: このアイテムが属する MenuCategory ID への参照。
  • availability: アイテムが利用可能になるタイミングを指定します（ステータスや時間帯など）。指定しない場合のデフォルトは STATUS_AVAILABLE です。

修飾子と ModifierGroup

修飾子を使用すると、アイテムをカスタマイズできます。

  • ModifierGroup は、最小選択数や最大選択数などの制約を含む選択肢のセットを定義します。少なくとも 1 つの Modifier を含める必要があります。
  • Modifier は実際のオプションを表します。price_adjustment を含めることができ、ネストされたカスタマイズのために他の ModifierGroup を再帰的に参照できます（たとえば、「食事のセット」の Item に「飲み物を選ぶ」の ModifierGroup が含まれ、そのグループ内の「ソーダ」の Modifier に「フレーバーを選ぶ」の ModifierGroup が含まれるなど）。

例 1: トッピング

「ベーコン チーズバーガー」Item は「トッピング」ModifierGroup を参照する場合があります。この ModifierGroup には、「チーズ増量」、「玉ねぎ抜き」などの Modifier が含まれます。

例 2: セットメニュー（コンボ）

一部のメニューは、組み合わせメニューなどの複数のネストされた選択肢で構成される複雑な構造になっています。コンボは、コンボのコンポーネントを表す複数の ModifierGroup を持つ Item としてモデル化できます。たとえば、固定のメイン料理と複数のサイドメニューとドリンクのオプションを組み合わせた「バーガー コンボ」Item は、次のようにモデル化できます。

  • サイドの ModifierGroup（「Side choices」）。
    • 各サイド オプションは Modifier としてモデル化されます（例: 「フライドポテト」、「サラダ」）。
      • 各ドリンク オプションは、ネストされた ModifierGroup を参照できます（例: 「氷のオプション」、「飲み物のサイズ」）で、Modifier（「氷なし」、「飲み物大」など）を参照します。
  • 飲み物の ModifierGroup（「Drinks」）。
    • 各ドリンク オプションは Modifier としてモデル化されます。
      • 各ドリンク オプションは、ネストされた ModifierGroup を参照できます（例: 「氷のオプション」、「飲み物のサイズ」）で、Modifier（「氷なし」、「飲み物（大）」など）を参照します。
  • メイン料理のトッピングの ModifierGroup。（例: 「チーズ増量」、「ベーコン」）。

対象

Item と Modifier の Availability メッセージでは、次の指定が可能です。

  • status: STATUS_AVAILABLE、STATUS_OUT_OF_STOCK（以下同様）
  • daypart_availability: アイテムが特定の時間帯にのみ利用可能な場合（例: 「朝食メニュー」）。

統合属性

Item、Modifier、ModifierGroup メッセージには integration_attributes フィールドが含まれています。このフィールド（ItemIntegrationAttributes、ModifierIntegrationAttributes など）には、custom_integration_attributes という google.protobuf.Struct が保持されます。これを使用して、次のような任意の Key-Value データを保存できます。

  • 販売時点情報管理（POS）システムの ID。
  • SKU やその他の内部コード。
  • ダウンストリームの注文処理や POS 統合に必要なその他のメタデータ。

このデータは AI エージェントによって透過的に渡されます。

ラベル

Menu リソースの labels フィールドを使用して、統合とデバッグに役立つようにメタデータをメニューに関連付けることができます。

ラベルは便利な機能であり、AI エージェントの動作には影響しません。

メニューの作成

メニューは、MenuService 内の CreateMenu RPC 呼び出しを使用して取り込まれます。

手順

  1. データを変換する: 既存のメニューデータ（POS、API、その他のソースから）を google.cloud.foodorderingaiagent.v1beta.Menu メッセージで定義された構造に変換します。これには、商品、修飾子、カテゴリ、価格を対応する API メッセージ タイプにマッピングすることが含まれます。
  2. CreateMenuRequest を構築する:
    • parent フィールドを設定します（例: projects/PROJECT/locations/LOCATION）。
    • 変換された Menu オブジェクトを menu フィールドに入力します。
    • 必要に応じて menu_id を指定します。
  3. API を呼び出す: CreateMenuRequest を MenuService.CreateMenu エンドポイントに送信します。API は最初にメニューをサニタイズし、検証してから、最終的な Menu オブジェクトを返します。
  4. メニューの更新を処理する: メニューのソースデータが更新されるたび（新商品が導入されたときや、商品が販売終了になったときなど）、メニューの更新の処理に沿って、更新されたソースデータを反映した新しい Menu を作成する必要があります。

データ変換のガイダンス

メニューデータを変換する具体的なロジックは、ソースシステムの形式と構造（例: POS API、データベース スキーマ）。一般的なアプローチは次のとおりです。

  • データのエクスポート: すべてのアイテム、修飾子、価格、関係を含むメニューデータの完全なエクスポートを取得します。
  • マップ エンティティ:
    • ソースデータの各要素に対応するエンティティを Food Ordering AI Agent API スキーマで特定します。たとえば、POS の「メニュー アイテム」は Item オブジェクトにマッピングされる可能性があります。「注文オプション」または「アドオン」は Modifier と ModifierGroup にマッピングされます。
    • ID を使用して関係を確立します。たとえば、modifier_groups 参照フィールドを使用して、Item を該当する ModifierGroup にリンクします。
  • ネストされた構造を処理する: メニューにネストされた修飾子（コンボ ミールのソーダのフレーバーを選択するなど）がある場合は、Modifier が他の ModifierGroup を参照するようにモデル化します。
  • 属性を入力: ソースデータに基づいて、display_name、base_price、price_adjustment、availability などのフィールドに入力します。
  • POS ID を含める: custom_integration_attributes フィールド内の各アイテム、修飾子、グループの内部 POS ID またはシステム ID を保存します。これにより、エージェントが生成した Order を、最終的な注文または進行中のカートのアプリケーションの表現に戻すことができます。
  • スクリプト作成: ソースからデータを取得し、変換を実行して、CreateMenu メソッドを呼び出すスクリプト（Python、Node.js、Go など）を作成する必要があります。このスクリプトは、認証と API のやり取りに Google Cloud クライアント ライブラリを使用します。

概念的な変換のワークフロー:

このワークフローは、ソース システムから Food Ordering AI Agent API 形式にメニューデータを変換するプロセスを示しています。

  1. カテゴリを抽出してマッピングする:
    • ソースデータ内のカテゴリまたはセクションを特定します（例: 「Appetizers」、「Entrees」）。
    • それぞれを一意の id と display_name を持つ MenuCategory オブジェクトに変換します。
  2. 項目の抽出とマッピング:
    • ソースデータ内の販売可能なアイテムを特定します。
    • それぞれを Item オブジェクトに変換し、id、display_name、base_price、availability を入力します。
    • category_ids フィールドを使用して、各 Item をカテゴリにマッピングします。
    • ソースシステム ID（PLU や SKU など）を item.integration_attributes.custom_integration_attributes に保存します。
  3. 抽出とマップの修飾子:
    • ソースデータでアイテムのカスタマイズ、オプション、アドオンを特定します。
    • 関連するオプションをグループ化します（例: （「Side Options」、「Drink Choices」、「Extra Toppings」など）を ModifierGroup オブジェクトに変換します。各 ModifierGroup で最小選択ルールと最大選択ルールを定義します。
    • 個々のオプション（「フライドポテト」、「コーラ」、「チーズ増量」）を、適切な ModifierGroup 内の Modifier オブジェクトに変換します。該当する場合は price_adjustment を入力します。
    • ソースシステムの ID を modifier_group.integration_attributes.custom_integration_attributes と modifier.integration_attributes.custom_integration_attributes に保存します。
  4. 関係を確立する:
    • 各 Item について、その modifier_groups フィールドに、適用される ModifierGroup の id への参照を入力します。
    • Modifier でさらなるカスタマイズ（「ソーダ」修飾子のフレーバーの選択など）が可能な場合は、modifier_groups フィールドに入力してネストされた修飾子を作成します。
  5. 組み立てと取り込み:
    • すべての MenuCategory、Item、ModifierGroup、Modifier オブジェクトを 1 つの Menu メッセージ内のリストに結合します。
    • 完全に組み立てられた Menu メッセージを入力として CreateMenu RPC を呼び出します。

メニューの更新の処理

Menu は変更不可です。CreateMenu RPC 呼び出しを使用して作成したメニューは変更できません。メニューの更新（アイテムの価格の変更、オプションの変更、在庫状況の調整など）をメニューに反映するには、CreateMenu を再度呼び出して新しいメニュー リソースを作成する必要があります。メニューの各バージョンは、一意の menu_id を持つ新しい Menu リソースとして取り込む必要があります。

メニューの新しいバージョンを取り込むプロセスは、メニューを初めて取り込むプロセスと同じで、同じサニタイズと検証の手順が実行されます。注文の処理中、エージェントの動作は常に、セッションの構成で参照される Store に関連付けられた最新の Menu を反映します。

メニューの自動サニタイズ

CreateMenu API は、一般的な問題を修正し、メニュー コンテンツが API 全体で一貫して表現されるように、いくつかのサニタイズ手順を自動的に実行します。クライアントのメニュー統合を簡素化するため、これらのサニタイズの後に検証が適用されます。

  • デフォルトの可用性: 明示的な Availability.Status のない Item と Modifier は STATUS_AVAILABLE に設定されます。
  • 参照されていないエンティティを削除: Item によって推移的に参照されていない Modifier と ModifierGroup は、順序付けできないため、メニューから削除されます。
  • 空の修飾子グループを削除: modifier_ids を含まない ModifierGroup は削除され、それらへの参照も削除されます。

サニタイズ後、API は厳格なルールセットに照らしてメニューを検証し、メニューが整形式であり、AI エージェントが確実に使用できることを確認します。検証に失敗すると、CreateMenu 呼び出しは問題を説明するエラーを返します。主な検証は次のとおりです。

  • 必須フィールド: id、display_name、availability.status などの必須フィールドがすべて存在することを確認します。
  • 一意の ID: すべての Item、Modifier、ModifierGroup には、メニュー内で一意の ID が必要です。
  • 一意の表示名:
    • すべての Item に一意の display_name が必要です。
    • 特定の ModifierGroup 内では、含まれるすべての Modifier に一意の display_name が必要です。
  • 参照整合性:
    • Item または Modifier で参照されるすべての modifier_group_ids はメニューに存在する必要があります。
    • ModifierGroup で参照されるすべての modifier_ids はメニューに存在する必要があります。
    • ModifierGroupReference で指定されたデフォルトの修飾子は、参照される ModifierGroup に存在する必要があります。
    • Modifier が item_id を使用して Item を参照する場合、その Item が存在する必要があります。
  • 修飾子グループの制約:
    • ModifierGroup は空欄にできません。
    • ModifierGroup 内の最小選択数または最大選択数が論理的に一貫しているかどうかがチェックされます。
    • Item レベルまたは Modifier レベルの modifier_constraints は、参照される ModifierGroup の選択数の制約に対して検証され、満たされることが保証されます。
  • ネストの深さ: ネストされた修飾子の深さには制限があります（例: Item -> ModifierGroup -> Modifier -> ModifierGroup -> Modifier...) を最大 5 レベルまで指定できます。
  • 時間帯の検証: Availability で時間帯が使用されている場合は、関連付けられた Store リソースで定義する必要があります。
  • 修飾子項目の参照: item_id を使用して Item を参照する Modifier には、display_name や availability などのフィールドを設定できません。これらのフィールドは、参照される Item から継承されるためです。

これらの検証ルールのいずれかに失敗すると、メニューを作成または更新できません。エラー メッセージには、違反の原因となっているエンティティの詳細が表示されます。

API リファレンス

すべてのメッセージとフィールドの詳細については、Food Ordering AI Agent API RPC リファレンスをご覧ください。

ベスト プラクティス

  • 一意の ID: Menu スコープ（Item、Modifier、ModifierGroup、MenuCategory）内のすべての id フィールドが一意であることを確認します。
  • わかりやすい名前: わかりやすく、お客様に優しい display_name を使用します。意味的に異なる商品には異なる display_name を指定して、エージェントが適切に曖昧さを解消できるようにします。
  • モデルの組み合わせを効果的に使用する: 組み合わせメニューで説明したように、Item としてモデルの組み合わせメニューを使用し、ModifierGroup でサイドメニュー、ドリンク、その他の選択肢を表します。これにより、エージェントはコンボの選択についてお客様に正しくご案内できます。
  • 統合属性を使用する: 必要な POS または内部システム ID を custom_integration_attributes に保存して、注文のシームレスな統合を容易にします。
  • Manage Availability（在庫状況を管理）: Availability ステータスを最新の状態に保ちます。
  • 徹底的にテスト: 取り込み後、さまざまな注文の組み合わせでエージェントのメニューの理解度をテストします。