Alexa.ReportStateインターフェースとAlexa.StateReportインターフェース

Alexa.ReportStateインターフェースとAlexa.StateReportインターフェース

スキルに状態レポートインターフェースが実装されていると、ユーザーがAlexaにデバイスの状態をたずねることができます。たとえば、ユーザーがAlexaアプリで自宅の別の階にある照明の状態をチェックしたとします。Alexaは、スキルにAlexa.ReportStateディレクティブを送信して、インターフェースで取得可能なすべてのプロパティの現在の状態を照会します。スキルはAlexa.StateReportで応答します。この例では、Alexa.ReportStateディレクティブに照明のエンドポイントIDが含まれています。

状態レポートの詳細については、状態および変更レポートについてを参照してください。

検出

検出中に、スキルでサポートしているインターフェースと、各インターフェースの取得可能なプロパティを特定します。インターフェースにretrievable = trueを設定すると、Alexaはそのインターフェースのプロパティの現在の状態をスキルに照会できます。

検出応答の例

以下は、照明を制御するAlexaスキルのDiscover.Responseメッセージの例です。このスキルは、Alexa.PowerControllerAlexa.BrightnessControllerAlexa.EndpointHealthの各インターフェースをサポートしています。powerStatebrightnessconnectivityは取得可能なプロパティです。

クリップボードにコピーされました。

{
    "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応答のプロパティ

プロパティ 説明 必須

event

レポートのエンドポイントを識別します。
空のpayloadオブジェクトを含めます。

Eventオブジェクト

context

取得可能なすべてのプロパティの状態をレポートします。

Contextオブジェクト

ReportStateディレクティブのエラー処理

Alexa.ReportStateディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponseイベントを使用して応答します。エンドポイントに到達できないためプロパティの状態を残らずレポートすることができず、値のキャッシュもない場合は、タイプがBRIDGE_UNREACHABLEまたはENDPOINT_UNREACHABLEAlexa.ErrorResponseを送信する必要があります。