智慧型住宅細胞結構定義
action.devices.traits.Dispense
- 這個特性代表裝置可用於支援一或多個實體項目的指定數量。
這個特性也能夠支援預設值,例如寵物餵食器的「貓食碗」或「玻璃」等。
裝置屬性
具此特性的裝置可能會在 SYNC
作業中回報下列屬性。如要進一步瞭解如何處理 SYNC
意圖,請參閱意圖執行要求。
屬性 | 類型 | 說明 |
---|---|---|
supportedDispenseItems |
陣列 |
包含裝置可使用的所有商品相關資訊。 |
[item, ...] |
物件 |
。 |
item_name |
String |
必要。 已提款物品的內部名稱。這項行為不易使用,且支援所有語言。 |
item_name_synonyms |
陣列 |
必要。 已支援的語言 (使用各個支援的語言) 同義詞。 |
[item, ...] |
物件 |
以特定語言表示補償項的同義詞名稱。 |
synonyms |
陣列 |
必要。 已退商品的同義詞名稱。同義詞應同時包含單數與複數形式 (如適用)。這份清單的第一個字串必須是該語言中複數形式的項目。 |
[item, ...] |
String |
同義詞 |
lang |
String |
必要。 語言代碼 (ISO 639-1)。請參閱「支援的語言」。 |
supported_units |
陣列 |
必要。 裝置針對該商品支援的單位組合。 |
[item, ...] |
String |
支援的單位。 支援的值:
|
default_portion |
物件 |
必要。 可以補價的一般商品數量。 |
amount |
整數 |
必要。 已支付。 |
unit |
String |
必要。 已充電單位。 |
supportedDispensePresets |
陣列 |
裝置支援的預設設定。 |
[item, ...] |
物件 |
預設。 |
preset_name |
String |
必要。 預設設定的內部名稱。這個名稱可能不容易使用,而且會由所有語言共用。 |
preset_name_synonyms |
陣列 |
必要。 預設值,表示每個支援的語言支援的語言。 |
[item, ...] |
物件 |
預設語言的指定語言名稱。 |
synonyms |
陣列 |
必要。 預設設定的同義詞名稱。同義詞應同時包含單數與複數形式 (如適用)。 |
[item, ...] |
String |
同義詞 |
lang |
String |
必要。 語言代碼 (ISO 639-1)。請參閱「支援的語言」。 |
範例
支援水壺的液體電池
{ "supportedDispenseItems": [ { "item_name": "Water", "item_name_synonyms": [ { "lang": "en", "synonyms": [ "Water" ] } ], "supported_units": [ "TEASPOONS", "TABLESPOONS", "FLUID_OUNCES", "CUPS", "PINTS", "QUARTS", "GALLONS", "MILLILITERS", "LITERS", "DECILITERS" ], "default_portion": { "amount": 2, "unit": "CUPS" } } ], "supportedDispensePresets": [ { "preset_name": "cat_bowl", "preset_name_synonyms": [ { "lang": "en", "synonyms": [ "Cat water bowl", "Cat water dish", "Cat water cup" ] } ] }, { "preset_name": "glass_1", "preset_name_synonyms": [ { "lang": "en", "synonyms": [ "Glass of water", "Glass" ] } ] } ] }
沒有預設設定的寵物食材?
{ "supportedDispenseItems": [ { "item_name": "Treat", "item_name_synonyms": [ { "lang": "en", "synonyms": [ "Treats", "Dog treats", "Treat", "Dog treat" ] } ], "supported_units": [ "NO_UNITS" ], "default_portion": { "amount": 1, "unit": "NO_UNITS" } } ] }
裝置狀態
具有這個特性的實體可能會在 QUERY
作業中回報下列狀態。如要進一步瞭解如何處理 QUERY
意圖,請參閱意圖執行要求。
州 | 類型 | 說明 |
---|---|---|
dispenseItems |
陣列 |
裝置可密度的項目狀態。 |
[item, ...] |
物件 |
指定項目的狀態。 |
itemName |
String |
|
amountRemaining |
物件 |
裝置中剩餘的項目數量。如果裝置目前正在充電,報告中會顯示剩餘金額,或是裝置是否已付清的費用。 |
amount |
Number |
剩餘金額 |
unit |
String |
|
amountLastDispensed |
物件 |
裝置最近釋出的物品數量。如果裝置目前正在充飽電,則應回報在當前應繳金額之前應扣除的金額。 |
amount |
Number |
剩餘金額 |
unit |
String |
|
isCurrentlyDispensing |
布林 |
指出裝置是否正在支付這個項目。 |
範例
我的桶子中還有幾隻狗食?
{ "dispenseItems": [ { "itemName": "Dog treats", "amountRemaining": { "amount": 83, "unit": "NO_UNITS" }, "amountLastDispensed": { "amount": 2, "unit": "NO_UNITS" }, "isCurrentlyDispensing": false } ] }
飲水量剩下多少水?
{ "dispenseItems": [ { "itemName": "Water", "amountRemaining": { "amount": 6.2, "unit": "GALLONS" }, "amountLastDispensed": { "amount": 1, "unit": "CUPS" }, "isCurrentlyDispensing": false } ] }
我今天吃的貓食量是多少?
{ "dispenseItems": [ { "itemName": "cat_food", "amountRemaining": { "amount": 16.5, "unit": "CUPS" }, "amountLastDispensed": { "amount": 2.5, "unit": "CUPS" }, "isCurrentlyDispensing": false } ] }
水龍是否供應灰水?
{ "dispenseItems": [ { "itemName": "Water", "isCurrentlyDispensing": true } ] }
您只需使用一個測量單位amountRemaining
並回報amountLastDispensed
。
可在 dispenseItems
陣列中提供多個項目。每個項目名稱不得重複,且必須與 supportedDispenseItems
屬性中的項目相對應。
裝置指令
具有此特性的裝置可能會回應 EXECUTE
作業中的下列指令。如要進一步瞭解如何處理 EXECUTE
意圖,請參閱意圖執行要求。
action.devices.commands.Dispense
違規項目。
參數
酬載包含下列內容:
依金額區分。
參數 | 類型 | 說明 |
---|---|---|
item |
String |
要表示的項目名稱,來自 |
amount |
Number |
必要。 要發放的總金額。 |
unit |
String |
必要。
|
預設設定。
參數 | 類型 | 說明 |
---|---|---|
presetName |
String |
必要。 預設密度的名稱,來自 |
缺少參數。
參數 | 類型 | 說明 |
---|---|---|
沒有任何資源 |
範例
給我 1 杯的水。
{ "command": "action.devices.commands.Dispense", "params": { "amount": 1, "unit": "CUPS", "item": "Water" } }
填那貓水碗。
{ "command": "action.devices.commands.Dispense", "params": { "presetName": "cat_bowl" } }
豐富水源。
{ "command": "action.devices.commands.Dispense", "params": {} }
裝置 ERRORS
請參閱錯誤和例外狀況的完整清單。dispenseAmountRemainingExceeded
:使用者嘗試從裝置剩餘空間不足時取出項目或金額。dispenseAmountAboveLimit
:使用者嘗試的作業量超過單一查詢可要求的上限。這是為了避免意外消耗過多費用 (例如 500,000 杯的水)。dispenseAmountBelowLimit
:使用者嘗試從裝置中移除低於最低門檻的項目或數量。dispenseFractionalAmountNotSupported
:使用者嘗試拆解裝置無法分割的項目數量 (例如裝置可能無法對犬隻零食等量化項目)。genericDispenseNotSupported
:使用者嘗試在裝置上指定,但並未指定項目或預設設定,但裝置不支援這類功能 (例如預設拒絕動作)。dispenseUnitNotSupported
:使用者嘗試從不支援該單位的主機選取裝置 (例如未提供項目,因此略過supported_unit validation
)。dispenseFractionalUnitNotSupported
:使用者嘗試分散特定項目,但這些單位無法用於分隔特定單位,例如可以獲得水龍頭 2.7 杯,而不是 2.7 mL。deviceCurrentlyDispensing
:使用者嘗試拆解項目,但裝置已經可以消耗。deviceClogged
:使用者嘗試挑出項目,但裝置已經關閉。deviceBusy
:使用者嘗試竊取項目,但裝置處於忙碌狀態 (一般)。
裝置規格
您可以在回應的 states
物件中,將這些例外狀況回報為 exceptionCode
:
amountRemainingLow
- 使用者減少裝置所花費的金額或金額,藉此將剩餘的金額降到最低。您必須負責定義構成「低」等級的內容。userNeedsToWait
- 使用者必須等一段時間才能要求所需項目或容量,才能成功釋出 (例如,水龍頭會供應熱水,但使用者必須先等待飲水量才能開始進行補償)。