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



スマートホームスキル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 メッセージペイロードのカテゴリーを表す文字列です。そのディレクティブが含まれる機能インターフェースと同じものを使用します。例：
  • 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
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment