Alexaイベントゲートウェイにイベントを送信する

Alexaイベントゲートウェイにイベントを送信する

Alexaにプロアクティブイベントを送信する、または前のディレクティブに対する非同期応答を送信するには、デバイス制御クラウドからAlexaイベントゲートウェイにイベントを送信します。Alexa.ChangeReportイベントは、スキルがAlexaイベントゲートウェイに送信する最も一般的なプロアクティブイベントです。

ユーザーアカウントでスマートホームスキルを認証し、Alexaゲートウェイに非同期イベントを送信するには、以下のガイドラインに従ってください。

前提条件

非同期イベントを送信するには、スマートホームスキルが以下の前提条件を満たす必要があります。

  • スマートホームスキルのアカウントリンクを設定します。
  • Alexa.ChangeReportイベントを送信するには、Alexaにレポートするインターフェースのプロパティ検出応答でproactivelyReportedをtrueに設定します。

イベントゲートウェイのアクセスフロー

ユーザーがAlexaアプリでスマートホームスキルを有効にすると、AlexaサービスがOAuth 2.0プロバイダーを使用してアカウントリンクフローを呼び出します。ここで、Alexaサービスはシステム内のユーザーアカウントへのアクセストークンを取得します。Alexaイベントゲートウェイにイベントを送信するために、2回目のOAuth交換が実行されます。スキルは、このAmazon OAuthサーバーとのOAuth交換を実装する必要があります。

Alexaサービスは、スキルにAlexa.Authorization.AcceptGrantディレクティブを送信して、Alexaイベントゲートウェイの認可フローを開始します。スキルはこれに応答して、スキルとLogin with Amazon（LWA）OAuthサーバーとの間でAuthorization code grantフローを開始します。Alexaユーザーのアクセストークンを安全な場所に格納します。後でユーザーに代わってイベントや非同期応答をAlexaイベントゲートウェイに送信するときに、そのアクセストークンを含めます。Alexaは、そのトークンを使用してAlexaユーザーを識別します。

次の図は、Alexaゲートウェイにイベントを送信するためにスキルが実装する通信フローを示しています。アカウントリンクは示されていません。この例の図にはChangeReportイベントが示されていますが、どの非同期イベントにも同じフローを使用できます。

AcceptGrantディレクティブ、Authorization code grant、およびChangeReportのメッセージフロー。
クリックで拡大表示

Alexaにイベントを送信する手順

スキルがユーザーに代わってイベントや非同期応答をAlexaイベントゲートウェイに送信できるようにするには、次の手順に従います。

  1. Alexa開発者コンソールで権限を設定します。
  2. スキルにコードを追加して、スキル内のAlexaイベントゲートウェイへのアクセス権限をリクエストします。
  3. Alexaイベントゲートウェイにイベントを送信するコードを追加します。

ベストプラクティス

イベントや非同期応答を送信するには、次のベストプラクティスに従います。

  • スキルを提供するリージョンごとにLambda関数を指定します。開発者コンソールのビルドページで、スキルを提供するリージョンごとに特定の地理的エンドポイントを設定します。詳細については、Lambda関数を複数のリージョンにデプロイするを参照してください。
  • リージョンごとにユーザーの認証情報を取得して格納します。リージョン固有のLambda関数でAuthorization code grantフローを実装します。リージョン固有のLambda関数がアクセスできるように、アクセストークンを格納します。
  • そのリージョンのユーザーに代わって、Lambda関数と同じリージョンのAlexaイベントゲートウェイエンドポイントにイベントを送信します。
  • 認証トークンを安全な方法で格納して送信するために、OAuth 2.0のベストプラクティスに従ってください。
  • 認可コードをアクセストークンおよび更新トークンとすぐに交換します。認可コードには有効期限（数分間）があります。認証コードの有効期限が切れた後、ユーザーはスキルを無効にしてから再度有効にする必要があります。スキルを再度有効にすると、新しい認証コードが生成され、AlexaがスキルにAlexa.Authorization.AcceptGrantディレクティブを送信します。
  • ユーザーのアクセストークンと更新トークンを格納しておき、非同期応答またはイベントをAlexaイベントゲートウェイに送信するたびにそのアクセストークンを含める必要があります。これらのトークンの有効期限が切れる前に、格納しておいた更新トークンを使用して新しいアクセストークンと更新トークンをLWAから取得してください。アクセストークンの有効期限は通常60分です。
  • スマートホームスキルAPI v2メッセージ形式からv3メッセージ形式にスキルを移行し、Alexaイベントゲートウェイにイベントを送信する権限をリクエストした場合、Alexaでバックフィルプロセスが発生します。Alexaは、スキルを有効にしたすべてのユーザーに対してAlexa.Authorization.AcceptGrantディレクティブを送信します。これらのメッセージを受け取る準備をし、認証プロセスを完了してください。スキル移行の詳細については、Smart Home Skill v2-to-v3 Migration Guideを参照してください。

テストツール

Alexa Skills Kit（ASK）には、Alexaスマートホームスキルを開発する際に、状態やその他のイベントのテストとデバッグを行うためのさまざまなツールが用意されています。詳細については、スマートホームスキルのデバッグを参照してください。

サンプルコード

次のサンプルコードでは、変更レポートをAlexaイベントゲートウェイに送信するようにスマートホームスキルを設定する方法を示しています。

このページは役に立ちましたか？

最終更新日: 2024 年 12 月 17 日