スマートホームの 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 |
整数 |
必須 支払額。 |
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 |
番号 |
残額 |
unit |
文字列 |
|
amountLastDispensed |
温度計 |
デバイスから最後に給付されたアイテムの分量。デバイスが現在供給中の場合は、現在の供給量の前に供給された量を報告します。 |
amount |
番号 |
残額 |
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 |
番号 |
必須 注入する量。 |
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 カップは供給できるが 2.7 mL は供給できない）。deviceCurrentlyDispensing: ユーザーがアイテムの供給を要求しましたが、デバイスはすでに供給中です。deviceClogged: ユーザーがアイテムを供給しようとしましたが、デバイスが詰まっています。deviceBusy: ユーザーがアイテムの供給を試みたが、デバイスはビジー状態（汎用）です。
デバイスの例外
これらの例外は、レスポンスの states オブジェクトで exceptionCode として報告される場合があります。
amountRemainingLow- ユーザーがデバイスからアイテムまたは分量を供給して、残量が低レベルになります。「低」レベルを定義する責任はユーザーにあります。userNeedsToWait- リクエストされたアイテムや量が正常に供給されるまで待たなければならない場合（たとえば、蛇口からお湯を出しても、水が温まるのを待ってから、給水を開始する必要があるなど）。