使用訂餐 AI 代理 API 整合菜單資料

本指南說明如何將餐廳菜單資料結構化、轉換及擷取至 Food Ordering AI Agent Menu API。這樣一來，AI 代理就能瞭解你的菜單，並準確接受顧客訂單。

事前準備

如要使用 Food Ordering AI Agent API 擷取及管理菜單，請先完成下列步驟：

  1. 啟用訂餐 AI 代理 API：

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

  2. 確認您具備必要的 IAM 權限。將下列 Identity and Access Management (IAM) 角色授予與 API 互動的使用者或服務帳戶：

    • 訂餐代理管理員 (roles/foodorderingaiagent.admin)：這個角色具備完整存取權，可建立、讀取、更新及刪除所有訂餐 AI 代理資源，包括品牌、商店和菜單。

    您可以使用 Google Cloud 控制台、gcloud 指令列工具或 IAM API 授予 IAM 角色。詳情請參閱「授予 IAM 角色」。

    如要使用 Google Cloud 控制台授予角色：

    1. 前往 Google Cloud 控制台的「IAM」(身分與存取權管理) 頁面。
    2. 按一下「新增」。
    3. 輸入主體 (使用者或服務帳戶電子郵件地址)。
    4. 選取「訂餐 AI 代理管理員」角色。
    5. 按一下 [儲存]。

    如果沒有適當的權限，建立或修改品牌、商店或菜單的 API 呼叫將會遭到拒絕。Food Ordering Agent Viewer 角色只授予唯讀存取權，因此不足以執行本指南所述工作。

總覽

Food Ordering AI Agent Menu API 的設計相當彈性，可因應各種菜單結構，從獨立項目的簡短清單，到含有巢狀修飾符和套餐的複雜菜單皆適用。此 API 是圍繞著以下幾個重要概念建構而成：

  • 菜單：所有可訂購實體的頂層容器。
  • 項目：代表菜單中可訂購的頂層產品，例如餐點、主菜或任何可單獨訂購的產品。Item 可以參照 ModifierGroup。
  • ModifierGroup：可套用至 Item 或其他 Modifier 的 Modifier 選項集合 (允許巢狀結構)。例如「選擇配菜」、「新增配料」或「選擇飲料口味」。
  • 加購品：ModifierGroup 中的個別選項，例如「薯條」、「起司加量」或「可樂」。修飾符可以調整價格，也可以有自己的巢狀 ModifierGroup。
  • MenuCategory：用於將 Item 分類顯示，方便使用者瀏覽 (例如「Appetizers」、「Burgers」、「Drinks」)。

重要概念和結構

本節將詳細說明 Food Ordering AI Agent Menu API 結構定義的核心元件，以及這些元件的結構。瞭解這些概念是正確建立菜單資料模型的關鍵。

項目

菜單上的每個不同項目都應定義為 Item。主要欄位包括：

  • id：選單中的專屬 ID。
  • display_name：向消費者顯示的名稱。
  • base_price：商品的底價。
  • modifier_groups：可套用至這個項目的 ModifierGroup 參照。
  • category_ids：這個項目所屬的 MenuCategory ID 參照。
  • availability：指定項目何時可供使用 (例如依狀態或時段)。如未指定，則預設值為 STATUS_AVAILABLE。

修飾符和 ModifierGroups

修飾符可讓您自訂項目。

  • ModifierGroup 定義一組選項，包括選取下限或上限等限制。至少要有一個 Modifier。
  • Modifier 代表實際選項。可以有 price_adjustment，並以遞迴方式參照其他 ModifierGroup，進行巢狀自訂 (例如「套餐」Item 可能有「選擇飲料」ModifierGroup，而該群組中的「汽水」Modifier 可能有「選擇口味」ModifierGroup)。
服務專員會與顧客合作，滿足限制條件 (例如「請問要搭配哪兩杯飲料？」)。

範例 1：配料

「培根起司漢堡」Item可能會參照「配料」ModifierGroup。這個 ModifierGroup 會包含「加起司」、「不要洋蔥」等 Modifier。

範例 2：套餐

有些菜單結構複雜，包含多個巢狀選項，例如套餐或「組合」。組合可模擬為 Item，其中包含多個代表組合元件的 ModifierGroup。舉例來說，「漢堡套餐」Item包含固定主菜，以及多種配菜和飲料選項，可使用下列項目建立模型：

  • 側邊的 ModifierGroup (例如 「配菜」)。
    • 每個側邊選項都會模擬為 Modifier (例如 「薯條」、「沙拉」)。
      • 每個飲料選項都可以參照巢狀 ModifierGroup (例如 「冰塊選項」、「飲料大小」)， 進而參照 Modifier (例如「不加冰塊」、「大杯飲料」)。
  • 飲料的 ModifierGroup (例如 「Drinks」)。
    • 每個飲料選項都會以 Modifier 建模。
      • 每個飲料選項都可以參照巢狀 ModifierGroup (例如 「冰塊選項」、「飲料大小」)，Modifier (例如「不加冰塊」、「大杯飲料」)。
  • 主菜的配料。ModifierGroup(例如：「Extra Cheese」、「Bacon」)。

可用性

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。您可以使用這項功能儲存任意鍵/值資料，例如：

  • 銷售點 (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 等欄位。
  • 加入銷售點 ID：請務必在 custom_integration_attributes 欄位中，儲存每個項目、修飾符和群組的內部銷售點或系統 ID。這項功能可將代理產生的 Order 翻譯回應用程式的最終訂單或進行中購物車表示法。
  • 編寫指令碼：您可能需要編寫指令碼 (例如使用 Python、Node.js、Go)，從來源擷取資料、執行轉換，然後呼叫 CreateMenu 方法。這個指令碼會使用 Google Cloud 用戶端程式庫進行驗證和 API 互動。

概念轉換工作流程：

這個工作流程說明如何將來源系統的菜單資料轉換為 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 欄位中填入適用於該 Item 的 ModifierGroup id 參照。
    • 如果 Modifier 允許進一步自訂 (例如選擇「汽水」輔助鍵的口味)，請填入 modifier_groups 欄位，建立巢狀輔助鍵。
  5. 組裝和擷取：
    • 將所有 MenuCategory、Item、ModifierGroup 和 Modifier 物件合併到單一 Menu 訊息中的清單。
    • 以完整組裝的 Menu 訊息做為輸入內容，呼叫 CreateMenu RPC。

處理菜單更新

「選單」為不可變動。使用 CreateMenu RPC 呼叫建立選單後，就無法修改。如要將菜單更新 (例如變更品項價格、修改選項或調整供應情形) 傳播至菜單，請再次呼叫 CreateMenu，建立新的菜單資源。菜單的每個版本都應以新的 Menu 資源形式匯入，並使用專屬的 menu_id。

如要匯入新版菜單，程序與首次匯入菜單相同，且同樣會經過清除和驗證步驟。處理訂單時，服務專員的行為一律會反映最近建立的 Menu，該 Menu 與工作階段設定中參照的 Store 相關聯。

自動清除選單

CreateMenu API 會自動執行多個清除步驟，修正常見問題，並確保整個 API 的菜單內容一致。這些清除作業完成後，系統會套用驗證，簡化用戶端的選單整合作業：

  • 預設適用情況：未明確設定 Availability.Status 的 Item 和 Modifier 會設為 STATUS_AVAILABLE。
  • 捨棄未參照的實體：系統會從選單中移除未由任何 Item 遞移參照的 Modifier 和 ModifierGroup，因為這些實體無法排序。
  • 捨棄空白的修飾符群組：系統會捨棄不含 modifier_ids 的 ModifierGroup，並移除對這些 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 不得留空。
    • 系統會檢查 ModifierGroups 內的選取項目數下限或上限是否符合邏輯。
    • Item 或 Modifier 層級 modifier_constraints 會根據參照 ModifierGroup 的選取計數限制進行驗證，確保這些限制可滿足。
  • 巢狀結構深度：巢狀修飾符的深度有限 (例如 Item -> ModifierGroup -> Modifier -> ModifierGroup -> Modifier...)，最多 5 個層級。
  • 時段驗證：如果 Availability 中使用時段，則必須在相關聯的 Store 資源中定義時段。
  • 修飾符項目參照：參照 Item 的 Modifier (使用 item_id 時) 不得設定 display_name 或 availability 等欄位，因為這些欄位是從參照的 Item 繼承而來。

如果違反任何驗證規則，系統將無法建立或更新菜單。錯誤訊息會詳細說明哪些實體導致違規。

API 參考資料

如要查看所有訊息和欄位的完整詳細資料，請參閱 Food Ordering AI Agent API RPC 參考資料。

最佳做法

  • 唯一 ID：請確保 Menu 範圍內的所有 id 欄位 (適用於 Item、Modifier、ModifierGroup、MenuCategory) 都是唯一的。
  • 明確的名稱：使用清楚易懂的 display_name，為語意不同的產品提供不同的 display_name，引導代理程式適當消除歧義。
  • 有效組合模型：將模型組合餐點視為 Item，其中 ModifierGroup 代表配菜、飲料和其他選擇，如組合餐點所述。確保服務專員能正確引導顧客選擇組合。
  • 使用整合屬性：在 custom_integration_attributes 中儲存任何必要的 POS 或內部系統 ID，方便順利整合訂單。
  • 管理供應情形：隨時更新 Availability 狀態。
  • 徹底測試：匯入後，請使用各種訂單組合測試服務專員對菜單的理解程度。