事前準備
您必須先完成下列事項,才能使用「訂餐 AI 代理」API 擷取及管理菜單:
啟用訂餐 AI 代理 API:
gcloud services enable foodorderingaiagent.googleapis.com --project=PROJECT確認您具備必要的 IAM 權限。將下列 Identity and Access Management (IAM) 角色授予與 API 互動的使用者或服務帳戶:
- 訂餐 AI 代理管理員 (
roles/foodorderingaiagent.admin):這個角色具備完整存取權,可建立、讀取、更新及刪除所有訂餐 AI 代理資源,包括品牌、商店和菜單。
您可以使用 Google Cloud 控制台、
gcloud指令列工具或 IAM API 授予 IAM 角色。詳情請參閱「授予 IAM 角色」。如要使用 Google Cloud 控制台授予角色,請按照下列步驟操作:
- 前往 Google Cloud 控制台的「IAM」(身分與存取權管理) 頁面。
- 按一下「新增」。
- 輸入主體 (使用者或服務帳戶電子郵件地址)。
- 選取「訂餐 AI 代理 Admin」角色。
- 按一下「儲存」。
如果沒有適當權限,系統會拒絕建立或修改品牌、商店或菜單的 API 呼叫。
Food Ordering Agent Viewer角色僅授予唯讀存取權,不足以執行本指南所述的工作。- 訂餐 AI 代理管理員 (
總覽
Food Ordering AI Agent Menu API 具有彈性,可容納各種菜單結構,從獨立品項的簡短清單,到含有巢狀修飾符和套餐的複雜菜單,都能輕鬆處理。此 API 是圍繞著以下幾個關鍵概念建構而成:
- 菜單:所有可訂購實體的頂層容器。
- Item:代表菜單中可訂購的頂層產品,例如餐點、主菜或任何可單獨訂購的產品。
Item可參照ModifierGroup。 - ModifierGroup:可套用至
Item或其他Modifier的Modifier選項集合 (允許巢狀結構)。例如「選擇配菜」、「添加配料」或「選擇飲料口味」。 - 修改項目:
ModifierGroup中的個別選項,例如「薯條」、「額外起司」或「可樂」。修飾符可以調整價格,也可以有自己的巢狀ModifierGroup。 - MenuCategory:用於將
Item整理成不同部分,以便顯示及理解 (例如「開胃菜」、「漢堡」、「飲料」)。
重要概念和結構
本節將詳細說明訂餐 AI 代理選單 API 架構的核心元件,以及這些元件的結構。瞭解這些概念,才能正確建立菜單資料模型。
項目
菜單上的每個不同品項都應定義為 Item。重要欄位包括:
id:選單中的專屬 ID。display_name::客戶看到的名稱。base_price:商品的底價。modifier_groups:可套用至這項商品的ModifierGroup參照。category_ids:這個項目所屬MenuCategoryID 的參照。availability:指定項目的供應時間 (例如依狀態或時段)。如未指定,預設為STATUS_AVAILABLE。
修飾符和 ModifierGroup
你可以使用修飾符自訂項目。
ModifierGroup定義一組選項,包括選取數量下限或上限等限制。至少須包含一個Modifier。Modifier代表實際選項。它們可以有price_adjustment,並可遞迴參照其他ModifierGroup進行巢狀自訂 (例如,「套餐」Item可能有「選擇飲料」ModifierGroup,而該群組中的「汽水」Modifier可能有「選擇口味」ModifierGroup)。
範例 1:配料
「培根起司漢堡」Item 可能會參照「配料」ModifierGroup。這個 ModifierGroup 會包含「加起司」、「不要洋蔥」等 Modifier。
範例 2:套餐
部分菜單結構複雜,包含多個巢狀選項,例如套餐或「組合餐」。套餐可以模擬為 Item,並以多個 ModifierGroup 代表套餐的組成部分。舉例來說,「漢堡套餐」Item 包含固定主菜,以及多種配菜和飲料選項,可模擬如下:
- 配菜的
ModifierGroup(例如「配菜選項」)。- 每個配菜選項都會模擬為
Modifier(例如「薯條」、「沙拉」)。- 每個飲料選項都可能參照巢狀
ModifierGroup(例如「冰塊選項」、「飲料大小」),而這些選項又會參照Modifier(例如「去冰」、「大杯飲料」)。
- 每個飲料選項都可能參照巢狀
- 每個配菜選項都會模擬為
- 飲料的
ModifierGroup(例如「飲料」)。- 每個飲料選項都會模擬為
Modifier。- 每個飲料選項都可能參照巢狀
ModifierGroup(例如「冰塊選項」、「飲料大小」),而這些選項又會參照Modifier(例如「去冰」、「大杯飲料」)。
- 每個飲料選項都可能參照巢狀
- 每個飲料選項都會模擬為
- 主菜配料的
ModifierGroup。(例如「起司加量」、「培根」)。
可用性
Item 和 Modifier 的 Availability 訊息可讓您指定:
status:STATUS_AVAILABLE、STATUS_OUT_OF_STOCK等等。daypart_availability:如果商品僅在特定時段供應 (例如「早餐菜單」),則連結至特定時段 ID。
整合屬性
Item、Modifier 和 ModifierGroup 訊息包含 integration_attributes 欄位。這個欄位 (ItemIntegrationAttributes、ModifierIntegrationAttributes 等) 包含名為 custom_integration_attributes 的 google.protobuf.Struct。您可以使用這個方法儲存任意鍵/值資料,例如:
- 銷售點 (POS) 系統的 ID。
- SKU 或其他內部代碼。
- 下游訂單處理或 POS 整合所需的任何其他中繼資料。
AI 代理會不透明地傳遞這項資料。
標籤
您可以使用 Menu 資源上的 labels 欄位,將中繼資料附加至選單,以便整合及偵錯。
標籤是便利功能,不會影響 AI 代理的行為。
建立選單
系統會使用 MenuService 中的 CreateMenu RPC 呼叫來擷取選單。
步驟
- 轉換資料:將現有菜單資料 (來自 POS、API 或其他來源) 轉換為
google.cloud.foodorderingaiagent.v1beta.Menu訊息定義的結構。這包括將品項、修飾符、類別和價格對應至相應的 API 訊息類型。 - 建構
CreateMenuRequest:- 設定
parent欄位 (例如projects/PROJECT/locations/LOCATION)。 - 使用轉換後的
Menu物件填入menu欄位。 - 視需要提供
menu_id。
- 設定
- 呼叫 API:將
CreateMenuRequest傳送至MenuService.CreateMenu端點。API 會先清理菜單,然後進行驗證,並傳回最終的Menu物件。 - 處理菜單更新:每次更新菜單來源資料時 (例如推出新產品或產品缺貨),請按照處理菜單更新一節的說明,建立新的
Menu來反映更新後的來源資料。
資料轉換指南
轉換菜單資料的具體邏輯,取決於來源系統的格式和結構 (例如 POS API、資料庫結構定義)。一般做法如下:
- 匯出資料:完整匯出菜單資料,包括所有品項、選項、價格和關係。
- 對應實體:
- 找出訂餐 AI 代理 API 架構中,與來源資料各元素對應的實體。舉例來說,POS「選單項目」可能會對應至
Item物件。「訂購選項」或「加購項目」會對應至Modifier和ModifierGroup。 - 使用 ID 建立關係。舉例來說,您可以使用
modifier_groups參照欄位,將Item連結至適用的ModifierGroup。
- 找出訂餐 AI 代理 API 架構中,與來源資料各元素對應的實體。舉例來說,POS「選單項目」可能會對應至
- 處理巢狀結構:如果菜單有巢狀修飾符 (例如選擇套餐汽水的口味),請讓
Modifier參照其他ModifierGroup,建立這類結構的模型。 - 填入屬性:根據來源資料填寫
display_name、base_price、price_adjustment和availability等欄位。 - 加入 POS ID:請務必在
custom_integration_attributes欄位中,儲存每個項目、修飾符和群組的內部 POS 或系統 ID。這樣一來,您就能將代理產生的Order轉譯回應用程式的最終訂單或進行中購物車。 - 編寫指令碼:您可能需要編寫指令碼 (例如使用 Python、Node.js、Go),從來源擷取資料、執行轉換,並呼叫
CreateMenu方法。這個指令碼會使用 Google Cloud 用戶端程式庫進行驗證和 API 互動。
概念轉換工作流程:
這個工作流程概述了將菜單資料從來源系統轉換為訂餐 AI 代理 API 格式的程序:
- 擷取及對應類別:
- 找出來源資料中的類別或部分 (例如「前菜」、「主菜」)。
- 將每個項目轉換為具有不重複
id和display_name的MenuCategory物件。
- 擷取及對應項目:
- 找出來源資料中的可販售商品。
- 將每個項目轉換為
Item物件,並填入id、display_name、base_price和availability。 - 使用
category_ids欄位,將每個Item對應至其類別。 - 將來源系統 ID (例如 PLU 或 SKU) 儲存在
item.integration_attributes.custom_integration_attributes中。
- 擷取及對應修飾符:
- 找出來源資料中的商品自訂選項、選項或加購內容。
- 將相關選項 (例如「配菜選項」、「飲料選擇」、「額外配料」) 分組到
ModifierGroup物件中。為每個ModifierGroup定義選取規則的上下限。 - 將每個選項 (例如「薯條」、「可樂」、「額外起司」) 轉換為適當
ModifierGroup中的Modifier物件。視情況填入price_adjustment。 - 將來源系統 ID 儲存在
modifier_group.integration_attributes.custom_integration_attributes和modifier.integration_attributes.custom_integration_attributes。
- 建立關係:
- 針對每個
Item,請在modifier_groups欄位中填入適用的ModifierGroupid參照。 - 如果
Modifier允許進一步自訂 (例如為「汽水」修飾符選擇口味),請填入modifier_groups欄位,建立巢狀修飾符。
- 針對每個
- 彙整及擷取:
- 將所有
MenuCategory、Item、ModifierGroup和Modifier物件合併到單一Menu訊息中的清單。 - 呼叫
CreateMenuRPC,並以完整組合的Menu訊息做為輸入內容。
- 將所有
處理菜單更新
Menu 不可變動。使用 CreateMenu RPC 呼叫建立選單後,即無法修改。如要將選單更新內容 (例如變更商品價格、修改選項或調整供應情形) 傳播至選單,您必須再次呼叫 CreateMenu,建立新的選單資源。每個版本的菜單都應擷取為新的 Menu 資源,並具有不重複的 menu_id。
擷取新版菜單的程序與首次擷取菜單相同,且會經過相同的清理和驗證步驟。處理訂單時,代理的行為一律會反映最近建立的 Menu,並與工作階段設定中參照的 Store 相關聯。
自動清理菜單
CreateMenu API 會自動執行多個清理步驟,修正常見問題,並確保 API 中的菜單內容呈現方式一致。系統會在清理後套用驗證,簡化用戶端的菜單整合程序:
- 預設適用情況:如果
Item和Modifier沒有明確的Availability.Status,則會設為STATUS_AVAILABLE。 - 捨棄未參照的實體:如果
Modifier和ModifierGroup未由任何Item遞移參照,則會從菜單中移除,因為這些項目無法訂購。 - 捨棄空白修飾符群組:不含
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內選項數量的下限或上限,確保邏輯一致。 - 系統會根據參照
ModifierGroup的選取數量限制,驗證Item或Modifier層級modifier_constraints,確保這些限制可以滿足。
- 巢狀深度:巢狀修飾符的深度有限制 (例如
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欄位都是專屬 ID。 - 明確的名稱:使用清楚、容易理解的
display_name。為語意不同的產品提供不同的display_name,引導代理適當釐清。 - 有效建立套餐模型:將套餐建立為
Item,並使用ModifierGroup代表配菜、飲料和其他選項,詳情請參閱套餐。這樣一來,代理就能正確引導顧客選擇套餐。 - 使用整合屬性:將任何必要的 POS 或內部系統 ID 儲存在
custom_integration_attributes中,以便順利整合訂單。 - 管理供應情形:隨時更新
Availability狀態。 - 僅納入可訂購的項目:請勿加入顧客無法在管道中訂購的項目,例如僅限外送的項目、重複項目,以及非食品或飲料產品的項目。大型選單可能會超出代理模型接受的輸入量。詳情請參閱「代理重複傳送重試訊息,然後結束工作階段」。
- 徹底測試:擷取完成後,請測試代理對菜單的理解程度,並嘗試各種點餐組合。