智慧型住宅 Dispense 特徵結構定義

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	支援的單位。 支援的值： CENTIMETERS CUPS DECILITERS FLUID_OUNCES GALLONS GRAMS KILOGRAMS LITERS MILLIGRAMS MILLILITERS MILLIMETERS NO_UNITS OUNCES PINCH PINTS PORTION POUNDS QUARTS TABLESPOONS TEASPOONS
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	來自 item_name 屬性的項目名稱。
amountRemaining	物件	裝置中剩餘的該項目數量。如果裝置目前正在供應，這個值會回報剩餘的量，或是裝置供應完畢後的量。
amount	Number	剩餘金額
unit	String	supported_units 屬性中的 amount 單位。
amountLastDispensed	物件	裝置最近一次供應該項目的數量。如果裝置目前正在供應，則應回報裝置在目前供應量之前所供應的量。
amount	Number	剩餘金額
unit	String	supported_units 屬性中的 amount 單位。
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	要分散的項目名稱 (來自 item_name 屬性)。
amount	Number	必填。 要分發的金額。
unit	String	必填。 amount 的單位，來自 supported_units 屬性。

依預設分發。

參數	類型	說明
presetName	String	必填。 從 preset_name 屬性選擇要處理的預設預設名稱。

不含參數的 Dispense。

參數	類型	說明
沒有任何屬性

範例

請給我 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 毫升)。
• deviceCurrentlyDispensing：使用者嘗試取用項目，但裝置已在供應該項目。
• deviceClogged：使用者嘗試取用商品，但裝置堵塞。
• deviceBusy：使用者嘗試分配項目，但裝置忙碌中 (一般)。

裝置例外狀況

這些例外狀況可在回應的 states 物件中以 exceptionCode 回報：

• amountRemainingLow：使用者從裝置中取出項目或金額，導致剩餘量降至低水準。您必須負責定義「低」等級的含義。
• userNeedsToWait - 使用者必須等待，才能成功取用所要求的項目或數量 (例如，水龍頭會供應熱水，但使用者需要等待水加熱後才能開始供應)。