Alexa.EndpointHealthインターフェース3.1

Alexa.EndpointHealthインターフェース3.1

AlexaスキルにAlexa.EndpointHealthインターフェースを実装すると、検出されたデバイスの健全性をAlexaにレポートできます。Wi-Fiパスワード変更による接続エラーなど、デバイスに問題が発生すると、Alexaがユーザーにデバイスのエクスペリエンス低下を知らせることができるよう、理由をレポートします。

Alexa.EndpointHealthインターフェースは、デバイスに機能を提供するほかのインターフェースと一緒に実装します。たとえば、デバイスがサーモスタットの場合は、ユーザーがサーモスタットを制御できるようにAlexa.ThermostatControllerを実装し、サーモスタットが温度を感知してレポートできるようにAlexa.TemperatureSensorを実装し、スキルがサーモスタットの接続ステータスをレポートできるようにAlexa.EndpointHealthを実装します。

Alexa.EndpointHealthインターフェースがサポートする言語については、Alexaインターフェースとサポートしている言語の一覧を参照してください。メッセージプロパティの定義については、Alexaインターフェースのメッセージとプロパティを参照してください。

発話

Alexa.EndpointHealthインターフェースにはユーザー発話はありません。代わりに、ユーザーがデバイスを制御しようとすると、Alexaがデバイスの健全性についての情報で応答します。たとえば、スキルがプラグにアクセスできないことをレポートしてユーザーがプラグをオンにしようとするとき、Alexaは「プラグが応答していません。ネットワーク接続と電源を確認してください。」と応答します。

出力可能なプロパティ

Alexa.EndpointHealthインターフェースには、以下の出力可能プロパティが含まれます。

Connectivityプロパティ

Connectivityプロパティは、デバイスの接続ステータスを表します。Connectivityは必須プロパティです。

UNREACHABLEとレポートすると、Alexaはデバイス制御リクエストに対して以下の例のような応答を返します。接続エラーのreasonは、応答に含まれていません。

device name isn't responding.Please check its network connection and power supply.
device name isn't responding.

device name مَا يَسْتَجِيب. يَالِيت تتأكد من اتصاله بالشبكة ومصدر طاقته
device name مَا يَسْتَجِيب

device name ne répond pas.Veuillez vérifier sa connexion réseau et son alimentation.
device name ne répond pas.

device name antwortet nicht.Bitte überprüfe die Netzwerkverbindung und Stromversorgung des Geräts.
device name reagiert gerade nicht.

device name से कनेक्शन नहीं हो पा रहा है. कृपया उसका नेटवर्क कनेक्शन और पावर सप्लाई ठीक से देख लें
device name से कनेक्शन नहीं हो पा रहा

device name non risponde.Verifica connessione di rete e alimentazione.
Il dispositivo device name non risponde.

デバイス名から応答がありません。ネットワークの接続と、電源を確認してください。
デバイス名から応答がありません。

apparaat naam reageert niet.Controleer de netwerkverbinding en stroomvoorziening.
apparaat naam reageert niet.

device name não está respondendo.Verifique a sua conexão de rede e fonte de alimentação.
device name não está respondendo.

device name no responde.Revisa la conexión de red y el suministro de alimentación del dispositivo.
device name no responde.

以下は、アクセスできないデバイスの例です。

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

{
    "name": "connectivity",
    "value": {
        "value": "UNREACHABLE",
        "reason": "WIFI_BAD_PASSWORD"
    }
}

connectivityプロパティは、次のフィールドを含むオブジェクトです。

フィールド 説明 型
value デバイスの接続ステータスです。
有効な値は OK、UNREACHABLEです。		 文字列
reason （任意）デバイスにアクセスできない場合、このプロパティにエラーの理由が入ります。
有効な値については、接続の理由値を参照してください。		 文字列

接続の理由値

以下の表は、接続エラーの各reasonについて、有効な値、説明、考えられる解決策をまとめたものです。

値 説明
WIFI_BAD_PASSWORD Wi-Fiのパスワードが誤っているためデバイスを接続できませんでした。
WIFI_AP_NOT_FOUND デバイスがWi-Fiアクセスポイントを見つけられません。デバイスは、ルーターから遠すぎるか、ベビーモニター、電子レンジなどの電子機器といった干渉を起こす別のデバイスと近すぎる可能性があります。
WIFI_ROUTER_UNREACHABLE デバイスは、ルーターにデータを送信できないか、ルーターからデータを受信できません。インターネットがダウンしているか、ルーターの再起動が必要な可能性があります。
WIFI_AP_CHANNEL_QUALITY_LOW デバイスはアクセスポイントに接続できますが、チャネルの品質は低いです。
INTERNET_UNREACHABLE デバイスはアクセスポイントに接続できますが、インターネットアクセスがありません。ルーターまたはデバイスの再起動が必要、またはインターネットがダウンしている可能性があります。
CAPTIVE_PORTAL_CHECK_FAILED デバイスはキャプティブポータルに接続しようとしています。インターフェースはキャプティブポータルをサポートしていません。空港やホテルではキャプティブポータルネットワークがよく使用されています。これらのネットワークは、接続する前にユーザーに特定の利用条件への同意を求めます。ユーザーは別のネットワークを選択する必要があります。
UNKNOWN 接続エラーの理由は不明です。

検出

Alexa.EndpointHealthインターフェースをサポートするエンドポイントは、Alexa.Discoveryの標準検出メカニズムを使用して表します。

Alexaからスキルに状態レポートリクエストが送信されたときにレポートするすべてのプロパティについて、そのretrievableをtrueに設定します。変更レポートでAlexaにプロアクティブにレポートするプロパティについては、そのproactivelyReportedをtrueに設定します。Alexa.EndpointHealthを実装するときは、サポートするプロパティのretrievableをtrueに設定し、proactivelyReportedをtrueに設定します。

検出応答の例

以下は、Alexa.EndpointHealthインターフェースとAlexa.LockControllerインターフェースをサポートするエンドポイントのDiscover.Responseメッセージの例です。

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

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "一意の識別子、バージョン4 UUIDが望ましい"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "エンドポイントの一意のID",
                "manufacturerName": "サンプルメーカー",
                "description": "Alexaアプリに表示される説明",
                "friendlyName": "Alexaアプリに表示されるデバイス名（例：玄関ドアなど）",
                "displayCategories": ["SMARTLOCK"],
                "additionalAttributes": {
                    "manufacturer": "サンプルメーカー",
                    "model": "サンプルモデル",
                    "serialNumber": "デバイスのシリアル番号",
                    "firmwareVersion": "デバイスのファームウェアバージョン",
                    "softwareVersion": "デバイスのソフトウェアバージョン",
                    "customIdentifier": "デバイスのカスタム識別子"
                },
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa.LockController",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                "name": "lockState"
                            }],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3.1",
                        "properties": {
                            "supported": [{
                                    "name": "connectivity"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    }
                ]
            }]
        }
    }
}

ディレクティブ

Alexa.EndpointHealthインターフェース自体はディレクティブを定義しません。Alexa.EndpointHealthを実装する場合は、ほかのインターフェースで定義されたディレクティブへの応答にconnectivityプロパティを含める必要があります。

ディレクティブ応答イベントの例

次の例では、デバイスはAlexa.PowerControllerインターフェースとAlexa.EndpointHealthインターフェースをサポートし、Alexa.ResponseをAlexa.PowerController.TurnOnディレクティブに送信します。

状態レポート

Alexaはエンドポイントの状態についての情報をリクエストするために、Alexa.ReportStateディレクティブを送信します。AlexaがAlexa.ReportStateディレクティブを送信したら、それに対する応答としてAlexa.StateReportイベントを送信します。応答には、contextオブジェクトのすべてのretrievableプロパティの現在の状態を含めます。retrievableプロパティは検出応答で特定します。状態レポートの詳細については、状態および変更レポートについてを参照してください。

Alexa.EndpointHealthを実装する場合、Alexa.StateReportにconnectivityプロパティを含めます。

StateReport応答の例

以下は、Alexa.EndpointHealthインターフェース、Alexa.ThermostatControllerインターフェース、Alexa.TemperatureSensorインターフェースをサポートするエンドポイントのAlexa.StateReportの例です。

変更レポート

エンドポイントの状態の変化をプロアクティブに出力するには、Alexa.ChangeReportイベントを送信します。プロアクティブにレポートするプロパティは検出応答で指定します。変更レポートの詳細については、状態および変更レポートについてを参照してください。

Alexa.EndpointHealthを実装する場合、Alexa.ChangeReportにconnectivityプロパティを含めます。connectivityプロパティの値が変更された場合は、これをペイロードフィールドに含めます。connectivityプロパティの値が変更されていない場合は、これをコンテキストフィールドに含めます。

変化しなかったデバイス健全性のレポート

以下は、Alexa.EndpointHealthインターフェースとAlexa.LockControllerインターフェースをサポートするエンドポイントのAlexa.ChangeReportの例です。この変更レポートでは、lockStateプロパティの値のみが変更されました。

変化したデバイス健全性のレポート

以下は、Alexa.EndpointHealthインターフェースとAlexa.LockControllerインターフェースをサポートするエンドポイントのAlexa.ChangeReportの例です。変更レポートでは、connectivityプロパティの値が変更されました。

このページは役に立ちましたか？

最終更新日: 2024 年 12 月 06 日