智慧型住宅細胞結構定義

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

裝置 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 - 使用者必須等一段時間才能要求所需項目或容量，才能成功釋出 (例如，水龍頭會供應熱水，但使用者必須先等待飲水量才能開始進行補償)。