スマートホームスキルAPIのメッセージリファレンス
スマートデバイスでやり取りされるメッセージの基本フローと形式は共通しています。Alexaはディレクティブと呼ばれるリクエストメッセージを送信し、スキルは同期的または非同期的なイベントで応答します。
スマートデバイス用のスキルは、照明やドアロックなどそれぞれの機能でサポートされるディレクティブ、イベント、プロパティを表す機能インターフェースを実装しています。
このトピックでは、基本的なメッセージの形式と、機能領域ごとの機能について説明します。
メッセージのフロー
Alexaは、ユーザーに代わって何かをリクエストするディレクティブをスキルに送信します。開発者は、イベントでディレクティブに応答するコードを提供します。コードはAWS Lambda(アマゾンウェブサービスによって提供されるサービス)のLambda関数としてホスティングされます。ディレクティブに対しては、以下の方法で応答できます。
- 8秒以内に、Lambda関数からAlexa.Responseイベントまたはエラーメッセージイベントで同期的に応答します。
- 8秒以内に、Alexaイベントゲートウェイに対してAlexa.Responseイベントまたはエラーメッセージイベントで非同期的に応答します。非同期的な応答は、一部のインターフェースではサポートされていません。詳細はインターフェースの個別のトピックを参照してください。
または
- 時間がかかる操作の場合は、Alexa.DeferredResponseイベントで同期的に応答し、後からAlexaイベントゲートウェイに対してAlexa.Responseイベントまたはエラーメッセージイベントで非同期的に応答します。Alexa.DeferredResponseは現在、LockControllerインターフェースでサポートされています。
ディレクティブとイベントの形式
スキルに送信されるディレクティブとスキルからAlexaに返されるイベントは、同じ基本構造を共有しています。
したがって、ディレクティブとイベントには、以下の上位レベルのオブジェクトが含まれます。
さらに、イベントには以下のオブジェクトが含まれる場合があります。
Headerオブジェクト
ヘッダーに含まれるフィールドは、すべての種類のメッセージに共通です。これらのフィールドでは、さまざまな種類の識別情報を提供します。以下は、一般的なメッセージヘッダーの例です。
"header": {
"namespace": "Alexa.PowerController",
"name": "TurnOn",
"messageId": "6d6d6e14-8aee-473e-8c24-0d31ff9c17a2",
"correlationToken": "abcdef-123456",
"payloadVersion": "3"
}
ヘッダーには以下のプロパティを含めることができます。
プロパティ | 説明 |
---|---|
namespace
|
メッセージペイロードのカテゴリーを表す文字列です。そのディレクティブが含まれる機能インターフェースと同じものを使用します。例:
|
name
|
TurnOn 、TurnOff など、ディレクティブの名前です。 |
|
1つのリクエストまたは応答の一意の識別子です。この情報はトラッキングに使用されます。スキルのログに記録しますが、ビジネスロジックのサポートには使用しません。すべてのメッセージのこのフィールドに値が含まれている必要があります。有効な値は、英数字とダッシュで構成される128文字未満の文字列ですが、ランダムな数値から生成されるバージョン4のUUIDが推奨されます。 |
|
ディレクティブとそれに関連付けられた1つまたは複数のイベントを識別するトークンです。以下の種類のメッセージに相関トークンが含まれます。
|
payloadVersion
|
このメッセージに適用される機能インターフェースのバージョンです。 |
Endpointオブジェクト
Endpointオブジェクトは、ディレクティブのターゲットとイベントの発生元を表します。エンドポイントは次のいずれかになります。
- 物理デバイス
- 仮想デバイス
- デバイスのグループまたは集合
- ソフトウェアコンポーネント
さらに、エンドポイントオブジェクトには認証トークンが含まれます。
- ディレクティブでは、このトークンを使うと、エンドポイントが指定するデバイスまたはコンポーネントとの通信が可能になります。
- イベントでは、Alexaイベントゲートウェイに送信されるイベントにのみトークンが必要です。
以下は、JSONで記述した一般的なメッセージのエンドポイントの例です。
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "Alexa-access-token"
},
"endpointId": "ターゲットエンドポイントのIDです",
"cookie": {
"key1": "何らかの情報",
"key": "検出中に受け取ったペアの値"
}
},
エンドポイントオブジェクトには以下のプロパティが含まれます。
プロパティ | 説明 |
---|---|
|
メッセージ交換の認証付与に関する設定を記述する、ポリモーフィズムなオブジェクトです。詳細については、Scopeオブジェクトを参照してください。 |
|
一意のIDです。この識別子は、スキルのドメイン内であるユーザーが所有するすべてのエンドポイントで一意である必要があります。デバイスの検出中に最初に提供され、このユーザーに関連付けられたデバイスを識別する際に、共通で使用される必要があります。 |
|
エンドポイントに関連付けられたキー/値ペアのリストです。これらは検出中に提供され、エンドポイントの各メッセージで送信されます。 |
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 |