?
サポート

Alexa.EndpointHealthインターフェース

Alexa.EndpointHealthインターフェース

Alexa.EndpointHealthインターフェースでは、スマートデバイスが正しく稼働しているかを表す一連の状態プロパティを定義しています。

このインターフェースによって、デバイスの状態の詳細のレポートが可能となり、ユーザーはAlexaアプリを通してその状態を確認することもできます。たとえば、EndpointHealthプロパティの状態に応じて、アプリはデバイスの状態を緑、黄色、赤で表示することができます。

Discovery

Discoveryに応答する際に、このインターフェースで定義されたプロパティをサポートしているかどうかをレポートする必要があります。

以下のコードは、エンドポイントがEndpointHealthプロパティをサポートしている場合の例となります。端末の検出メッセージの詳細については、Alexa.Discoveryを参照してください。

{
   "event":{
      "header":{
         "namespace":"Alexa.Discovery",
         "name":"Discover.Response",
         "payloadVersion":"3",
         "messageId":"5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4"
      },
      "payload":{
         "endpoints":[
            {
               "endpointId":"appliance-002",
               "friendlyName":"Hallway Thermostat",
               "description":"Smart Thermostat by Sample Manufacturer",
               "manufacturerName":"Sample Manufacturer",
               "displayCategories":[
                  "THERMOSTAT"
               ],
               "cookie":{

               },
               "capabilities":[
                  {
                     "type":"AlexaInterface",
                     "interface":"Alexa.EndpointHealth",
                     "version":"3",
                     "properties":{
                        "supported":[
                           {
                              "name":"connectivity"
                           }
                        ],
                        "proactivelyReported":true,
                        "retrievable":true
                     }
                  },
                  {
                     "type":"AlexaInterface",
                     "interface":"Alexa.ThermostatController",
                     "version":"3",
                     "properties":{
                        "supported":[
                           {
                              "name":"targetSetpoint"
                           },
                           {
                              "name":"thermostatMode"
                           }
                        ],
                        "proactivelyReported":true,
                        "retrievable":true
                     }
                  },
                  {
                     "type":"AlexaInterface",
                     "interface":"Alexa.TemperatureSensor",
                     "version":"3",
                     "properties":{
                        "supported":[
                           {
                              "name":"temperature"
                           }
                        ],
                        "proactivelyReported":false,
                        "retrievable":true
                     }
                  }
               ]
            }
         ]
      }
   }
}

ディレクティブ

このインターフェースはディレクティブを定義しません。

プロパティとイベント

このインターフェースのプロパティの値は、次のいずれかの方法でレポートします。

レポート可能なプロパティ

プロパティ名 説明
connectivity connectivity ハブまたはクラウドと端末との間の通信パスの状態を示します。サポートされる値は、OKとUNREACHABLEです。

今後プロパティは追加される予定です。

ChangeReport

エンドポイントがproactivelyReportedとしてプロパティをサポートし、何らかの理由で値が更新された場合は、その値をAlexaにレポートする必要があります。

ChangeReportの例

{
   "context":{ },
   "event":{
      "header":{
         "messageId":"abc-123-def-456",
         "namespace":"Alexa",
         "name":"ChangeReport",
         "payloadVersion":"3"
      },
      "endpoint":{
         "scope":{
            "type":"AlexaUserId",
            "userId":"some-Amazon-user-id"
         },
         "endpointId":"<the endpoint identifier of the endpoint >"
      },
      "payload":{
         "change":{
            "cause":{
               "type":"PHYSICAL_INTERACTION"
            },
            "properties":[
               {
                  "namespace":"Alexa.EndpointHealth",
                  "name":"connectivity",
                  "value":{
                     "value":"UNREACHABLE"
                  }
                  "timeOfSample": "2017-02-03T16:20:50.52Z",
                  "uncertaintyInMilliseconds": 0
               }

            ]
         }
      }
   }
}

StateReport

エンドポイントがretrievableとしてプロパティをサポートし、AlexaからReportStateディレクティブを受信した場合は、その値をレポートする必要があります。

現在はエンドポイントに到達不能であるものの、エンドポイントのプロパティ値がキャッシュされており、エンドポイントのすべてのプロパティ値をレポートできる場合は、そのプロパティ値を組み込んだStateReportを返し、EndpointHealthconnectivityプロパティがUNREACHABLEであることを示す必要があります。エンドポイントに到達できないためにすべてのプロパティの状態をレポートできず、値をキャッシュしていない場合は、ErrorResponse型のBRIDGE_UNREACHABLEまたはENDPOINT_UNREACHABLEを送信する必要があります。

StateReportの例

{
  "context": {
    "properties": [{
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
         },
          "timeOfSample": "2017-02-03T16:20:50.52Z",
          "uncertaintyInMilliseconds": 0
      }
    ]
  },
  "event": {
    "header": {
      "messageId": "abc-123-def-456",
      "correlationToken": "abcdef-123456",
      "namespace": "Alexa",
      "name": "StateReport",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "some-access-token"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {}
  }
}