Alexa.EndpointHealthインターフェース

Alexa.EndpointHealthインターフェース

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

ユーザーに最適なエクスペリエンスを提供するために、常にEndpointHealthを実装することをお勧めします。EndpointHealthの実装は任意ですが、次の場合は例外となります。

  • モーションセンサーや温度センサーなど、センサーデバイスにはEndpointHealthを実装する必要があります。
  • Works with AlexaまたはCertified for Humansプログラムの認定を受ける予定がある場合は、デバイスにEndpointHealthを実装する必要があります。

EndpointHealthインターフェースがサポートする言語については、Alexaインターフェースとサポートしている言語の一覧を参照してください。

プロパティ

connectivityプロパティ

Alexa.EndpointHealthインターフェースは、connectivityプロパティを使用してデバイスの接続を表します。connectivityプロパティは、次のフィールドを含むオブジェクトです。

フィールド 説明 型
value デバイスの接続ステータスです。OKまたはUNREACHABLEのいずれかです。 文字列

connectivityプロパティの例

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

{
    "name": "connectivity",
    "value": {
        "value": "OK"
    }
}

検出

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

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

検出応答の例

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

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

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<メッセージID>"
    },
    "payload": {
      "endpoints":[
        {
          "endpointId": "<エンドポイントの一意のID>",
          "manufacturerName": "<エンドポイントのメーカー名>",
          "description": "<Alexaアプリに表示される説明>",
          "friendlyName": "<Alexaアプリに表示されるデバイス名（例：玄関）>",
          "displayCategories": ["SMARTLOCK"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.LockController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "lockState"
                  }
                ],
                "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"
            }
          ]
        }
      ]
    }
  }
}

ディレクティブ応答

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

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

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

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

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "<エンドポイントID>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

状態レポート

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

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

StateReport応答イベントの例

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

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

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "<エンドポイントID>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.ThermostatController",
        "name": "thermostatMode",
        "value": "HEAT",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.ThermostatController",
        "name": "targetSetpoint",
        "value": {
          "value": 20.0,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      },
      {
        "namespace": "Alexa.TemperatureSensor",
        "name": "temperature",
        "value": {
          "value": 19.9,
          "scale": "CELSIUS"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 1000
      },
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
        },
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

変更レポート

エンドポイントの状態の変化をプロアクティブにレポートするために、ChangeReportイベントを送信します。プロアクティブにレポートするプロパティは検出応答で特定します。変更レポートの詳細については、スマートホームスキルの状態レポートについてを参照してください。

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

connectivityプロパティが変更されていないChangeReportイベントの例

以下は、EndpointHealthインターフェースとNetworking.AccessControllerインターフェースをサポートするエンドポイントのChangeReportの例です。この変更レポートでは、networkAccessプロパティの値が変更され、connectivityプロパティの値は変更されていません。

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

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "<メッセージID>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "APP_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.Networking.AccessController",
            "name": "networkAccess",
            "value": "ALLOWED",
            "timeOfSample": "2019-10-15T14:20:00Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.EndpointHealth",
        "name": "connectivity",
        "value": {
          "value": "OK"
        },
        "timeOfSample": "2019-10-15T14:20:00Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

connectivityプロパティが変更されたChangeReportイベントの例

以下は、EndpointHealthインターフェースとNetworking.AccessControllerインターフェースをサポートするエンドポイントのChangeReportの例です。この変更レポートでは、connectivityプロパティの値が変更され、networkAccessプロパティの値は変更されていません。

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

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "<メッセージID>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PERIODIC_POLL"
        },
        "properties": [
          {
            "namespace": "Alexa.EndpointHealth",
            "name": "connectivity",
            "value": {
              "value": "UNREACHABLE"
            },
            "timeOfSample": "2019-10-15T14:20:00Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.Networking.AccessController",
        "name": "networkAccess",
        "value": "ALLOWED",
        "timeOfSample": "2019-10-15T14:20:00Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}
このページは役に立ちましたか？

最終更新日: 2020 年 12 月 22 日