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":"access-token-from-skill"
      }
    },
    "payload": {
    }
  }
}

イベントとプロパティ

プロパティ

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

ChangeReport

ChangeReportイベントは、Alexaに状態の変更を通知するために送信されます。検出時にproactivelyReportedとして提示したプロパティは、そのプロパティ値が変更されたときにはいつでも、プロパティが変更された理由にかかわらず、AlexaにChangeReportイベントを送信する必要があります。たとえば、「キッチンの照明」エンドポイントが点灯された場合は、それをAlexaに通知するために、Alexa.PowerControllerインターフェースのpowerStateプロパティの値が「オン」に変更になったことを示すChangeReportイベントを送信します。

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

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

変更レポートはイベントゲートウェイに送信する必要があります。これを行うには、エンドポイントにイベントを送信するアクセス権限をリクエストしてユーザーごとに認証情報を保存し、変更レポートのscopeに含める必要があります。詳細については、アクセス権限を設定してAlexaのユーザー認証を実現するを参照してください。

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


POST /v3/events HTTP/1.1
Host: api-amazonalexa.com
Authorization: Bearer access-token-from-Amazon
Content-Type: application/json

{
  "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":"access-token-from-Amazon"
       },
       "endpointId" :  "endpoint-001" ,
    },
    "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 変更されたプロパティの名前空間です。 文字列
name 変更されたプロパティの名前です。 文字列
value 変更されたプロパティの現在の値です。 プロパティの種類による文字列またはオブジェクト
timeOfSample プロパティが変更された時刻です。 ISO 8601形式の文字列、Zulu時間
uncertaintyInMilliseconds プロパティ値が最後に確認されてから経過した時間(ミリ秒)です。 文字列

Causeオブジェクト

causeアトリビュートは、ChangeReportイベントの送信時に、プロパティ値の変更の理由を記述するために使用されます。

原因の種類 説明
APP_INTERACTION イベントの原因が、ユーザーによるアプリケーションの操作にあったことを示します。たとえば、ユーザーがAlexaアプリやデバイスベンダーが提供するアプリを使用して照明のスイッチを切り替えたりドアをロックした場合です。
PHYSICAL_INTERACTION イベントの原因が、エンドポイントの物理的な操作にあったことを示します。たとえば、照明を手動でオンにした場合や、ドアの鍵を手動でロックした場合があります。
PERIODIC_POLL イベントの原因が、エンドポイントの定期的なポーリングにより値の変更が検出されたためであることを示します。たとえば、温度センサーを1時間に1回ポーリングして、更新された温度をAlexaに送信する場合があります。
RULE_TRIGGER イベントの原因が、デバイスルールの適用によるものであることを示します。たとえば、モーションセンサーが動きを検出した場合に照明をオンにするようにユーザーがルールを設定している場合があります。この場合、Alexaはモーションセンサーからイベントを受信するとともに照明からも別のイベントを受信し、状態の変更がルールによって発生したことを示します。
VOICE_INTERACTION イベントの原因が、音声による操作にあったことを示します。たとえば、ユーザーがEchoデバイスに話しかけた場合などです。

DeferredResponse

DeferredResponseは、遅延または非同期応答を送信することをディレクティブに同期的に応答する場合に使用します。DeferredResponseを送信した場合は、後でResponseイベントを送信する必要があります。

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

DeferredResponseの例


{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "DeferredResponse",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "payload": {
      "estimatedDeferralInSeconds": 7
    }
  }
}

ペイロードの詳細

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

ディレクティブを受信したら、同期的な応答を送信するか、ディレクティブを受信したことを表すDeferredResponseを送信して、後から非同期のイベントをAlexaエンドポイントに送信します。どちらの場合も、Alexaがタイムアウトするまでの時間は8秒です。

8秒のタイムアウトの例外は、以下のとおりです。

機能インターフェース 説明
LockController 低速ロックに設定し、想定されるResponseの遅延の秒数をDeferredResponseのestimatedDeferralInSecondsに指定します。

ErrorResponse

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

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


{
"event": {
    "header": {
      "namespace": "Alexa",
      "name": "ErrorResponse",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "endpoint":{
       "scope":{
          "type":"BearerToken",
          "token":"access-token-from-Amazon"
       },
       "endpointId":"appliance-001"
    },
    "payload": {
      "type": "ENDPOINT_UNREACHABLE",
      "message": "エンドポイント12345にアクセスできません。オフラインの可能性があります"
    }
  }
}

応答

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

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

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

同期応答の例

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

{
    "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": "abc-123-def-456",
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
        },
        "endpoint": {
            "endpointId": "appliance-001"
        },
        "payload": {}
    }
}

非同期応答の例

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


POST /v3/events HTTP/1.1
Host: api-amazonalexa.com
Authorization: Bearer access-token-from-Amazon
Content-Type: application/json

{
    "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": "abc-123-def-456",
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
        },
        "endpoint": {
            "scope": {
              "type": "BearerToken",
              "token": "access-token-from-Amazon"
            },
            "endpointId": "appliance-001"
        },
        "payload": {}
    }
}

StateReport

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

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

  • スキルのLambda関数から同期的に送信。
  • 非同期でAlexaのイベントゲートウェイに送信。非同期的に応答する場合、認可トークンにscopeを含めてユーザーを識別し、相関トークンを含めて応答先のディレクティブを識別する必要があります。

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

状態レポートの応答の例

この同期の例では、エンドポイントは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":{
         "endpointId":"appliance-001",
         "cookie":{}
      },
      "payload":{
      }
   }
}

その他のサンプルコード

リクエストと応答のサンプルについては、AlexaスマートホームのGitHubリポジトリで以下を参照してください。