?
サポート

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

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

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

スマートホームスキルは、照明やロックなどそれぞれの機能のカテゴリーに対してサポートされるディレクティブイベントおよびレポート可能なプロパティを定義したインターフェースを実装しています。

このトピックでは、基本的なメッセージの形式を説明し、機能カテゴリーごとの機能をリストします。

メッセージフロー

Alexaは、ユーザーの発話に応じて操作要求(ディレクティブ)をスキルに送信します。スキルはディレクティブを受け取り、処理し、応答をイベントとして返します。ディレクティブを受け取るコードは、AWS Lambda(Amazon Web Servicesにより提供されるサービス)でLambda関数としてホスティングされたものです。イベントによるディレクティブへの応答には、次の方法があります。

  • 8秒以内に、Lambda関数からAlexa.Responseイベントかエラーメッセージイベントで同期的に応答する。
  • 8秒以内に、Alexaイベントゲートウェイに対してAlexa.Responseイベントかエラーメッセージイベントで非同期的に応答する。非同期応答はすべてのインターフェースでサポートされているわけではないことに注意してください。詳細は各インターフェースのトピックを参照してください。

または

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

スキルに送信されるディレクティブと、スキルからAlexaに送り返すイベントは、どちらも基本的に同じ構造を取っています。

ディレクティブとイベントはどちらも、次の最上位オブジェクトを持っています。

これらに加えて、イベントに次のオブジェクトを含めることができます。

Headerオブジェクト

ヘッダーには、すべてのメッセージタイプで同一の想定されるフィールドのセットが含まれます。各フィールドは、さまざまな種類の識別情報を提供します。典型的なメッセージヘッダーの例を次に示します。

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

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

プロパティ 説明
namespace メッセージペイロードのカテゴリーを示す文字列です。これは、そのディレクティブを含む機能のインターフェースと一致します。例:
  • Alexa.PowerController
  • Alexa.ThermostatController
name ディレクティブの名前。たとえば、TurnOnTurnOff

messageId

1つのリクエストまたは応答の固有の識別子。この情報は、追跡の目的で使用され、スキルはこれを記録すべきですが、この情報基にビジネスロジックを構築するのは適切ではありません。すべてのメッセージで、このフィールドに値が与えられていなければなりません。128文字以内の英数字の文字列とダッシュで構成されていれば有効ですが、バージョン4のUUID(ランダムな数値から生成されたUUID)が推奨されます。

correlationToken

ディレクティブと、それに関連付けられた1つか複数のイベントを識別するトークン。correlationトークンは、次の種類のメッセージに含まれます。
  • Alexaからスキルへのディレクティブ。
  • ディレクティブに応答するイベント。
ディレクティブリクエストに対する応答イベントには、同じ correlation トークンが含まれている必要があります。イベントがAlexaからのリクエストへの応答でない場合は、correlation トークンを含めてはなりません。
payloadVersion このメッセージに適用される機能のインターフェースのバージョン。

Endpointオブジェクト

endopointオブジェクトは、ディレクティブのターゲットとイベントの発生源を識別します。エンドポイントは次のうちのいずれかを表すことができます。

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

さらに、endpoint には認証トークンが含まれます。

  • ディレクティブの場合、このトークンによってエンドポイントが示すデバイスまたはコンポーネントが特定されます。
  • イベントの場合、Alexaイベントゲートウェイに送信されるイベントに対してのみ、トークンが必要です。

典型的なメッセージエンドポイントに対するJSONの例を次に示します。

 "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "Alexa-access-token"
      },
      "endpointId": "the identifier of the target endpoint",
      "cookie": {
         "key1": "some information",
         "key": "value pairs received during discovery"
      }
    },

Endpointオブジェクトには、次のようなプロパティが含まれます。

プロパティ 説明

scope

メッセージ交換に対して付与された認証のための情報を記述したポリモーフィックなオブジェクト。詳細については、Scopeオブジェクトを参照してください。

endpointId

固有ID。この識別子は、該当スキルの範疇においてユーザーが持つすべてのエンドポイントに対してユニークである必要があります。この識別子は、最初はデバイスの検出時に提供されたもので、このユーザーに関連付けられたこのデバイスを一貫して識別するものである必要があります。

cookie

エンドポイントに関連付けられたキー/値ペアのリスト。これらは検出時に提供され、エンドポイントに送信される各メッセージ内に含められます。

Scopeオブジェクト

Scopeは、このメッセージに認証情報と識別情報を提供する、ポリモーフィックなオブジェクトです。Scopeにはtypeフィールドがあり、種類に応じて異なる追加のキー/値ペアがあります。現在サポートされている種類を次の表に示します。

Scopeのtype 説明 関連付けられたフィールドと説明
BearerToken リンクされたユーザーのアカウントにアクセスするため、またはAlexaのユーザーを識別するためのOAuth ベアラートークンを提供します。 token形式は次のとおりです:
"token" : "tokenvalue"
  • ディレクティブメッセージでは、アカウントリンキングの結果としてシステム内でユーザーを識別するトークンがscopeに含まれています。詳細については、アカウントリンキングによりAlexaユーザーをシステムに認証するを参照してください。
  • イベントメッセージでは、お客様をAlexaに識別させるトークンがscopeに含まれることがあります(オプション)。これは、Login with Amazon(LWA)による権限プロセスで取得できます。このトークンは、Alexaイベントゲートウェイへのメッセージに必要です。詳細については、「Permissionsを設定してAlexaへのユーザー認証を実現する」を参照してください。

Contextオブジェクト

Contextオブジェクトは、任意のイベントメッセージでエンドポイントの状態をレポートするために使用します。コンテキストには、レポート可能なプロパティのオブジェクトとその状態の配列が含まれています。コンテキストを含めた応答イベントを送信するときは、レポートする値に、ディレクティブを処理した後の副次効果をすべて組み込む必要があります。言い換えると、レポートするプロパティ値は、ディレクティブの処理に伴って値が変更されるすべての副次効果を適用した後の値にする必要があります。

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

Alexa.ThermostatControllerインターフェースを実装したエンドポイントに対するContextの例を次に示します。


"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ミリ秒です。

ペイロード

メッセージのペイロードは、メッセージの種類によって異なります。次のいくつかのセクションで、機能分野ごとのメッセージを説明します。

Discoveryメッセージ

このインターフェースは、デバイスと、このスキルアダプターが使用できる機能を識別するためのメッセージを記述します。

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

状態と変更レポートのメッセージ

これらのメッセージは、インターフェースのプロパティの状態をAlexaがリクエストするか、Alexaからの状態リクエストをし、デバイス制御クラウドがそれに応答するか、デバイス制御クラウドから変更レポートを通知するか、機器操作に対する応答をイベントゲートウェイに遅れて到着することを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

エラーメッセージ

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

インターフェースに対して特有のエラーを定義することもできますが、ほとんどのエラーメッセージの種類はErrorResponseイベントに含まれています。

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

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