スマートホームの Dispense トレイトのスキーマ

action.devices.traits.Dispense - このトレイトは、1 つ以上の物理的アイテムを指定の分量だけ供給できるデバイスに使用します。

このトレイトは、ペット用フィーダー用の「キャットフード ボウル」や蛇口用の「グラス」などのプリセットの供給もサポートします。

デバイスの属性

このトレイトを持つデバイスは、SYNC オペレーションの一部として次の属性を報告できます。SYNC インテントの処理について詳しくは、インテントのフルフィルメントをご覧ください。

属性 タイプ 説明
supportedDispenseItems 配列

デバイスが供給可能なすべてのアイテムに関する情報が含まれています。
[item, ...] オブジェクト

不要なアイテム。
item_name String

必須。

払い出されたアイテムの内部名。これは、ユーザー フレンドリーでない場合があり、すべての言語で共通です。
item_name_synonyms 配列

必須。

サポートされている各言語で調剤された場合の同義語名。
[item, ...] オブジェクト

指定された言語での調剤されたアイテムの同義語名。言語フォールバックを提供するには、lang 値が en のアイテムが少なくとも 1 つ必要です。
synonyms 配列

必須。

調剤されたアイテムの同義語名。該当する場合は、同義語に単数形と複数形の両方を含める必要があります。このリストの最初の文字列は、その言語のアイテムの複数形にする必要があります。
[item, ...] String

同義語の名前。言語フォールバックを提供するには、lang 値が en のアイテムが少なくとも 1 つ必要です。
lang String

必須。

言語コード（ISO 639-1）。サポートされている言語をご覧ください。
supported_units 配列

必須。

デバイスがそのアイテムに対してサポートしている単位のセット。
[item, ...] String

サポートされている単位。

サポートされている値:

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 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

item_name 属性のアイテムの名前。
amountRemaining オブジェクト

デバイスに残っているアイテムの分量。デバイスが現在供給中の場合は、残量またはデバイスが供給を終了した時点の量を報告します。
amount 数値

残額
unit String

supported_units 属性の amount の単位。
amountLastDispensed オブジェクト

デバイスが最後に供給したアイテムの分量。デバイスが現在供給中の場合は、現在の供給量の前に供給された分量を報告します。
amount 数値

残額
unit String

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 は、1 つの測定単位だけを使用して報告する必要があります。

dispenseItems 配列で複数のアイテムを指定できます。各アイテムの名前は一意にする必要があり、supportedDispenseItems 属性内のアイテムに対応している必要があります。

デバイスのコマンド

このトレイトを持つデバイスは、EXECUTE オペレーションの一部として次のコマンドに応答できます。EXECUTE インテントの処理について詳しくは、インテントのフルフィルメントをご覧ください。

action.devices.commands.Dispense

アイテムを配布します。

パラメータ

ペイロードには次のいずれかが含まれます。

金額で分配します。

パラメータ タイプ 説明
item String

item_name 属性から取得した、ディスペンサーから取り出すアイテムの名前。
amount 数値

必須。

吐出量。
unit String

必須。

supported_units 属性の amount の単位。

プリセットでディスペンスします。

パラメータ タイプ 説明
presetName String

必須。

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": {}
}

デバイスエラー

エラーと例外の全リストをご覧ください。
  • 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 - 特定のアイテムまたは分量が正常に供給されるまで待たなければならない場合（蛇口からお湯を得るには、水が温まるまで待たなければならない場合など）。