スマートホームの Dispense トレイトのスキーマ
action.devices.traits.Dispense - このトレイトは、指定した 1 つ以上の特定項目の分量をサポートするデバイス用です。
このトレイトは、ペット用フィーダー用の「キャットフード ボウル」や蛇口用の「グラス」などのプリセットの供給もサポートします。
デバイスの属性
このトレイトを持つデバイスは、SYNC オペレーションの一部として次の属性を報告できます。SYNC インテントの処理の詳細については、インテントのフルフィルメントをご覧ください。
| 属性 | タイプ | 説明 |
|---|---|---|
supportedDispenseItems |
配列 |
デバイスに供給可能なすべてのアイテムに関する情報が含まれています。 |
[item, ...] |
オブジェクト |
ディスペンサブリー アイテム。 |
item_name |
文字列 |
必須。 ディスペンス アイテムの内部名。これはユーザー フレンドリーな言語ではなく、すべての言語に共通です。 |
item_name_synonyms |
配列 |
必須。 サポートされている各言語で表記された表記の同義名。 |
[item, ...] |
オブジェクト |
特定の言語で公開されるアイテムの同義名。 |
synonyms |
配列 |
必須。 出品するアイテムの同義名。該当する場合は、単数形と複数形の両方を含める必要があります。このリストの最初の文字列は、その言語のアイテムの複数形である必要があります。 |
[item, ...] |
文字列 |
同義名 |
lang |
文字列 |
必須。 言語コード（ISO 639-1）。サポートされている言語をご覧ください。 |
supported_units |
配列 |
必須。 そのアイテムに対してデバイスがサポートするユニットのセット。 |
[item, ...] |
文字列 |
サポートされている単位。 サポートされている値:
|
default_portion |
オブジェクト |
必須。 出品される可能性のある商品の通常の量。 |
amount |
Integer |
必須。 出金額。 |
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"
}
}
]
}
デバイスのステータス
このトレイトを使用するエンティティは、QUERY オペレーションの一部として次の状態を報告できます。QUERY インテントの処理の詳細については、インテントのフルフィルメントをご覧ください。
| 状態 | タイプ | 説明 |
|---|---|---|
dispenseItems |
配列 |
デバイスが給水できるアイテムの状態。 |
[item, ...] |
オブジェクト |
特定のアイテムの状態。 |
itemName |
文字列 |
|
amountRemaining |
オブジェクト |
デバイスに残っているそのアイテムの金額。デバイスが現在給餌中の場合、残りの分量、または処理が開始した後の分量が表示されます。 |
amount |
Number |
残額 |
unit |
文字列 |
|
amountLastDispensed |
オブジェクト |
デバイスが最後に分注したそのアイテムの数量。デバイスが現在分量を給餌している場合は、現在の給餌量より前に分量が報告されます。 |
amount |
Number |
残額 |
unit |
文字列 |
|
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 は、1 つの測定単位を使用して報告するだけで済みます。
dispenseItems 配列内に複数のアイテムを指定できます。
各アイテム名は一意でなければならず、supportedDispenseItems 属性内のアイテムに対応している必要があります。
デバイスのコマンド
このトレイトを持つデバイスは、EXECUTE オペレーションの一環として次のコマンドに応答できます。EXECUTE インテントの処理の詳細については、インテントのフルフィルメントをご覧ください。
action.devices.commands.Dispense
アイテムを置く。
パラメータ
ペイロードには次のいずれかが含まれています。
金額で分注する。
| パラメータ | タイプ | 説明 |
|---|---|---|
item |
文字列 |
分配するアイテムの名前（ |
amount |
Number |
必須。 出金額。 |
unit |
文字列 |
必須。
|
プリセットで分量します。
| パラメータ | タイプ | 説明 |
|---|---|---|
presetName |
文字列 |
必須。
|
パラメータなしのディスペンス。
| パラメータ | タイプ | 説明 |
|---|---|---|
プロパティがありません |
||
例
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: ユーザーが 1 回のクエリで要求できる量の上限を超えています。これは、誤って大量の分（500,000 カップ分の水など）を供給することを防止するものです。dispenseAmountBelowLimit: ユーザーが、統一可能な最低数量を下回ったアイテムまたは金額をデバイスから分配しようとしました。dispenseFractionalAmountNotSupported: ユーザーが、デバイスが分割できない小数の項目（例: 犬用おやつのようなカウント可能な項目がデバイスによって分割できない）を提供しようとした。genericDispenseNotSupported: ユーザーがアイテムやプリセットを指定せずにデバイスからのディスペンスを試みましたが、デバイスがその機能（デフォルトのディスペンス アクションなど）をサポートしていません。dispenseUnitNotSupported: ユーザーは、そのケースでサポートされていないユニットを備えたデバイスから給餌しようとしています（たとえば、アイテムが指定されていないため、supported_unit validationはスキップされました）。dispenseFractionalUnitNotSupported: ユーザーが、分割はできるが、指定された特定の単位に該当しない小計のアイテム（たとえば、蛇口なら 2.7 ml の分量で給餌できるが、2.7 mL は供給できない）を配布しようとしました。deviceCurrentlyDispensing: ユーザーがアイテムの給餌を試みましたが、デバイスはすでに給餌しています。deviceClogged: ユーザーが商品アイテムの給餌を試みましたが、デバイスが詰まっています。deviceBusy: ユーザーがアイテムの供給を試みるが、デバイスがビジー状態（一般）である。
デバイスの例外
これらの例外は、レスポンスの states オブジェクトで exceptionCode として報告される場合があります。
amountRemainingLow- ユーザーがアイテムまたは金額をデバイスから提供し、残量を低くします。「低」レベルを構成するのはユーザーの責任です。userNeedsToWait- ユーザーがリクエストするアイテムや量が正常に給水されるまで待つ必要がある（例: 蛇口から給湯されるが、給水が終わるまで待つ必要がある）。