智慧型住宅分配特徵架構

action.devices.traits.Dispense - 這項特徵屬於支援發放指定數量一或多個實體物品的裝置。

這項特徵也支援預設的分配量，例如寵物餵食器分配「貓食碗」的量，或水龍頭分配「一杯」的量。

裝置屬性

具有這項特徵的裝置可能會回報下列屬性，做為 SYNC 作業的一部分。如要進一步瞭解如何處理 SYNC 意圖，請參閱「意圖執行要求」。

屬性 類型 說明
supportedDispenseItems 陣列

包含裝置可分配的所有物品資訊。
[item, ...] 物件

可丟棄的物品。
item_name String

必要。

已發放商品的內部名稱。這可能不夠友善，而且所有語言都會共用。
item_name_synonyms 陣列

必要。

以各支援語言顯示的同義字名稱。
[item, ...] 物件

特定語言的發放項目同義字名稱。如要提供語言備用選項，至少須有一個項目的 lang 值為 en。
synonyms 陣列

必要。

替代名稱，同義詞應包含單數和複數形式 (如適用)。清單中的第一個字串必須是該語言的項目複數形式。
[item, ...] String

同義詞名稱。如要提供語言備用選項，至少須有一個項目的 lang 值為 en。
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 屬性。

不含參數的分配作業。

參數 類型 說明

沒有任何屬性

範例

給我 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": {}
}

裝置錯誤

如需完整清單，請參閱錯誤和例外狀況。
  • dispenseAmountRemainingExceeded：使用者嘗試從餘額不足的裝置領取商品或金額。
  • dispenseAmountAboveLimit：使用者嘗試發放的金額超出單一查詢可要求的上限。這是為了避免意外分配過多水量 (例如 50 萬杯水)。
  • dispenseAmountBelowLimit：使用者嘗試從裝置領取物品或金額，但該裝置可領取的最低金額高於使用者要求的金額。
  • dispenseFractionalAmountNotSupported：使用者嘗試分裝裝置無法分割的物品 (例如，裝置可能無法分割可數的物品，如狗狗零食)。
  • genericDispenseNotSupported：使用者嘗試從裝置取用物品，但未指定項目或預設值，且裝置不支援這類功能 (例如預設取用動作)。
  • dispenseUnitNotSupported：使用者嘗試從裝置取用該案件不支援的零件 (例如未提供該項目，因此系統跳過 supported_unit validation)。
  • dispenseFractionalUnitNotSupported：使用者嘗試分配可分割的項目，但無法分配指定單位 (例如水龍頭可能可分配 2.7 杯，但無法分配 2.7 毫升)。
  • deviceCurrentlyDispensing：使用者嘗試分裝商品，但裝置已在分裝商品。
  • deviceClogged：使用者嘗試分裝商品，但裝置堵塞。
  • deviceBusy：使用者嘗試分發商品，但裝置忙碌中 (一般)。

裝置例外狀況

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

  • amountRemainingLow - 使用者從裝置中取出商品或金額，導致剩餘金額偏低。您必須負責定義「低」等級的意義。
  • userNeedsToWait - 使用者必須等待一段時間，才能取得所要求的項目或數量 (例如水龍頭會供應熱水，但使用者必須等待水加熱後才能開始供應)。