Alexaのインターフェース

Note: Sign in to the developer console to build or publish your skill.

Alexaインターフェース

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

Discovery
ディレクティブ
- ReportState
イベントとプロパティ
その他のサンプルコード

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イベントを送信します。

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

重要： プロパティの値は、イベント内のpayloadまたはcontextのどちらか1か所でのみレポートします。両方を使用することはできません。

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

変更レポートはイベントゲートウェイに送信する必要があります。これを行うには、エンドポイントにイベントを送信するアクセス権限をリクエストしてユーザーごとに認証情報を保存し、変更レポートの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オブジェクトを組み込みます。詳細については、propertyオブジェクトとcauseオブジェクトを参照してください。

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リポジトリで以下を参照してください。

このページは役に立ちましたか？

フィードバックを送信