スマートホームの Dispense トレイトのスキーマ
action.devices.traits.Dispense - このトレイトは、1 つ以上の物理的アイテムを一定量供給できるデバイスに使用します。
このトレイトは、ペット用フィーダー用の「キャットフード ボウル」や蛇口用の「グラス」などのプリセットの供給もサポートします。
デバイスの属性
このトレイトを持つデバイスは、SYNC オペレーションの一部として以下の属性をレポートできます。SYNC インテントの処理について詳しくは、インテント フルフィルメントをご覧ください。
| 属性 | タイプ | 説明 |
|---|---|---|
supportedDispenseItems |
配列 |
デバイスが供給可能なすべてのアイテムに関する情報が含まれています。 |
[item, ...] |
オブジェクト |
不要なアイテム。 |
item_name |
String |
必須。 発行されたアイテムの内部名。これは、ユーザー フレンドリーでない場合があり、すべての言語で共通です。 |
item_name_synonyms |
配列 |
必須。 サポートされている各言語で、dispensed の同義語名。 |
[item, ...] |
オブジェクト |
特定の言語で、提供される商品アイテムの同義語名。 |
synonyms |
配列 |
必須。 投薬されたアイテムの類義語名。該当する場合は、類義語に単数形と複数形の両方を含める必要があります。このリストの最初の文字列は、その言語のアイテムの複数形にする必要があります。 |
[item, ...] |
String |
類義語 |
lang |
String |
必須。 言語コード（ISO 639-1）。サポートされている言語をご覧ください。 |
supported_units |
配列 |
必須。 デバイスがそのアイテムに対してサポートしている単位のセット。 |
[item, ...] |
String |
サポートされている単位。 サポートされている値:
|
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 |
|
amountRemaining |
オブジェクト |
デバイスに残っているアイテムの分量。デバイスが現在供給中の場合は、残量またはデバイスが供給を終了した時点の量を報告します。 |
amount |
数値 |
残額 |
unit |
String |
|
amountLastDispensed |
オブジェクト |
デバイスが最後に供給したアイテムの分量。デバイスが現在供給中の場合は、現在の供給量の前に供給された分量を報告します。 |
amount |
数値 |
残額 |
unit |
String |
|
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 |
String |
|
amount |
数値 |
必須。 支払う金額。 |
unit |
String |
必須。
|
プリセットによる分注。
| パラメータ | タイプ | 説明 |
|---|---|---|
presetName |
String |
必須。
|
パラメータなしでディスペンスします。
| パラメータ | タイプ | 説明 |
|---|---|---|
プロパティがありません |
||
例
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 カップは注水できるが 2.7 mL を注ぐことはできない）。deviceCurrentlyDispensing: ユーザーがアイテムの供給を要求しましたが、デバイスによる供給はすでに進行中です。deviceClogged: ユーザーがアイテムの供給を要求しましたが、デバイスが詰まっています。deviceBusy: ユーザーがアイテムの供給を要求しましたが、デバイスがビジー状態（汎用）です。
デバイスの例外
これらの例外は、レスポンスの states オブジェクト内の exceptionCode として報告される場合があります。
amountRemainingLow- 特定のアイテムまたは分量が供給された結果、残量レベルが低くなりました。「低」レベルの定義は、事前にしておく必要があります。userNeedsToWait- 特定のアイテムまたは分量が正常に供給されるまで待たなければならない場合（蛇口からお湯を得るには、水が温まるまで待たなければならない場合など）。