スマートホームの 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 カップの分注ができるが、2.7 mL は供給されない）。deviceCurrentlyDispensing: ユーザーがアイテムの分量を得ようとしましたが、デバイスはすでに分量化しています。deviceClogged: ユーザーが商品をまとめようとしましたが、デバイスが詰まっています。deviceBusy: ユーザーがアイテムの供給を試みるが、デバイスがビジー状態（汎用）である。
デバイスの例外
これらの例外は、レスポンスの states オブジェクトで exceptionCode としてレポートできます。
amountRemainingLow- ユーザーはアイテムまたは金額をデバイスに分配し、残額を低レベルにします。「低」レベルの定義を定義する責任はユーザーにあります。userNeedsToWait- リクエストされたアイテムまたは量が正常に分量を準備されるまでユーザーが待つ必要がある場合（例: 蛇口から給水しますが、給湯する前に温める必要があります）。