總覽

Google 合作夥伴可以透過預訂端對端整合服務，向 Google 提供結構化菜單資料，用於餐廳 Google 商家檔案的「菜單」部分，以及 Google 消費者平台上的其他進入點。

系統會使用通用動態饋給擷取菜單資料。事前準備：

  1. 請確認您已完成帳戶設定
  2. 瞭解一般動態饋給上傳程序
  3. 瞭解如何設定帳戶，以便上傳一般動態饋給

建立及上傳菜單動態饋給

建立及上傳菜單動態饋給時，請遵守下列規範和慣例：
  • 如要提供餐廳詳細資料，請按照商家動態饋給所述的資料規格操作。 如需 JSON 檔案範例，請參閱範例 JSON。 上傳的資料檔案名稱不得重複。建議在檔案名稱中加入時間戳記，例如 menu1_1633621547.json
  • 在選單動態饋給的檔案集描述元中，將 name 欄位設為 google.food_menu。 如要查看描述元檔案內容範例，請參閱「描述元檔案 JSON 範例」。 描述元檔案的名稱在不同上傳作業之間不得重複。建議在檔案名稱中加入時間戳記，例如 descriptor_1633621547.filesetdesc.json。描述元檔案必須上傳至一般安全檔案傳輸通訊協定伺服器，做為菜單動態饋給的一部分。
  • 動態饋給必須每天上傳至一般安全檔案傳輸通訊協定伺服器，以進行完整更新。
  • 如「使用通用動態饋給 SFTP」一文所述，動態饋給最多只能有 1000 個分片 (檔案)

你可以在合作夥伴入口網站的「Ingestion」>「History」部分，查看動態饋給擷取狀態。如要查看動態饋給 SFTP 伺服器資訊，請前往合作夥伴入口網站的「設定」>「動態饋給」部分。

選取動態饋給安全檔案傳輸通訊協定伺服器

圖 1： 一般 SFTP 伺服器資訊

你可以在合作夥伴入口網站的「擷取」>「記錄」部分，查看動態饋給擷取狀態。如要查看動態饋給 SFTP 伺服器資訊，請前往合作夥伴入口網站的「設定」>「動態饋給」部分。

使用菜單項目選項

您可以使用 MenuItemOption proto 指定選單項目選項。

如果合作夥伴的單一菜單項目有多組必要選項 (例如拿鐵有大小和牛奶選項)，則必須決定如何在 Google 中顯示這些選項。Google 建議採取下列做法：

  • 菜單動態饋給應與合作夥伴的訂餐網站相符 (如果沒有該地點的訂餐網站，則應與餐廳的內用菜單相符)。如果訂購網站上顯示個別商品的價格，則應使用 MenuItem。 如果商品顯示底價和多個選項，則應使用 MenuItemOption。
  • 請避免加入長長的選項清單，例如：
    • 雞肉捲餅
    • 起司雞肉捲餅
    • 雞肉捲餅佐莎莎醬
    • 雞肉捲餅佐莎莎醬和起司
    • 雞肉捲餅佐酪梨醬
    • 雞肉捲餅，佐以酪梨醬和莎莎醬
  • 只有在菜色需要選取其中一個選項時，系統才會支援菜單項目選項。舉例來說，訂購披薩時，必須選擇尺寸。系統不支援外掛程式的選單項目選項 (例如「加酪梨」的選項)，因此請勿將這類選項加入動態饋給。

菜單選項的價格應為選取該選項的商品全價。 菜單項目或選項應設定價格，但兩者不得同時設定。

提供多種菜單的餐廳

單一餐廳 (實體) 只能有一個菜單。如果餐廳有多份菜單 (例如午餐和晚餐菜單)，你可以使用 MenuSections 將所有菜單合併為一份 (例如一份菜單，其中包含午餐和晚餐專區)。產生的選單結構如下：

  • 選單
    • 午餐專區
      • 湯品
        • 湯 1
        • 湯 2
      • 三明治
        • 三明治 1
        • 三明治 2
    • 晚餐專區
      • 啟動條件
        • 啟動條件 1
        • Starter 2
      • 主菜
        • 主菜 1
        • 主菜 2

在餐廳之間共用菜單

只要將所有餐廳納入菜單的merchant_ids清單，即可在多間餐廳共用同一份菜單。請注意，這份清單接受使用實體動態饋給的合作夥伴實體 ID。

最佳做法

開發菜單動態饋給時，請遵循下列最佳做法。

  • 只能將一個菜單與餐廳建立關聯。
  • 最多可有 3,000 個不重複的 MenuItem 物件 (涵蓋所有區段和巢狀子區段)。
  • 單一 Menu 內，每種實體類型 (MenuSection、MenuItem、MenuItemOption) 最多可有 100,000 個不重複的實體。
  • 完全組裝的 Menu (所有區段、項目和選項在重複資料刪除後合併) 不得超過 3.8 MB。
  • 所有 ID 欄位 (menu_id、merchant_ids、menu_section_ids、menu_item_ids、menu_item_option_ids、addon_menu_section_ids) 的字元數不得超過 580 個。
  • 在 TextField 中，將偏好語言設為第一種語言。如果您傳送多個 LocalizedText 物件，系統會向使用者顯示文字清單中的第一個物件。
  • 所有菜單品項都必須新增至菜單專區。 請勿直接將選單項目新增至選單物件。
  • 使用 UTF-8 編碼提供內容。不需要逸出非 ASCII 字元。
  • 如果要在多個區域推出應用程式，請務必在「單位」和「奈米」欄位中使用正確的貨幣代碼和幣值，並特別注意「奈米」欄位，因為該欄位的值是「單位」欄位的 10^-9。使用目錄檢視器中的菜單檢視器，確認價格設定正確無誤。
  • 為使用者提供豐富、全面且最新的菜單，是提供實用且吸引人使用者體驗的關鍵。價格、說明、相片和飲食資訊都是影響決策的重要因素，因此建議合作夥伴盡可能提供這類資料，以提供最佳的使用者和商家體驗。
  • 如要顯示不含價格，請在 Offer proto 中加入空白的 Price proto。

推出菜單動態饋給後，系統就會在探索介面中顯示菜單動態饋給資料，並可能在餐廳地點資訊頁的「菜單」分頁中顯示。Google 搜尋 (行動版和電腦版) 支援菜單分頁，這項功能也將擴展至其他平台，包括 Google 地圖。實際呈現的體驗可能會因介面而異。

菜單範例：顯示附有說明的菜單品項

圖 3： 菜單動態消息內容在行動裝置商家檔案上的顯示方式範例

如要確保菜單結構正確無誤，請使用目錄檢視器中的菜單視覺化工具預覽菜單。

餐廳菜單的來源有很多，包括餐廳透過 Google 商家檔案提供的菜單、美食訂餐和訂位合作夥伴提供的菜單、使用者拍攝的菜單相片等。如果有多個來源為同一間餐廳提供菜單，商家可以在 Google 商家檔案菜單編輯器中選擇偏好的供應商。

結構定義

如要查看完整菜單結構定義，請按這裡。

FoodMenuFeed

欄位名稱類型規定說明
data物件陣列
(MenuComponent)

欄位名稱類型規定說明
oneOf
(type)

這個 oneOf 中的欄位只能設定一個。

美食商家提供的頂層目錄。菜單 包含商家 ID 清單，以及適用於這些商家的菜單。 選單可用於代表提供選單的單一商家，或提供選單的多個商家 (通常是連鎖餐廳)。

欄位名稱類型規定說明
menu_id字串

必填

合作夥伴提供的不透明字串，可明確識別合作夥伴動態饋給中的菜單。必填。
merchant_ids字串陣列

必填

菜單適用的商家。 注意：這個欄位會重複，因此連鎖餐廳可以在多個地點共用相同菜單，每個地點都是個別商家。必填。
display_name物件
(TextField)

使用者瀏覽選單時，可識別選單的名稱。 選用項目。
language字串

與選單中文字標籤相關聯的預設語言代碼。預期為 BCP-47 語言代碼，例如「en-US」或「sr-Latn」。 詳情請參閱 http://www.unicode.org/reports/tr35/#Unicode_locale_identifier。選用項目。

TextField

包含一或多個本地化值的文字酬載。

欄位名稱類型規定說明
text物件陣列
(LocalizedText)

必填

每個語言代碼的文字值。 如果只支援一種語言代碼，則不需要在每個文字中設定 language_code，系統會根據選單的預設語言推斷語言。 如果不同語言代碼有多個文字，則必須為每個文字設定 language_code。清單中的第一個文字會視為偏好的表示方式。必填。

LocalizedText

特定語言的文字本地化變體。

欄位名稱類型規定說明
text字串

以對應於下方 [language_code][google.type.LocalizedText.language_code] 的語言顯示本地化字串。
language_code字串

文字的 BCP-47 語言代碼，例如「en-US」或「sr-Latn」。 詳情請參閱 http://www.unicode.org/reports/tr35/#Unicode_locale_identifier。

菜單專區是指菜單上的一組項目。通常會為菜單上每個邏輯分組的項目建立個別的 MenuSection。例如餐點類型 (開胃菜、主菜、甜點) 和食物類別 (漢堡、飲料) 是常見的區塊。

欄位名稱類型規定說明
menu_section_id字串

必填

合作夥伴提供的不透明字串，可明確識別合作夥伴動態饋給中的 MenuSection。 必填。
display_name物件
(TextField)

必填

使用者瀏覽菜單時，可識別 MenuSection 的名稱。必填。
description物件
(TextField)

選單專區的說明。 選用項目。
images物件陣列
(Image)

菜單專區的圖片。 選用項目。

圖片

代表與選單實體相關聯的圖片。

欄位名稱類型規定說明
uri字串

必填

含有圖片原始像素的網址。 必填。

代表餐飲場所提供的單一食品或飲料項目。

欄位名稱類型規定說明
menu_item_id字串

必填

合作夥伴提供的不透明字串，可明確識別合作夥伴動態饋給中的 MenuItem。 必填。
display_name物件
(TextField)

必填

使用者瀏覽選單時，可識別 MenuItem 的名稱。 必填。
description物件
(TextField)

選單項目的說明。 選用項目。
images物件陣列
(Image)

菜單項目的圖片。 選用項目。
oneOf
(pricing)

必填

這個 oneOf 中的欄位只能設定一個。
item_attributes物件
(MenuItemAttributes)

這個選單項目的屬性。 選用項目。

OfferSet

容器，用於存放選單項目 / 選項可用的優惠清單。 在特定時間只能適用/有效一項優惠。 舉例來說，飲料可以有 2 項優惠，一項適用於上午，另一項適用於傍晚的歡樂時光。

欄位名稱類型規定說明
offers物件陣列
(Offer)

必填

可能提供的優惠清單。 必填。

優惠

代表 MenuItems 和 MenuItemOptions 的價格和供應情形資訊。

欄位名稱類型規定說明
price物件
(Money)

以下案例無效，會導致菜單項目遭到捨棄： 價格沒有貨幣代碼，但有單位或奈米單位，或兩者都有： price {units: 100, nanos: 1000000} price {units: 100} price {nanos: 1000000} 價格的貨幣代碼無效，但有單位或奈米單位，或兩者都有： price {currency_code: 'gXYZ', units: 100, nanos: 1000000} price {currency_code: 'gXYZ', units: 100} price {currency_code: 'gXYZ', nanos: 1000000} 價格有貨幣代碼，但單位或奈米單位無效 price {currency_code: 'USD', units: 100, nanos: -100} price {currency_code: 'USD', units: -100, nanos: 100}

金額

代表金額與其貨幣類型。

欄位名稱類型規定說明
currency_code字串

ISO 4217 中定義的三個英文字母貨幣代碼。
units數字

金額的整數單位。 舉例來說，如果 currencyCode 為 "USD"，則 1 個單位為 1 美元。
nanos數字

金額的奈米 (10^-9) 單位數量。 這個值必須介於 -999,999,999 和 +999,999,999 (含) 之間。 如果 units 為正值，nanos 必須為正值或零。 如果 units 為零，則 nanos 可為正值、零或負值。 如果 units 為負值，nanos 就必須為負值或零。 例如，$-1.75 美元的表式方式為 units=-1 和 nanos=-750,000,000。

容器，用於指定項目可用的選項清單。

欄位名稱類型規定說明
menu_item_option_ids字串陣列

必填

適用於此菜單項目的菜單項目選項 ID。 必填。

說明特定菜單項目或選項的屬性。

欄位名稱類型規定說明
number_of_servings數字

特定菜單項目可提供的份量數。 選用項目。
nutrition_information物件
(NutritionInformation)

說明商品的完整營養資訊，例如熱量、脂肪含量。選用項目。
suitable_diets列舉陣列
(DietaryRestriction)

這項菜單項目符合的飲食限制。 選用項目。
additive物件陣列
(Additive)

這個選單項目的加購品。 選用項目。
allergen物件陣列
(Allergen)

這個菜單項目的過敏原。 選用項目。
packaging_deposit_info物件
(DepositInfo)

這個菜單項目的包裝和回收資訊。 選用項目。

NutritionInformation

描述 MenuItem 或加購產品的所有營養成分測量結果。

欄位名稱類型規定說明
energy物件
(NutritionValue)

一份食物的營養能量。可定義為卡路里或千焦耳。選用項目。
sodium_content物件
(NutritionValue)

鈉含量，以公克或毫克為單位。 選用項目。
serving_size數字

營養價值適用的份量數。 選用項目。
description物件
(TextField)

以任意文字輸入營養資訊。例如「含有防腐劑」。 選用項目。

NutritionValue

說明一份食物的單一營養測量值。

欄位名稱類型規定說明
oneOf
(value)

這個 oneOf 中的欄位只能設定一個。
unitenum
(NutritionValueUnit)

必填

合作夥伴指定的金額相關單位。我們會驗證動態饋給，確保每種營養價值的單位符合該類型的值。舉例來說，在 NutritionalInformation 的能量屬性中，只會顯示 ENERGY_CALORIES 和 ENERGY_KILOJOULES。必填。

範圍

說明營養價值的封閉範圍。例如「100-150 大卡」

欄位名稱類型規定說明
min數字

必填

最低營養價值。 必填。
max數字

必填

營養價值上限。 必填。

加法

MenuItem 上向使用者顯示的加號。添加物可保存或提升食品品質。

欄位名稱類型規定說明
name物件
(TextField)

必填

添加物的說明文字，例如「防腐劑」。 必填。
containment_level_codeenum
(ContainmentLevelCode)

MenuItem 是否含有、可能含有或不含這項添加物。 預設值為 contains。 選用項目。

過敏原

MenuItem 上向使用者顯示的過敏原。過敏原是指食物中會引起過敏反應的物質。

欄位名稱類型規定說明
allergen_type_codeenum
(AllergenTypeCode)

必填

過敏原類型。 必填。
containment_level_codeenum
(ContainmentLevelCode)

MenuItem 是否含有、可能含有或不含此過敏原。 預設值為 contains。 選用項目。

DepositInfo

合作夥伴提供的押金資訊，用於指示使用者如何退還食品容器或瓶子，以及押金金額。

欄位名稱類型規定說明
deposit_codeenum
(DepositCode)

要採用的押金策略，例如「可重複使用」。 選用項目。
deposit_value物件
(Money)

正確存放商品可獲得的退款金額。 選用項目。

說明使用者選取菜餚 / 套餐時必須做出的選擇。使用者必須選取選項，否則訂單會視為無效 (例如使用者必須選擇披薩的小、中或大尺寸)。

欄位名稱類型規定說明
menu_item_option_id字串

必填

合作夥伴提供的不透明字串，可專門識別合作夥伴動態饋給中的 MenuItemOption。必填。
value物件
(MenuItemOptionProperty)

必填

選項屬性和值，例如尺寸：小。 必填。

說明選單項目選項的屬性及其值。

欄位名稱類型規定說明
property_typeenum
(PropertyType)

必填

這個選項屬性的類型。 必填。
oneOf
(value)

必填

這個 oneOf 中的欄位只能設定一個。

NutritionValueUnit

名稱說明
NUTRITION_VALUE_UNIT_UNSPECIFIED請勿使用。營養價值單位未明確設定。
ENERGY_CALORIES用於表示菜單項目能量的單位。
ENERGY_KILOJOULES
WEIGHT_MILLIGRAMS用於表示菜單項目中物質重量的單位。
WEIGHT_GRAMS

DietaryRestriction

表示食物製備期間遵守的飲食限制或指南。

名稱說明
DIET_UNSPECIFIED請勿使用。未明確指定飲食限制。
DIET_DIABETIC
DIET_GLUTEN_FREE
DIET_HALAL
DIET_HINDU
DIET_KOSHER
DIET_LOW_CALORIE
DIET_LOW_FAT
DIET_LOW_LACTOSE
DIET_LOW_SALT
DIET_VEGAN
DIET_VEGETARIAN

ContainmentLevelCode

指出食品含有特定屬性的程度，例如過敏原或添加物。

名稱說明
CONTAINMENT_LEVEL_CODE_UNSPECIFIED請勿使用。未明確指定包含層級代碼。
CONTAINMENT_LEVEL_CODE_CONTAINS
CONTAINMENT_LEVEL_CODE_DOES_NOT_CONTAIN
CONTAINMENT_LEVEL_CODE_MAY_CONTAIN

AllergenTypeCode

從 GS1 衍生而來的過敏原類型：http://gs1.org/voc/AllergenTypeCode

名稱說明
ALLERGEN_TYPE_CODE_UNSPECIFIED請勿使用。未明確指定過敏原類型代碼。
ALLERGEN_TYPE_CODE_ALMONDS
ALLERGEN_TYPE_CODE_ALPHA_ISOMETHYL_IONONE
ALLERGEN_TYPE_CODE_ALCOHOL
ALLERGEN_TYPE_CODE_AMYL_CINNAMAL
ALLERGEN_TYPE_CODE_ANISE_ALCOHOL
ALLERGEN_TYPE_CODE_BARLEY
ALLERGEN_TYPE_CODE_BENZYL_ALCOHOL
ALLERGEN_TYPE_CODE_BENZYL_BENZOATE
ALLERGEN_TYPE_CODE_BENZYL_CINNAMATE
ALLERGEN_TYPE_CODE_BENZYL_SALICYLATE
ALLERGEN_TYPE_CODE_BRAZIL_NUTS
ALLERGEN_TYPE_CODE_BUTYLPHENYL_METHYLPROPIONATE
ALLERGEN_TYPE_CODE_CARROTS
ALLERGEN_TYPE_CODE_CASHEW_NUTS
ALLERGEN_TYPE_CODE_CELERY
ALLERGEN_TYPE_CODE_CEREALS_CONTAINING_GLUTEN
ALLERGEN_TYPE_CODE_CINNAMAL
ALLERGEN_TYPE_CODE_CINNAMYL_ALCOHOL
ALLERGEN_TYPE_CODE_CITRAL
ALLERGEN_TYPE_CODE_CITRONELLOL
ALLERGEN_TYPE_CODE_COCOA
ALLERGEN_TYPE_CODE_CORIANDER
ALLERGEN_TYPE_CODE_CORN
ALLERGEN_TYPE_CODE_COUMARIN
ALLERGEN_TYPE_CODE_CRUSTACEANS
ALLERGEN_TYPE_CODE_EGGS
ALLERGEN_TYPE_CODE_EUGENOL
ALLERGEN_TYPE_CODE_EVERNIA_FURFURACEA
ALLERGEN_TYPE_CODE_EVERNIA_PRUNASTRI
ALLERGEN_TYPE_CODE_FARNESOL
ALLERGEN_TYPE_CODE_FISH
ALLERGEN_TYPE_CODE_GERANIOL
ALLERGEN_TYPE_CODE_GLUTEN
ALLERGEN_TYPE_CODE_HAZELNUTS
ALLERGEN_TYPE_CODE_HEXYL_CINNAMAL
ALLERGEN_TYPE_CODE_HYDROXYCITRONELLAL
ALLERGEN_TYPE_CODE_HYDROXYISOHEXYL_3_CYCLOHEXENE_CARBOXALDEHYDE_ISOEUGENOL_LIMONENE_LINAL
ALLERGEN_TYPE_CODE_KAMUT
ALLERGEN_TYPE_CODE_LACTOSE
ALLERGEN_TYPE_CODE_LUPINE
ALLERGEN_TYPE_CODE_MACADAMIA_NUTS
ALLERGEN_TYPE_CODE_METHYL_2_OCTYNOATE
ALLERGEN_TYPE_CODE_MILK
ALLERGEN_TYPE_CODE_MOLLUSCS
ALLERGEN_TYPE_CODE_MUSTARD
ALLERGEN_TYPE_CODE_NO_DECLARED_ALLERGENS
ALLERGEN_TYPE_CODE_OAT
ALLERGEN_TYPE_CODE_PEANUTS
ALLERGEN_TYPE_CODE_PEAS
ALLERGEN_TYPE_CODE_PECAN_NUTS
ALLERGEN_TYPE_CODE_PISTACHIOS
ALLERGEN_TYPE_CODE_POD_FRUITS
ALLERGEN_TYPE_CODE_QUEENSLAND_NUTS
ALLERGEN_TYPE_CODE_RYE
ALLERGEN_TYPE_CODE_SESAME_SEEDS
ALLERGEN_TYPE_CODE_SOYBEANS
ALLERGEN_TYPE_CODE_SPELT
ALLERGEN_TYPE_CODE_SULPHUR_DIOXIDE
ALLERGEN_TYPE_CODE_TREE_NUTS
ALLERGEN_TYPE_CODE_TREE_NUT_TRACES
ALLERGEN_TYPE_CODE_WALNUTS
ALLERGEN_TYPE_CODE_WHEAT

DepositCode

說明如何正確存放食物或瓶子。

名稱說明
DEPOSIT_CODE_UNSPECIFIED請勿使用。未明確指定存款代碼。
DEPOSIT_CODE_REUSABLE
DEPOSIT_CODE_RECYCLABLE

PropertyType

選項適用的房源類型。

名稱說明
UNKNOWN_PROPERTY_TYPE請勿使用。未明確指定屬性類型。
OPTION一般菜單項目選項屬性，不屬於下列更具體的類型。如果屬性不是 SIZE 或 PIZZA_SIDE 類型，請使用這項屬性。
SIZE表示尺寸的菜單項目選項屬性 (例如小、中或大)。
PIZZA_SIDE披薩專屬屬性。舉例來說，這個 MenuItemOption 僅適用於部分/整個披薩，例如左側、右側或整個披薩的蘑菇配料。

PropertyValue

選項屬性的值定義明確。

名稱說明
UNKNOWN_PROPERTY_VALUE請勿使用。屬性值未明確指定。
PIZZA_SIDE_LEFTMenuItemOption 僅適用於披薩左半邊。
PIZZA_SIDE_RIGHTMenuItemOption 只會套用至披薩右半邊。
PIZZA_SIDE_WHOLEMenuItemOption 會套用至整個披薩。

類型

欄位名稱類型規定說明
menu物件
(Menu)

與 section、item、option 互斥

section物件
(MenuSection)

與 menu、item、option 互斥

item物件
(MenuItem)

與 menu、section、option 互斥

option物件
(MenuItemOption)

與 menu、section、item 互斥

定價

菜單品項必須有價格，或一組菜單品項選項。 必填。

欄位名稱類型規定說明
offer_set物件
(OfferSet)

與 menu_item_option_set 互斥

可購買這項食品的優惠。
menu_item_option_set物件
(MenuItemOptionSet)

與 offer_set 互斥

這個選單項目可用的選項。

值

必要 oneof。

欄位名稱類型規定說明
amount數字

與 range 互斥

代表營養價值的單一數字。
range物件
(Range)

與 amount 互斥

代表營養價值的範圍。

值

必填。

欄位名稱類型規定說明
property_valenum
(PropertyValue)

與 text_val 互斥

選項屬性的明確值。目前只有在 property_type 為 PIZZA_SIDE 時，才會預期有這個值。
text_val物件
(TextField)

與 property_val 互斥

屬性值的文字 (格式不限)。預期用於 property_type 選項和 SIZE。