Alexa.ReportStateインターフェースとAlexa.StateReportインターフェース
スキルに状態レポートインターフェースが実装されていると、ユーザーがAlexaにデバイスの状態をたずねることができます。たとえば、ユーザーがAlexaアプリで自宅の別の階にある照明の状態をチェックしたとします。Alexaは、スキルにAlexa.ReportState
ディレクティブを送信して、インターフェースで取得可能なすべてのプロパティの現在の状態を照会します。スキルはAlexa.StateReport
で応答します。この例では、Alexa.ReportState
ディレクティブに照明のエンドポイントIDが含まれています。
状態レポートの詳細については、状態および変更レポートについてを参照してください。
検出
検出中に、スキルでサポートしているインターフェースと、各インターフェースの取得可能なプロパティを特定します。インターフェースにretrievable = true
を設定すると、Alexaはそのインターフェースのプロパティの現在の状態をスキルに照会できます。
検出応答の例
以下は、照明を制御するAlexaスキルのDiscover.Response
メッセージの例です。このスキルは、Alexa.PowerController
、Alexa.BrightnessController
、Alexa.EndpointHealth
の各インターフェースをサポートしています。powerState
、brightness
、connectivity
は取得可能なプロパティです。
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "<一意の識別子、バージョン4 UUIDが望ましい>"
},
"payload": {
"endpoints": [{
"endpointId": "<照明のエンドポイントの一意のID>",
"manufacturerName": "<エンドポイントのメーカー名>",
"description": "<Alexaアプリに表示される説明>",
"friendlyName": "リビングの照明",
"displayCategories": ["LIGHT"],
"additionalAttributes": {
"manufacturer": "<エンドポイントのメーカー名>",
"model": "<デバイスのモデル>",
"serialNumber": "<デバイスのシリアル番号>",
"firmwareVersion": "<デバイスのファームウェアバージョン>",
"softwareVersion": "<デバイスのソフトウェアバージョン>",
"customIdentifier": "<デバイスのカスタム識別子>"
},
"cookie": {},
"capabilities": [{
"type": "AlexaInterface",
"interface": "Alexa.PowerController",
"version": "3",
"properties": {
"supported": [{
"name": "powerState"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.BrightnessController",
"version": "3",
"properties": {
"supported": [{
"name": "brightness"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3",
"properties": {
"supported": [{
"name": "connectivity"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}]
}
}
}
ディレクティブ
ReportStateディレクティブ
AlexaがAlexa.ReportState
ディレクティブを送信してエンドポイントの状態をリクエストすると、スキルはAlexa.StateReport
応答を送信します。この応答には、エンドポイントで取得可能なすべてのプロパティの現在の状態を含めます。
ReportStateディレクティブの例
次の例は、Alexaがスキルに送信するAlexa.ReportState
ディレクティブを示しています。endpointId
はデバイスを識別します。
{
"directive": {
"header": {
"namespace": "Alexa",
"name": "ReportState",
"messageId": "<一意の識別子、バージョン4 UUIDが望ましい>",
"correlationToken": "opaque相関トークン",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2ベアラートークン"
},
"endpointId": "<照明のエンドポイントID>",
"cookie": {}
},
"payload": {}
}
}
StateReport応答
スキルがリクエストを正常に処理した場合は、スキルから同期的にAlexa.StateReport
応答を送信します。応答には、Alexa.ReportState
リクエストで渡された値に設定したcorrelationToken
を含めます。
StateReport応答の例
以下の例は、取得可能なすべてのプロパティの状態を示します。
{
"event": {
"header": {
"namespace": "Alexa",
"name": "StateReport",
"messageId": "<一意の識別子、バージョン4 UUIDが望ましい>",
"correlationToken": "opaque相関トークン",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2ベアラートークン"
},
"endpointId": "<照明のエンドポイントID>"
},
"payload": {}
},
"context": {
"properties": [{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": "OFF",
"timeOfSample": "2022-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.BrightnessController",
"name": "brightness",
"value": 75,
"timeOfSample": "2022-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 1000
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2022-02-03T16:20:50.52Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
StateReport応答のプロパティ
プロパティ | 説明 | 型 | 必須 |
---|---|---|---|
|
レポートのエンドポイントを識別します。 |
|
◯ |
|
取得可能なすべてのプロパティの状態をレポートします。 |
|
◯ |
ReportStateディレクティブのエラー処理
Alexa.ReportState
ディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponse
イベントを使用して応答します。エンドポイントに到達できないためプロパティの状態を残らずレポートすることができず、値のキャッシュもない場合は、タイプがBRIDGE_UNREACHABLE
またはENDPOINT_UNREACHABLE
のAlexa.ErrorResponse
を送信する必要があります。
関連トピック
- Alexa.Discoveryインターフェース
- Alexa.ChangeReportインターフェース
- Alexa.EndpointHealthインターフェース
- Alexaインターフェースのメッセージとプロパティ
最終更新日: 2022 年 05 月 25 日