智慧型住宅供應特徵

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 屬性)。

不含參數的超量。

參數	類型	說明
沒有任何資源

範例

請給我 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：使用者嘗試分配的金額超出單次查詢可要求提供的內容上限。這是為了避免意外發放過多水量 (例如 500,000 杯水)。
• dispenseAmountBelowLimit：使用者嘗試從低於最低門檻的裝置供應商品或金額。
• dispenseFractionalAmountNotSupported：使用者嘗試分配少量裝置無法分割的項目 (舉例來說，狗狗點心等可計數的項目可能無法被裝置分割)。
• genericDispenseNotSupported：使用者嘗試處理裝置，但未指定項目或預設設定，但裝置不支援這類功能 (例如預設使用動作)。
• dispenseUnitNotSupported：使用者嘗試供應裝置不支援該情況的單位 (舉例來說，因為未提供項目，所以系統會略過 supported_unit validation)。
• dispenseFractionalUnitNotSupported：使用者嘗試分散少量的項目，但可以針對特定單位無法分割。舉例來說，水龍頭可能無法供應 2.7 杯，而非 2.7 mL。
• deviceCurrentlyDispensing：使用者嘗試送貨，但裝置已經棄置。
• deviceClogged：使用者嘗試丟棄商品，但裝置遭到關閉。
• deviceBusy：使用者試圖丟棄商品，但裝置忙碌中 (一般)。

裝置 EXCEPTIONS

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

• amountRemainingLow - 使用者從裝置中支付商品或金額，讓剩餘金額進入低階。您必須負責定義構成「低」等級的條件。
• userNeedsToWait - 當使用者需要等待，才能成功供應要求的商品或金額時 (例如，水龍頭會供應熱水，但使用者需要等水資源升溫後才能開始發放)。