智慧型住宅細胞結構定義

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