總覽

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

系統會使用一般動態消息擷取菜單資料。事前準備：

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

建立及上傳菜單動態饋給

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

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

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

圖 1： 一般 SFTP 伺服器資訊

你可以在合作夥伴入口網站的「擷取」>「記錄」專區中，查看動態饋給擷取狀態。你可以在合作夥伴入口網站的「設定」>「動態饋給」部分中，找到動態饋給 SFTP 伺服器資訊。

使用菜單項目選項

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

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

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

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

提供多種菜單的餐廳

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

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

在不同餐廳之間共用菜單

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

最佳做法

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

  • 每間餐廳只能關聯一個菜單。
  • 在 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_nameobject
(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_nameobject
(TextField)

必填

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

菜單專區的說明。 選填。
images物件陣列
(Image)

菜單專區的圖片。 選填。

圖片

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

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

必填

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

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

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

必填

合作夥伴提供的隱晦字串，用來在合作夥伴動態消息中，唯一識別 MenuItem。必填。
display_nameobject
(TextField)

必填

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

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

菜單品項圖片。 選填。
oneOf
(pricing)

必填

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

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

OfferSet

容器，用於存放菜單品項 / 選項提供的優惠清單。 一次只能適用/有效一項優惠。 舉例來說，某項飲品可能提供 2 種優惠，一種適用於早上，另一種則適用於傍晚的歡樂時光。

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

必填

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

優惠

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

欄位名稱類型規定說明
priceobject
(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 定義的貨幣代碼，由 3 個字母組成。
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_informationobject
(NutritionInformation)

說明商品的完整營養資訊，例如卡路里、脂肪含量。選填。
suitable_diets列舉陣列
(DietaryRestriction)

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

這項菜單品項的添加物。 選填。
allergen物件陣列
(Allergen)

這道菜單品項的過敏原。 選填。
packaging_deposit_infoobject
(DepositInfo)

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

NutritionInformation

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

欄位名稱類型規定說明
energyobject
(NutritionValue)

一份食物的營養能量。可定義為卡路里或千焦耳。選填。
sodium_contentobject
(NutritionValue)

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

營養價值適用的份量數。 選填。
descriptionobject
(TextField)

以任意文字格式提供的營養資訊。例如「含有防腐劑」。 選填。

NutritionValue

說明食品分量的單一營養成分測量結果。

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

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

必填

合作夥伴指定的金額單位。我們會驗證動態饋給，確保每種營養價值類型都有適用的單位。舉例來說，NutritionalInformation 的能量屬性只應包含 ENERGY_CALORIES 和 ENERGY_KILOJOULES。必填。

範圍

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

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

必填

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

必填

營養價值的最大值。 必填。

加成

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

欄位名稱類型規定說明
nameobject
(TextField)

必填

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

MenuItem 是否含有、可能含有或不含此添加物。 預設值為 contains。 選填。

過敏原

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

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

必填

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

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

DepositInfo

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

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

要採用的押金策略，例如「可重複使用」。 選填。
deposit_valueobject
(Money)

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

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

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

必填

合作夥伴提供的隱晦字串，用來在合作夥伴動態饋給中識別 MenuItemOption。 必填。
valueobject
(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 會套用至整個披薩。

類型

欄位名稱類型規定說明
menuobject
(Menu)

與 section、item、option 互斥

sectionobject
(MenuSection)

與 menu、item、option 互斥

itemobject
(MenuItem)

與 menu、section、option 互斥

optionobject
(MenuItemOption)

與 menu、section、item 互斥

定價

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

欄位名稱類型規定說明
offer_setobject
(OfferSet)

與 menu_item_option_set 互斥

可購買這項食品的優惠。
menu_item_option_setobject
(MenuItemOptionSet)

與 offer_set 互斥

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

值

必要 oneof。

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

與 range 互斥

代表營養價值的單一數字。
rangeobject
(Range)

與 amount 互斥

代表營養價值的範圍。

值

必填。

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

與 text_val 互斥

選項屬性的明確值。目前只有在 property_type 為 PIZZA_SIDE 時才需要。
text_valobject
(TextField)

與 property_val 互斥

屬性值的任意形式文字。預期屬性類型為 OPTION 和 SIZE。