Alexaのインターフェース

Alexaのインターフェース

Alexaのインターフェースは、状態の取得とエラーのレポートに関するディレクティブとイベントを含んでいます。エンドポイントはAlexaのインターフェースを暗黙的に実装しますが、Discoveryに対して応答する際には、明示的にこのインターフェースとサポートしているバージョンを示す必要があります。

Discovery

Discoveryに応答する際に対応しているAlexaのインターフェースを識別させる方法を次に示します。

. . .
    {
    "type": "AlexaInterface",
    "interface": "Alexa",
    "version": "3"
    }
. . .

ディレクティブ

ReportState

エンドポイントの状態プロパティの現在の値を要求するために、ReportStateディレクティブが送信されます。以下の例では、エンドポイントappliance-001がメッセージの中で指定されています。そのエンドポイントに対応するすべてのプロパティを含んだStateReportを作成してReportStateに応答します。

ReportStateリクエストの例

{
  "directive": {
    "header": {
      "messageId": "abc-123-def-456",
      "correlationToken": "abcdef-123456",
      "namespace": "Alexa",
      "name": "ReportState",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "appliance-001",
      "cookie": {},
      "scope":{
            "type":"BearerToken",
            "token":"some-access-token"
      }
    },
    "payload": {
    }
  }
}

イベントとプロパティ

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

現在、Alexaのインターフェースでは、レポート可能なプロパティを定義しません。

ChangeReport

ChangeReportイベントは、Alexaに状態の変更をプロアクティブに通知し、Alexaアプリに端末の現在の状態を確実に反映させるために送信されます。たとえば、お客様が"キッチンの照明"エンドポイントを手動で点灯した場合は、それをAlexaに通知するために、Alexa.PowerControllerインターフェースのpowerStateプロパティの値が"オン"に変更になったことを示すChangeReportイベントを送信します。

検出時にproactivelyReportedとして提示したプロパティは、Alexaからのリクエストのディレクティブでないため、プロパティ値が変更されたときにはいつでもAlexaにChangeReportイベントを送信する必要があります。

  • ChangeReportpayloadを使用して、新しいプロパティ値と、その変更の理由を提供します。
  • オプションとして、ChangeReportcontextを使用して他の任意のプロパティの状態をレポートすることもできます(変更された可能性のあるプロパティをレポートしたり、すべてのプロパティの現在の状態をレポートしたりできます)。
  • 複数のプロパティが変更された場合は、Alexaに対して、ペイロードに1つのプロパティを入れた複数の変更レポートイベントを送信するか、ペイロードに複数のプロパティ値を入れた1つの変更レポートイベントを送信することができます。
  • どのユーザーのエンドポイントに対する通知なのかはendpointオブジェクトで示します。

変更レポートはプロアクティブに送信するものであり、Alexaとユーザーとの声によるやりとりの結果によるものではないので、イベントゲートウェイに対して状態を通知する必要があります。これを行うためには、あらかじめ、このイベントゲートウェイのエンドポイントに対してイベントを送るための許可を得、ユーザー毎のこの許可に関するコード情報を格納しておく必要があります。通知を行う際には scope オブジェクトにそのユーザーに与えられた許可に関するコード情報を含めます。詳細については、「Permissionsを使用してAlexaへのユーザー認証を実現する」を参照してください。

次の例は、Alexa.PowerControllerインターフェースとAlexa.BrightnessControllerインターフェースを実装した1つのエンドポイントに関するChangeReportイベントを示しています。このイベントは、エンドポイントのpowerStateがデバイスの物理的な相互作用によって"OFF"から"ON"に変更されたことをレポートし、輝度のレベルには変更がなかったため、輝度をcontextオブジェクトに入れてレポートしています。

{
  "context": {
    "properties": [
      {
        "namespace": "Alexa.BrightnessController",
        "name": "brightness",
        "value": 85,
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 60000
      }
    ]
  },
  "event": {
    "header": {
      "messageId": "abc-123-def-456",
      "namespace": "Alexa",
      "name": "ChangeReport",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type":"BearerToken",
        "token":"Alexa-access-token"
       },
       "endpointId" :  "<the endpoint identifier of the endpoint >" ,
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PHYSICAL_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.PowerController",
            "name": "powerState",
            "value": "ON",
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
        ]
      }
    }
  }
}

ペイロードの詳細

ChangeReportイベントのペイロードには、変更されたプロパティの配列の入ったChangeオブジェクトと、変更の理由を示すCauseオブジェクトを組み込みます。

フィールド 説明 必須
change 変更の原因を指定します causeオブジェクトを含むオブジェクト
properties 変更レポート送信の原因となったプロパティオブジェクトの配列を含みます。 propertyオブジェクトの配列
*property*.namespace 変更されたプロパティの名前空間 string
*property*.name 変更されたプロパティの名前 string
*property*.value 変更されたプロパティの現在の値 プロパティの種類によって異なります
*property*.timeOfSample プロパティが変更された時刻 ISO 8601形式の文字列、Zulu 時間。
*property*.uncertaintyInMilliseconds プロパティ値のミリ秒数 string

Causeオブジェクト

cause属性は、ChangeReportイベントの送信時に、プロパティ値の変更の原因を記述するために使用されます。これは、次に挙げる子要素をもつポリモーフィックな型です。

原因の種類 説明
APP_INTERACTION イベントの原因が、ユーザーとアプリケーションとの間のやりとりにあったことを示します。たとえば、お客様がAlexaアプリまたは端末ベンダーから提供されるアプリを使用して、照明をオンにした場合や、ドアをロックした場合です。
PHYSICAL_INTERACTION イベントの原因が、エンドポイントとの物理的な相互作用にあったことを示します。たとえば、照明を手動でオンにした場合や、ドアの鍵を手動でロックした場合があります。
PERIODIC_POLL 機器の定期的なポーリングにより値の変更が検出されたために、イベントが発生したことを示します。たとえば、温度センサーを1時間に1回ポーリングして、更新された温度をAlexaに送信する場合があります。
RULE_TRIGGER 端末ルールの適用によってイベントが発生したことを示します。たとえば、モーションセンサーがモーションを検出した場合、お客様は照明をオンにするルールを設定します。この場合、Alexaはモーションセンサーと照明からそれぞれのイベントを受信し、ルールが原因で状態の変化が発生したことを示します。
VOICE_INTERACTION イベントの原因が、Alexaとの声による対話にあったことを示します。たとえば、お客様がEcho端末に話しかけ、操作が行われた場合です。

DeferredResponse

ある操作要求のディレクティブに対して非同期で結果通知を行いたい場合、まず操作要求のディレクティブに対しては DeferredResponseで同期レスポンスをします。次に結果の通知を行うために Response をAlexaのイベントゲートウェイに送信します。

DeferredResponseは常に同期的に送信されるため、スコープはありません。

DeferredResponseの例

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "DeferredResponse",
      "messageId": "954fad82-15b4-4367-9e6a-297926031855",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "payload": {
      "estimatedDeferralInSeconds": 7
    }
  }
}

ペイロードの詳細

フィールド 説明 必須
estimatedDeferralInSeconds 任意。非同期応答が送信されるまでの概算時間を秒単位で示す整数。 整数 ×

ディレクティブを受信したときは、同期応答を送信するか、または、ディレクティブを受信したことを示すDeferredResponseを送信し、後でAlexaのエンドポイントに非同期イベントを送信することができます。いずれの場合も、Alexaがタイムアウトする8秒以内に実施する必要があります。

以下は例外として、8秒以上でも実施可能となります。

機能のインターフェース 備考
LockController 低速ロックにし、DeferredResponseestimatedDeferralInSecondsを使用してResponseの時間を長めに設定します。

ErrorResponse

ディレクティブを正常に処理できない場合は、ErrorResponseを送信します。エラーの種類やエラーの例の詳細については、Alexa.ErrorResponseを参照してください。

エラーの応答の例を次に示します。

{
"event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "a9a87be3-a41a-43c4-b734-04a8fcaf9d3c",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "endpoint":{
       "scope":{
          "type":"BearerToken",
          "token":"Alexa-access-token"
       },
       "endpointId":"appliance-001"
    },
    "payload": {
      "type": "ENDPOINT_UNREACHABLE",
      "message": "Unable to reach endpoint 12345 because it appears to be offline"
    }
  }
}

応答

ディレクティブが正常に処理された場合、Responseイベントで応答する必要があります。ResponseはLambda関数からAlexaに、または端末クラウドからAlexaのイベントゲートウェイに送信することができます。Responseイベントを送信するときは、影響を受けたプロパティの値をメッセージのコンテキストでレポートする必要があります。

ほとんどの場合、Alexaはタイムアウトするまでの8秒間、同期および非同期の両方の応答を待ちます。例外は個々のインターフェースに記載されています。たとえば、LockControllerインターフェースを実装しているエンドポイントからの非同期応答に関しては、Alexaの待ち時間は長くなります。

イベントゲートウェイと非同期で応答する場合、Responseには、Alexaのお客様であることを認証するスコープが必要になります。同期または非同期で応答するときは、メッセージに correlation トークンを含める必要があります。

同期応答の例

次の例は、調整可能な白色照明をサポートするエンドポイントの同期応答を示しています。

{
    "context": {
        "properties": [ {
            "namespace": "Alexa.ColorTemperatureController",
            "name": "colorTemperatureInKelvin",
            "value": 7500,
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 500
        } ]
    },
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "payloadVersion": "3",
            "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
        },
        "endpoint": {
            "endpointId": "appliance-001"
        },
        "payload": {}
    }
}

非同期応答の例

次の例は、調整可能な白色照明をサポートするエンドポイントの非同期応答を示しています。

{
    "context": {
        "properties": [ {
            "namespace": "Alexa.ColorTemperatureController",
            "name": "colorTemperatureInKelvin",
            "value": 7500,
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 500
        } ]
    },
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "payloadVersion": "3",
            "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
        },
        "endpoint": {
            "scope": {
              "type": "BearerToken",
              "token": "Alexa-access-token"
            },
            "endpointId": "appliance-001"
        },
        "payload": {}
    }
}

StateReport

ReportStateディレクティブ に対して期待される応答はStateReportです。この応答には、エンドポイントによって実装された各機能のインターフェースに対して Discovery のレスポンスで与えられた、すべてのレポート可能なプロパティを含むcontextオブジェクトが必要になります。各プロパティの現在の値をレポートしてください。エンドポイントに到達できない、またはエンドポイントがオフラインのため、プロパティの状態が不明の場合は、問題を指定するErrorResponseを返す必要があります。

StateReportは次の方法で送信します。

  • ReportStateディレクティブへの応答として同期的に送信します。
  • AlexaのイベントゲートウェイへのStateReportイベントと共に、非同期的に送信します。非同期応答の際には、お客様を識別する認可トークンを含むscopeと、応答するディレクティブを識別する correlation トークンが必要になります。

状態レポート応答の例

この例では、エンドポイントはAlexa.ThermostatController機能インターフェースを実装しています。

{
   "context":{
      "properties":[
         {
            "namespace":"Alexa.ThermostatController",
            "name":"targetSetpoint",
            "value":{
               "value":25.0,
               "scale":"CELSIUS"
            },
            "timeOfSample":"2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds":6000
         },
         {
            "namespace":"Alexa.ThermostatController",
            "name":"thermostatMode",
            "value":"HEAT",
            "timeOfSample":"2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds":6000
         }
      ]
   },
   "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":{

      }
   }
}

追加のサンプルコード

リクエストの例と応答メッセージについては、AlexaスマートホームGitHubリポジトリを参照してください。