Alexa.PercentageControllerインターフェース
Alexa.PercentageController
インターフェースは、パーセンテージで表現できるエンドポイントのプロパティを制御するためのメッセージを記述します。
このインターフェースは、デバイスに適用される固有のコントローラーインターフェースが存在しない場合にのみ使用します。たとえば、輝度値に固有のリクエストを処理する場合は、代わりにAlexa.BrightnessControllerインターフェースを実装します。調光スイッチのようなエンドポイントの電力レベルに固有のリクエストを処理するには、Alexa.PowerLevelControllerインターフェースを実装します。
PercentageController
インターフェースでサポートされているロケールについては、機能インターフェースの一覧を参照してください。
発話
Alexa.PercentageController
インターフェースを使用する場合、音声対話モデルは既にビルドされています。以下に、ユーザーの発話の例を示します。
Alexa, set the <device name> to thirty percent.
Alexa, increase <device name> by ten percent.
Alexa, decrease <device name> by twenty percent.
Alexa, stelle <Geräteame> auf Anzahl Prozent.
Alexa, erhöhe <Gerätename> um 10 Prozent.
Alexa, reduziere <Gerätename> um 20 Prozent.
<デバイス名>を30%に設定して。
アレクサ、<デバイス名>を10パーセント上げて。
アレクサ、<デバイス名>を20パーセント下げて。
ユーザーがこのような発話をしたら、Alexaがそれに対応するディレクティブをスキルに送信します。
プロパティ
percentageプロパティ
Alexa.PercentageController
インターフェースは、percentage
プロパティをプライマリプロパティとして使用します。このプロパティは整数で、有効値は0~100(両端の値を含む)です。percentage
プロパティを使用して変化を表す場合、有効値は-100~100(両端の値を含む)です。
検出
Alexa.PercentageController
をサポートするエンドポイントは、Alexa.Discoveryの標準検出メカニズムを使用して表します。
Alexaからスキルに状態レポートリクエストが送信されるときにレポートするすべてのインターフェースとプロパティのretrievable
をtrueに設定します。変更レポートでAlexaにプロアクティブにレポートするインターフェースとプロパティのproactivelyReported
をtrueに設定します。
表示カテゴリーの一覧は、表示カテゴリーを参照してください。
応答例
以下は、Alexa.PercentageController
インターフェースをサポートする1つのエンドポイントへのDiscover.Response
メッセージの例です。
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "<メッセージID>"
},
"payload": {
"endpoints":[
{
"endpointId": "<エンドポイントの一意のID>",
"manufacturerName": "<エンドポイントのメーカー名>",
"modelName": "<エンドポイントのモデル名>",
"description": "<Alexaアプリに表示される説明>",
"friendlyName": "<Alexaアプリに表示されているデバイス名>",
"displayCategories": ["OTHER"],
"cookie": {},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa.PercentageController",
"version": "3",
"properties": {
"supported": [
{
"name": "percentage"
}
],
"proactivelyReported": true,
"retrievable": true
}
}
]
}
]
}
}
}
ディレクティブ
SetPercentageディレクティブ
ユーザーがデバイス設定のパーセント値を設定できるように、SetPercentage
ディレクティブをサポートします。
以下は、ユーザーの発話の例です。
Alexa, set the <device name> to thirty percent.
Alexa, stelle <Geräteame> auf Anzahl Prozent.
<デバイス名>を30%に設定して。
SetPercentageディレクティブペイロードの詳細
フィールド | 説明 | 型 |
---|---|---|
percentage |
デバイスに設定するパーセント値です。 | 整数 |
SetPercentageディレクティブの例
{
"directive": {
"header": {
"namespace": "Alexa.PercentageController",
"name": "SetPercentage",
"messageId": "<メッセージID>",
"correlationToken": "<opaque相関トークン>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<OAuth2ベアラートークン>"
},
"endpointId": "<エンドポイントID>",
"cookie": {}
},
"payload": {
"percentage": 74
}
}
}
SetPercentage応答イベント
SetPercentage
ディレクティブを正しく処理したら、Alexa.Responseイベントを使用して応答します。contextオブジェクトに、変更されたすべてのプロパティの値を含めます。応答は同期または非同期のどちらでも可能です。非同期で応答する場合、相関トークンと、認可トークンを含めたスコープを含めます。
SetPercentage応答イベントの例
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "<メッセージID>",
"correlationToken": "<opaque相関トークン>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<OAuth2ベアラートークン>"
},
"endpointId": "<エンドポイントID>",
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.PercentageController",
"name": "percentage",
"value": 74,
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
}
]
}
}
SetPercentageディレクティブのエラー処理
SetPercentage
ディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponseイベントを使用して応答します。
AdjustPercentageディレクティブ
ユーザーがデバイス設定のパーセント値を調整できるように、AdjustPercentage
ディレクティブをサポートします。
以下は、ユーザーの発話の例です。
Alexa, increase <device name> by ten percent.
Alexa, decrease <device name> by twenty percent.
Alexa, erhöhe <Gerätename> um 10 Prozent.
Alexa, reduziere <Gerätename> um 20 Prozent.
アレクサ、<デバイス名>を10パーセント上げて。
アレクサ、<デバイス名>を20パーセント下げて。
AdjustPercentageディレクティブペイロードの詳細
フィールド | 説明 | 型 |
---|---|---|
percentageDelta |
パーセント値の変更量です。 | 整数 |
AdjustPercentageディレクティブの例
{
"directive": {
"header": {
"namespace": "Alexa.PercentageController",
"name": "AdjustPercentage",
"messageId": "<メッセージID>",
"correlationToken": "<opaque相関トークン>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<OAuth2ベアラートークン>"
},
"endpointId": "<エンドポイントID>",
"cookie": {}
},
"payload": {
"percentageDelta": -20
}
}
}
AdjustPercentage応答イベント
AdjustPercentage
ディレクティブを正しく処理したら、Alexa.Responseイベントを使用して応答します。contextオブジェクトに、変更されたすべてのプロパティの値を含めます。応答は同期または非同期のどちらでも可能です。非同期で応答する場合、相関トークンと、認可トークンを含めたスコープを含めます。
AdjustPercentage応答イベントの例
{
"event": {
"header": {
"namespace": "Alexa",
"name": "Response",
"messageId": "<メッセージID>",
"correlationToken": "<opaque相関トークン>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<OAuth2ベアラートークン>"
},
"endpointId": "<エンドポイントID>",
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.PercentageController",
"name": "percentage",
"value": 54,
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 500
}
]
}
}
AdjustPercentageディレクティブのエラー処理
AdjustPercentage
ディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponseイベントを使用して応答します。
状態レポート
Alexaはエンドポイントの状態についての情報をリクエストするためにReportState
ディレクティブを送信します。AlexaがReportState
ディレクティブを送信したら、それに対する応答としてStateReport
イベントを送信します。この応答には、contextオブジェクトのすべてのretrievableプロパティの現在の状態を含めます。retrievableプロパティは検出応答で特定します。状態レポートの詳細については、状態レポートについてを参照してください。
StateReport応答イベントの例
{
"event": {
"header": {
"namespace": "Alexa",
"name": "StateReport",
"messageId": "<メッセージID>",
"correlationToken": "<opaque相関トークン>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<OAuth2ベアラートークン>"
},
"endpointId": "<エンドポイントID>",
},
"payload": {}
},
"context": {
"properties": [
{
"namespace": "Alexa.PercentageController",
"name": "percentage",
"value": 30,
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
変更レポート
エンドポイントの状態の変化をプロアクティブにレポートするために、ChangeReport
イベントを送信します。プロアクティブにレポートするプロパティは検出応答で特定します。変更レポートの詳細については、スマートホームスキルの状態レポートについてを参照してください。
ChangeReportイベントの例
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "<メッセージID>",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "<OAuth2ベアラートークン>"
},
"endpointId": "<エンドポイントID>",
},
"payload": {
"change": {
"cause": {
"type": "PHYSICAL_INTERACTION"
},
"properties": [
{
"namespace": "Alexa.PercentageController",
"name": "percentage",
"value": 65,
"timeOfSample": "2017-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
},
"context": {}
}