センサー用のスマートホームスキルを作成する



センサー用のスマートホームスキルを作成する

モーションセンサーや接触センサーなどのセンサー用に作成されたスマートホームスキルを使うと、Alexaでこれらのデバイスを使えるようになります。たとえば、スマートホームスキルを適切に設定すると、ユーザーが「アレクサ、寝室の窓は開いてる?」と聞くと、Alexaが正しい回答をしてくれるようになります。

このドキュメントでは、センサーを対象としたスマートホームスキルの技術的要件の概要や、特定のディレクティブとプロパティについて説明します。

スキル開発を開始する

初めてスマートホームスキルを作成する場合は、このドキュメントを読み進める前に、関連するその他のドキュメントを確認してください。スマートホームスキルの作成方法と、Alexaから送信されるスマートホームリクエストを処理するLambda関数のコードの作成方法を理解する必要があります。詳細については、次のページを参照してください。

v3と英語を対象にする

センサー用のスキルを作成する場合は、開発者コンソールでスキルの対象バージョンとしてv3(推奨)、対象言語として英語(米国)をそれぞれ選択する必要があります。これにより、スキルがセンサー関連のリクエストを受け取ることができます。

メッセージの形式

最初にAlexaがスキルのLambda関数に検出リクエストを送信するので、対象のセンサーを説明する応答を返します。各センサーは、インターフェース機能のリストに記載されたエンドポイントです。センサーのインターフェースは、レポート可能なプロパティを定義します。これらのプロパティは、イベントでエンドポイントの現在の状態を説明するのに使用します。送受信されるメッセージとその形式の詳細については、スマートホームスキルAPIのメッセージリファレンスを参照してください。

センサーは、機能で特定のディレクティブやディレクティブを起動する発話を定義せず、代わりにAlexaからの状態リクエストに応答するイベントを送信するか、センサーの状態が変更されたときにAlexaに変更レポートを送信するという点が、他の種類のエンドポイントと若干異なります。

機能を選択する

上記のとおり、メッセージの形式はインターフェースで、デバイスの機能別に整理されて定義されています。以下の表は、センサーの機能をサポートするために実装できるインターフェースの一覧です。

操作 機能インターフェース
接触を検出してレポートします。 Alexa.ContactSensor
動きを検出してレポートします。 Alexa.MotionSensor
温度を検出してレポートします。 Alexa.TemperatureSensor
エンドポイントを検出して記述します。すべてのスマートホームスキルに実装されます。 Alexa.Discovery
スキルでサポートされるAPIメッセージのバージョンを表します。すべてのスマートホームスキルに実装されます。 Alexaインターフェース
エンドポイントの現在の状態を表します。すべてのスマートホームスキルに実装されます。 Alexa.EndpointHealth

センサーの検出

標準の検出メカニズムを使って、センサーエンドポイントを記述します。詳細については、Alexa.Discoveryを参照してください。

センサーはChangeReportイベントを送信して、センサーのプロパティが常にproactivelyReportedになるようにする必要がある点に注意してください。また、センサーをサポートするエンドポイントはEndpointHealthもサポートする必要があります。

センサーエンドポイントを識別する

Alexaアプリが正しい状態を表示できるよう、常にセンサーの正しいdisplayCategoriesの値を提供する必要があります。センサーは以下のいずれかになります。

CONTACT_SENSOR
接触を検出してレポートするエンドポイントを表します。
MOTION_SENSOR
動きを検出してレポートするエンドポイントを表します。
TEMPERATURE_SENSOR
温度を検出してレポートするエンドポイントを表します。

たとえば、動きを感知できるエンドポイントの場合、表示カテゴリーを以下のように設定する必要があります。

"displayCategories":["MOTION_SENSOR"]

検出の例

以下は、動きの検出をサポートするセンサーの記述方法のコード例です。

例: MotionSensorのDiscover.Response

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "ff746d98-ab02-4c9e-9d0d-b44711658414"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "sensor-001",
          "manufacturerName": "エンドポイントのメーカー名",
          "friendlyName": "寝室のセンサー",
          "description": "ユーザーに表示される説明です",
          "displayCategories": [
            "MOTION_SENSOR"
          ],
          "cookie": {
            "key1": "このエンドポイントのキーと値のペアです",
            "key2": "複数のエントリーがある場合があります",
            "key3": "参照目的で使用します",
            "key4": "現在のエンドポイントの状態を維持するためには使わないでください"
          },
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.MotionSensor",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "detectionState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.EndpointHealth",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "connectivity"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            }
          ]
        }
      ]
    }
  }
}

センサーの状態レポート

センサーエンドポイントにとって状態レポートは非常に重要です。窓が開いたり、モーションセンサーが動きを検出したりといった場合には、状態レポートを使ってユーザーに通知するからです。センサーエンドポイントの場合:

  • エンドポイントのプロパティ値が変更した場合は必ずプロアクティブにChangeReportイベントを送信し、ChangeReportに変更が検出された時間(イベントを送信した時間ではない)を明記する必要があります。

  • スキルでReportStateディレクティブに応答する場合はStateReportイベントを使い、エンドポイントの現在の状態を伝えることをおすすめします。ただし、センサーの電力が小さい場合は必須ではありません。

  • デバイスの電力が小さく、ReportStateディレクティブに応答できない場合、エンドポイントは検出の完了直後にChangeReportイベントを送信する必要があります。これにより、Alexaアプリがエンドポイントの正しい状態を反映できます。後続の変更レポートは、プロパティの変更が検出されたときにのみ送信される必要があります。

状態レポートの詳細については、スマートホームスキルの状態レポートについてを参照してください。

エラー

ユーザーが対応できないリクエストをしたり、スキルとエンドポイントとの間に通信の問題がある場合は、エラーが発生する可能性があります。センサーエンドポイントは、Alexa.ErrorResponseのトピックに記載した一般的なエラーを返す必要があります。

詳細情報

スキルを実装する手順の詳細については、スマートホームスキルの作成手順を参照してください。

Alexaから送信されるディレクティブのメッセージ形式や応答の方法の詳細については、スマートホームスキルAPIのメッセージリファレンスを参照してください。