本頁面由 Cloud Translation API 翻譯而成。

智慧型住宅分散型點心結構定義

action.devices.traits.Dispense - 此屬性所屬的裝置可分配指定數量的一或多個實體項目。

此外，這項特性也支援配置預設食材，例如當做寵物餵食器的「貓食碗」或水龍頭的「玻璃」

裝置屬性

具有此特性的裝置可能會在 SYNC 作業中回報下列屬性。如要進一步瞭解如何處理 SYNC 意圖，請參閱意圖執行要求一文。

屬性	類型	說明
`supportedDispenseItems`	陣列	包含裝置可供應的所有商品相關資訊。
`[item, ...]`	物件	可出貨商品。
`item_name`	字串	必填。已售商品的內部名稱。這項功能不容易理解，並且與所有語言共用。
`item_name_synonyms`	陣列	必填。以各個支援語言分配的同義詞名稱。
`[item, ...]`	物件	特定語言的銷售項目的同義詞名稱。
`synonyms`	陣列	必填。已分配項目的同義詞名稱。這類話應包括單數與複數形式 (如果適用的話)。此清單的第一個字串必須是該語言的項目的複數形式。
`[item, ...]`	字串	同義詞名稱
`lang`	字串	必填。語言代碼 (ISO 639-1)。詳情請參閱支援的語言。
`supported_units`	陣列	必填。裝置支援的商品單位組合。
`[item, ...]`	字串	支援的單位。支援的值： `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`	字串	必填。分配單位。
`supportedDispensePresets`	陣列	裝置支援的預設設定。
`[item, ...]`	物件	預設。
`preset_name`	字串	必填。預設設定的內部名稱。此名稱不容易使用，且適用於所有語言。
`preset_name_synonyms`	陣列	必填。各個支援語言的預設設定同義詞名稱。
`[item, ...]`	物件	特定語言的預設同義詞名稱。
`synonyms`	陣列	必填。預設設定的同義詞名稱。同義詞應包括單數與複數形式 (如適用)。
`[item, ...]`	字串	同義詞名稱
`lang`	字串	必填。語言代碼 (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"
      }
    }
  ]
}

裝置狀態：STATE

具有此特性的實體可能會在 QUERY 作業中回報下列狀態。如要進一步瞭解如何處理 QUERY 意圖，請參閱意圖執行要求一文。

州	類型	說明
`dispenseItems`	陣列	裝置可供應的商品項目狀態。
`[item, ...]`	物件	特定項目的狀態。
`itemName`	字串	來自 `item_name` 屬性的項目名稱。
`amountRemaining`	物件	該項目在裝置中剩餘的金額。如果裝置目前正在分配，這會回報剩餘金額，或是裝置在配銷後的總金額。
`amount`	Number	剩餘金額
`unit`	字串	`supported_units` 屬性中的 `amount` 單位。
`amountLastDispensed`	物件	裝置最近自費支付的商品數量。如果裝置目前正在分配款項，則應回報裝置在目前配銷金額之前已配置的金額。
`amount`	Number	剩餘金額
`unit`	字串	`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`	字串	要供應的商品名稱，來自 `item_name` 屬性。
`amount`	Number	必填。要抵銷的金額。
`unit`	字串	必填。 `supported_units` 屬性中的 `amount` 單位。

item

字串

要供應的商品名稱，來自 item_name 屬性。

amount

Number

必填。

要抵銷的金額。

unit

字串

必填。

supported_units 屬性中的 amount 單位。

依預設而定。

參數類型說明

參數	類型	說明
`presetName`	字串	必填。來自「`preset_name`」屬性的預設設定名稱。

presetName

字串

必填。

來自「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 毫升)。
deviceCurrentlyDispensing：使用者嘗試供應某個項目，但裝置已經在供應中。
deviceClogged：使用者嘗試散佈項目，但裝置已損毀。
deviceBusy：使用者嘗試散佈項目，但裝置忙碌 (一般)。

裝置排除

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

amountRemainingLow - 使用者從裝置分配項目或金額，導致剩餘的金額偏低。您必須負責定義「低」層級的要素。
userNeedsToWait - 使用者必須等待要求的項目或金額成功供應 (比方說，水龍頭會供應熱水，但使用者必須等待水溫上升才能開始分配)。