スマートホームスキルAPIのメッセージリファレンス

スマートデバイスでやり取りされるメッセージの基本フローと形式は共通しています。Alexaはディレクティブと呼ばれるリクエストメッセージを送信し、スキルは同期的または非同期的なイベントで応答します。

スマートデバイス用のスキルは、照明やドアロックなどそれぞれの機能でサポートされるディレクティブ、イベント、プロパティを表す機能インターフェースを実装しています。

このトピックでは、基本的なメッセージの形式と、機能領域ごとの機能について説明します。

メッセージのフロー
ディレクティブとイベントの形式
Headerオブジェクト
Endpointオブジェクト
- Scopeオブジェクト
  - BearerTokenスコープ
  - BearerTokenWithPartitionスコープ
Contextオブジェクト
Payloadオブジェクト

メッセージのフロー

Alexaは、ユーザーに代わって何かをリクエストするディレクティブをスキルに送信します。開発者は、イベントでディレクティブに応答するコードを提供します。コードはAWS Lambda（アマゾンウェブサービスによって提供されるサービス）のLambda関数としてホスティングされます。ディレクティブに対しては、以下の方法で応答できます。

8秒以内に、Lambda関数からAlexa.Responseイベントまたはエラーメッセージイベントで同期的に応答します。
8秒以内に、Alexaイベントゲートウェイに対してAlexa.Responseイベントまたはエラーメッセージイベントで非同期的に応答します。非同期的な応答は、一部のインターフェースではサポートされていません。詳細はインターフェースの個別のトピックを参照してください。

または

時間がかかる操作の場合は、Alexa.DeferredResponseイベントで同期的に応答し、後からAlexaイベントゲートウェイに対してAlexa.Responseイベントまたはエラーメッセージイベントで非同期的に応答します。Alexa.DeferredResponseは現在、LockControllerインターフェースでサポートされています。

ディレクティブとイベントの形式

スキルに送信されるディレクティブとスキルからAlexaに返されるイベントは、同じ基本構造を共有しています。

したがって、ディレクティブとイベントには、以下の上位レベルのオブジェクトが含まれます。

Header
Endpoint
Payload

さらに、イベントには以下のオブジェクトが含まれる場合があります。

Context

重要： 認識できない追加のフィールドが含まれるディレクティブを受け取った場合でも、失敗が発生しないようにする必要があります。

Headerオブジェクト

ヘッダーに含まれるフィールドは、すべての種類のメッセージに共通です。これらのフィールドでは、さまざまな種類の識別情報を提供します。以下は、一般的なメッセージヘッダーの例です。

"header": {
  "namespace": "Alexa.PowerController",
  "name": "TurnOn",
  "messageId": "6d6d6e14-8aee-473e-8c24-0d31ff9c17a2",
  "correlationToken": "abcdef-123456",
  "payloadVersion": "3"
}

ヘッダーには以下のプロパティを含めることができます。

プロパティ	説明
`namespace`	メッセージペイロードのカテゴリーを表す文字列です。そのディレクティブが含まれる機能インターフェースと同じものを使用します。例： `Alexa.PowerController` `Alexa.ThermostatController`
`name`	`TurnOn`、`TurnOff`など、ディレクティブの名前です。
`messageId`	1つのリクエストまたは応答の一意の識別子です。この情報はトラッキングに使用されます。スキルのログに記録しますが、ビジネスロジックのサポートには使用しません。すべてのメッセージのこのフィールドに値が含まれている必要があります。有効な値は、英数字とダッシュで構成される128文字未満の文字列ですが、ランダムな数値から生成されるバージョン4のUUIDが推奨されます。
`correlationToken`	ディレクティブとそれに関連付けられた1つまたは複数のイベントを識別するトークンです。以下の種類のメッセージに相関トークンが含まれます。 Alexaからスキルへのディレクティブディレクティブに応答するイベントディレクティブリクエストに対する応答イベントには、同じ相関が含まれる必要があります。イベントがAlexaからのリクエストへの応答に含まれない場合、相関トークンは提供されません。
`payloadVersion`	このメッセージに適用される機能インターフェースのバージョンです。

Endpointオブジェクト

Endpointオブジェクトは、ディレクティブのターゲットとイベントの発生元を表します。エンドポイントは次のいずれかになります。

物理デバイス
仮想デバイス
デバイスのグループまたは集合
ソフトウェアコンポーネント

さらに、エンドポイントオブジェクトには認証トークンが含まれます。

ディレクティブでは、このトークンを使うと、エンドポイントが指定するデバイスまたはコンポーネントとの通信が可能になります。
イベントでは、Alexaイベントゲートウェイに送信されるイベントにのみトークンが必要です。

以下は、JSONで記述した一般的なメッセージのエンドポイントの例です。

 "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "Alexa-access-token"
      },
      "endpointId": "ターゲットエンドポイントのIDです",
      "cookie": {
         "key1": "何らかの情報",
         "key": "検出中に受け取ったペアの値"
      }
    },

エンドポイントオブジェクトには以下のプロパティが含まれます。

プロパティ	説明
`scope`	メッセージ交換の認証付与に関する設定を記述する、ポリモーフィズムなオブジェクトです。詳細については、Scopeオブジェクトを参照してください。
`endpointId`	一意のIDです。この識別子は、スキルのドメイン内であるユーザーが所有するすべてのエンドポイントで一意である必要があります。デバイスの検出中に最初に提供され、このユーザーに関連付けられたデバイスを識別する際に、共通で使用される必要があります。
`cookie`	エンドポイントに関連付けられたキー／値ペアのリストです。これらは検出中に提供され、エンドポイントの各メッセージで送信されます。

Scopeオブジェクト

Scopeは、メッセージに認可および識別情報を提供するポリモーフィズムなオブジェクトです。Scopeには、typeフィールドと、型によって大きく異なる追加のキー／値ペアが含まれます。以下の表では、サポートされている現在の型を示しています。

BearerTokenスコープ

リンクされたユーザーアカウントにアクセスするため、またはAlexaユーザーを識別するための、OAuthベアラートークンを提供します。通常は、スマートホームスキルで使用されます。

フィールド	説明	型	必須
`token`	スキルが有効になったときに、アカウントリンクされたシステムでユーザーを検証するためのトークンです。	文字列	◯

BearerTokenの例

"scope": {
        "type": "BearerToken",
        "token": "Alexa-access-token"
      }

BearerTokenWithPartitionスコープ

リンクされたユーザーアカウントおよび検出リクエストを出す場所にアクセスするための、OAuthベアラートークンを提供します。通常は、Alexa for Businessを対象とするスキルで使用されます。（日本未対応）スコープの種類がBearerTokenWithPartitionの場合、以下のフィールドが含まれます。

フィールド	説明	型	必須
`token`	リンクされたユーザーアカウントを識別し、アクセスするためのトークンです。	文字列	◯
`partition`	部屋の名前や番号など、リクエストの対象となる場所です。	文字列	◯
`userId`	リクエストを行ったユーザーの一意のIDです。ユーザーの本人確認は、`userId`ではなく`token`を使用して行う必要があります。	文字列	◯

BearerTokenWithPartitionの例

"scope": {
        "type": "BearerTokenWithPartition",
        "token": "some-access-token",
        "partition": "101号室",
        "userId":"some-user-id"
      }

ディレクティブのメッセージでは、アカウントリンクを行った後、システムでユーザーを識別するためのトークンがscopeに含まれます。詳細については、スマートホームなどのドメインのアカウントリンクを参照してください。
イベントのメッセージのscopeに、Alexaにユーザーを識別させるためのトークンが含まれる場合があります（オプション）。トークンは、Login with Amazon（LWA）による権限プロセスで取得されます。このトークンは、Alexaイベントゲートウェイへのメッセージでは必須です。詳細については、アクセス権限を使用してAlexaのユーザー認証を実現するを参照してください。

Contextオブジェクト

contextオブジェクトは、エンドポイントの状態をレポートするときに任意のイベントメッセージで使用します。contextには、レポート可能なプロパティのオブジェクトとその状態の配列が含まれます。contextを使って応答イベントを送信する場合、出力される値には、ディレクティブの処理によって生じる副次的な影響がすべて含まれることを確認する必要があります。つまり、出力されるプロパティの値はディレクティブの処理によって変化した後の値である必要があります。

contextオブジェクトと状態レポートの詳細については状態レポートを、プロパティの構造の詳細についてはプロパティのスキーマを参照してください。

以下は、Alexa.ThermostatControllerインターフェースを実装するエンドポイントのコンテキストの例です。

"context": {
  "properties": [
    {
      "namespace": "Alexa.ThermostatController",
      "name": "targetSetpoint",
      "value": {
        "value": 25.0,
        "scale": "CELSIUS"
      },
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 0
    },
    {
      "namespace": "Alexa.ThermostatController",
      "name": "thermostatMode",
      "value": "HEAT",
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 0
    }
  ]
}

フィールド	説明
`namespace`	プロパティのインターフェースを指定します。
`name`	レポートに表示されるプロパティ名です。
`timeOfSample`	プロパティ値がサンプリングされた時刻です（ISO 8601形式）。UTCで指定されます。例： "YYYY-MM-DDThh:mm:ss.sD"
`uncertaintyInMilliseconds`	レポートされるプロパティが不確実である期間です。プロパティ値が取得されたと見なされる時点からの経過時間（ミリ秒）で示します。たとえば、60秒ごとにハードウェアデバイスをポーリングすることで値を取得する場合、サンプリングされた値が不確実な期間は60000ミリ秒です。

Payloadオブジェクト

メッセージのペイロードは、メッセージの種類によって異なります。以下のセクションでは、機能領域別のメッセージについて説明します。

検出に関するメッセージ

このインターフェースには、デバイスとこのスキルアダプターで利用可能な機能を識別するメッセージが含まれます。

操作	機能インターフェース
エンドポイントを検出し、その機能についてレポートします	Alexa.Discovery

状態および変更レポートに関するメッセージ

これらのメッセージは以下の場合に送信されます。1.インターフェースのプロパティの状態をリクエストするとき、2.状態のリクエストに応答するとき、変更レポートを送信するとき、3.後から応答がイベントゲートウェイに送信されることをAlexaに通知するときこれらのメッセージは、リクエストディレクティブのインターフェースの種類と関係なく、すべて同じ形式です。

操作	メッセージ
成功したディレクティブリクエストに応答します	応答
状態レポートをリクエストします	Alexa.ReportState
状態レポートのリクエストに応答します	Alexa.StateReport
エンドポイントのプロパティが変更されたことをAlexaにプロアクティブに通知します	Alexa.ChangeReport
操作時間が8秒を超えるため、メッセージに非同期的に応答することをAlexaに通知します（ドアロックに使用）	Alexa.DeferredResponse
エンドポイントの接続状態をレポートします	Alexa.EndpointHealth

電力制御に関するメッセージ

この種類のメッセージは、エンドポイントの電源をオンまたはオフにしたり、デバイスの電力レベルを制御したりします。さまざまな種類のデバイスで一般的に使用されます。

操作	機能インターフェース
エンドポイントのオン／オフを切り替えます	Alexa.PowerController
エンドポイントの電力レベルを設定します	Alexa.PowerLevelController

ドアロックの制御および照会に関するメッセージ

このインターフェースには、ロックの現在の状態を照会したり、状態を変更したりするためのメッセージが含まれます。詳細については、ロック用のスマートホームスキルを作成するを参照してください。

操作	機能インターフェース
エンドポイントのロックの状態を取得または設定します	Alexa.LockController

温度の制御および照会に関するメッセージ

このインターフェースには、デバイスの温度を取得および設定するためのメッセージが含まれます。詳細については、サーモスタット用のスマートホームスキルを作成するを参照してください。

操作	機能インターフェース
温度の値やサーモスタットのモードを設定するなど、サーモスタットを制御します	Alexa.ThermostatController
エンドポイントの現在の温度をレポートします	Alexa.TemperatureSensor

パーセンテージに関するメッセージ

このインターフェースには、エンドポイントをパーセンテージ値で設定したり、パーセンテージ値を変更したりするメッセージが含まれます。これらはパーセンテージの汎用メッセージです。できれば、照明にはBrightnessControllerなど、より具体的なメッセージタイプを使用するようにしてください。

操作	機能インターフェース
エンドポイントのパーセンテージを調整します	Alexa.PercentageController

照明および調節可能な照明の制御に関するメッセージ

これらのインターフェースには、照明のオン／オフを切り替えたり、その設定を変更したりするためのメッセージが含まれます。詳細については、照明用のスマートホームスキルを作成するを参照してください。

操作	機能インターフェース
照明のオン／オフを切り替えます	Alexa.PowerController
エンドポイントの電力レベルを設定します	Alexa.PowerLevelController
照明の明るさをパーセンテージで、または値を指定して変更します	Alexa.BrightnessController
照明の色を変更します	Alexa.ColorController
調整可能な照明の白の色調を変更します	Alexa.ColorTemperatureController

スマートカメラに関するメッセージ

このインターフェースには、カメラに対して照会を実行し、ストリームURIを返すメッセージが含まれます。カメラ用のスマートホームスキルを作成するための詳細情報と技術要件については、カメラ用のスマートホームスキルを作成するを参照してください。

操作	機能インターフェース
カメラのフィードを取得します	Alexa.CameraStreamController

エンターテイメントの制御に関するメッセージ

これらのインターフェースには、エンターテイメントデバイスを操作したり、デバイスのチャンネル変更、コンテンツの再生モードの変更、再生音量の調節などのリクエストに応答したりするためのメッセージが含まれます。詳細については、エンターテイメントデバイス用のスマートホームスキルを作成するを参照してください。

操作	機能インターフェース
デバイスのオン／オフを切り替えます	Alexa.PowerController
デバイスのチャンネルを変更します	Alexa.ChannelController
再生デバイスの入力を変更します	Alexa.InputController
早送り、早戻し、一時停止など、デバイスの再生を制御します	Alexa.PlaybackController
ボリュームを段階的に変更します	Alexa.StepSpeaker
ボリュームを特定の範囲のいずれかの値に変更します	Alexa.Speaker

調理器具の制御に関するメッセージ

操作	機能インターフェース
調理を開始または中止する、器具の調理モードを変更します	Alexa.Cooking
時間を指定して調理します	Alexa.Cooking.TimeController
器具のプリセット機能を使用して調理します	Alexa.Cooking.PresetController
調理を一時停止または再開します	Alexa.TimeHoldController

エラーメッセージ

さまざまな種類のエラーが発生する可能性があります。

インターフェースに固有のエラーを定義できますが、ほとんどの種類のエラーメッセージは、ErrorResponseイベントで記述されています。

特記されていない限り、エラーメッセージは機器の検出には使用されません。したがって、検出ディレクティブに対する応答としてエラーメッセージが返されることはありません。

操作	イベント
Alexaにエラーを返します	Alexa.ErrorResponse