スマートホームスキル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"
}

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

Endpointオブジェクト

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

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

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

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

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

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

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

Scopeオブジェクト

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

BearerTokenスコープ

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

BearerTokenの例

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

BearerTokenWithPartitionスコープ

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

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
    }
  ]
}

Payloadオブジェクト

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

検出に関するメッセージ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

エラーメッセージ

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

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

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