スマートホームスキルのコードを実装する

スマートホームスキルのコードを実装する

スマートホームスキルのコードは、アマゾン ウェブ サービス（AWS）のLambda関数として実装し、その関数をスキルIDに接続します。この関数は、スキルコード、設定情報、Identity and Access Management（IAM）ロールで構成されます。IAMロールは、ユーザーに代わってスキルコードを実行する許可をLambdaに与えます。コードは、AWS Lambdaコンソールで直接作成することも、スキルのコード作成に使用するプログラミング言語に最適な開発環境で作成することもできます。Lambda関数は、Node.js、Java、Python、C#、Go、Ruby、PowerShellで作成できます。Lambda関数では、オプションでデータをAWS DynamoDBに保存したり、ログをAWS CloudWatchに書き込んだりできます。

簡単なスマートホームスキルを作成するステップバイステップのチュートリアルについては、チュートリアル： スマートホームスキルの作成を参照してください。

ベストプラクティス

Lambda関数にコードを追加する前に、スマートホームスキルを実装する際の以下のベストプラクティスを確認してください。

  • スマートホームデバイスの制御に適したスマートホームスキルAPIを確認します。検出応答でサポートされているすべての機能を宣言します。
  • 各インターフェースの適切なバージョンを宣言します。多くのAlexaインターフェースはバージョン3であり、バージョン3.0ではありません。
  • すべての応答メッセージとイベントメッセージで、messageIdを一意の識別子、できればバージョン4 UUIDに設定します。
  • デバイスの最新の状態をAlexaに通知するには、検出の応答で、機能のプロパティをretrievableおよびproactivelyReportedと設定します。詳細については、Alexa.Discoveryを参照してください。
  • 検出応答のadditionalAttributesオブジェクトにmanufacturerとmodelを追加します。Alexaが一意のデバイスを識別できるよう、できるだけ多くのアトリビュートを追加してください。
  • Alexaにデバイスの健全性を通知する場合、EndpointHealthを実装すること。EndpointHealthプロパティはできる限り多くサポートしてください。
  • 制御ディレクティブへのすべての応答でデバイスの状態をレポートします。詳細については、ディレクティブの応答で状態をレポートするを参照してください。
  • デバイスの状態が変更された場合、その理由にかかわらずAlexa.ChangeReportイベントを送信することで、デバイスの状態をプロアクティブにAlexaに知らせます。詳細については、ChangeReportで状態をレポートするを参照してください。状態の変更から3秒以内にレポートを送信します。Alexa.EndpointHealthインターフェースで定義されるconnectivityプロパティの現在値も含めます。
  • デバイスに、設定用のモバイルアプリがある場合は、アプリからAlexaアプリへのアカウントリンクを実装します。アプリは、iOS、Androidの両方をサポートする必要があります。詳細については、アプリ間アカウントリンクを参照してください。

Lambda関数を作成する

Lambda関数を作成するには、AWS認証情報を使用してAWSマネジメントコンソールにサインインし、以下の手順を実行します。Lambda基本実行ポリシーがアタッチされたIAMロールが既にある場合は、最後のステップに進んでください。

IAMロールとLambda関数を作成するステップバイステップのチュートリアルについては、スマートホームチュートリアルのステップ2： スキルコードを実装するを参照してください。

Lambda関数を作成するには

  1. AWSマネジメントコンソールにサインインします。
  2. IAMポリシーを作成します。
    IAMダッシュボードのポリシーページに移動し、ポリシーの作成をクリックします。Lambda関数からアクセスするAWSリソースへのアクセス権限を追加します。
  3. IAMロールを作成します。
    IAMダッシュボードのロールページに移動し、ロールを作成をクリックします。信頼されたエンティティタイプでAWSのサービスを選択し、一般的なユースケースでLambdaを選択します。先ほど作成したポリシーをロールに追加します。
  4. Lambda関数を作成します。
    Lambdaコンソールに移動し、Lambda関数を実行する適切なリージョンを選択します。スキルを提供するのと同じリージョンで関数を作成します。後からほかの言語とリージョンを追加できます。
    • ランタイムで、使用するプログラミング言語を選択します。
    • アーキテクチャはデフォルトのままにします。
    • アクセス権限＞デフォルトの実行ロールの変更で、既存のロールを使用するを選択し、先ほど作成したIAMロールを選択します。
    • トリガーを追加で、Alexa Smart Homeを選択します。
    • アプリケーションIDにスキルIDを貼り付けます。
    • Lambda関数のARNをコピーするには、Lambda＞関数＞my-smart-home-skillページの上部にあるARNをコピーを選択します。サービスエンドポイントを設定するときに、このARNをリージョンごとに追加する必要があります。Alexaは、ARNを使用して関数にアクセスします。

AWS Lambdaリージョン

以下の表は、スキルをデプロイできるAlexaリージョンと、それぞれで使用する必要のあるAWS Lambdaリージョンを示しています。Lambda関数は適切なリージョンで作成してください。

スキルの言語とロケール AWS Lambdaのリージョン Alexaエンドポイントのリージョン
アラビア語（SA）、英語（CA）、英語（US）、フランス語（CA）、ポルトガル語（BR）、スペイン語（MX）、スペイン語（US） 米国東部（バージニア北部） 北米
アラビア語（SA）、英語（IN）、英語（UK）、フランス語（FR）、ドイツ語（DE）、ヒンディー語（IN）、イタリア語（IT）、スペイン語（ES） 欧州（アイルランド） ヨーロッパ、インド
英語（AU）、日本語 米国西部（オレゴン） 極東、オーストラリア

Lambda関数にコードを追加する

Alexaは、ユーザーの発話を特定のJSON構造を持つディレクティブに変換します。次に、このディレクティブをスキルに送信します。スキルのLambdaコードがディレクティブを処理し、クラウド経由でデバイスと通信して、リクエストされたアクションを実行します。スキルコードは、リクエストの成功または失敗を示す応答をAlexaに返します。応答には、デバイスの現在の状態が含まれます。

スキルコードの作成には、Lambda関数でサポートされている言語（ Node.js、Java、Python、C#、Go、Ruby、PowerShellのいずれか）を使用できます。非コンパイル型のプログラミング言語（PythonやNode.jsなど）の場合は、Lambdaコンソールのコードエディターでコードを記述できます。また、スキルの実装に使用するプログラミング言語に適した開発環境を使用することもできます。別の開発環境でコードを記述する場合は、そのコードをコピーしてLambdaコンソールのエディターに貼り付けるか、コードをzipファイルまたはjarファイルとしてアップロードします。詳細については、Lambdaの開始方法を参照してください。

スキルユーザーに最良のエクスペリエンスを提供するために、スキルコードでは次の機能をサポートする必要があります。

  • 検出 - ユーザーのAlexaアカウントに関連付けられたデバイスエンドポイントを識別します。
  • 機能ディレクティブ - デバイスを制御するディレクティブに応答します。
  • 状態レポート - デバイスの最新の状態をAlexaに通知します。
  • 非同期イベントの送信 - 非同期応答と状態変更を送信するために、Alexaイベントゲートウェイへのアクセスをリクエストします。

以下の図は、Alexaアプリ、Alexaサービス、スキルを使用するユーザーとデバイス間の最も一般的な通信フローを示しています。この例では、AlexaアプリのみのアカウントリンクのAuthorization code grantフローを使用します。詳細については、スキルを有効にする際のフローを参照してください。

クリックで拡大表示
  1. ユーザーがAlexaアプリでスキルを有効にします。
  2. Alexaサービスは、デバイス制御クラウドの認可サーバーのログインページにユーザーをリダイレクトして、アカウントリンクフローを開始します。アカウントリンクフロー全体は図に示されていません。
  3. 成功すると、システム内のユーザーアカウントにアクセスするためのアクセストークン（黒字で表示）をAlexaサービスが受け取ります。Alexaは、スキルに送信する後続のディレクティブにこのトークンを含めます。
    アカウントリンクが完了します。
  4. Alexaサービスは、スキルにAlexa.Authorization.AcceptGrantディレクティブを送信して、Alexaイベントゲートウェイの認可フローを開始します。スキルはこれに応答して、スキルとAmazon LWA認可サーバーとの間でAuthorization code grantフローを開始します。スキルは、Amazonユーザーのアクセストークン（青字で表示）を取得し、スキルのバックエンドに保存します。このトークンは、Alexaイベントゲートウェイにイベントを送信するときに必要になります。
  5. ユーザーが、スキルでユーザーのデバイスを検出するようにリクエストします。
  6. Alexaサービスは、スキルにAlexa.Discovery.Discoverディレクティブを送信して、ユーザーのデバイスアカウントに関連付けられているエンドポイントを識別します。スキルは各エンドポイントについて、デバイスのエンドポイント情報とエンドポイントの機能をDiscover.Responseに含めます。
  7. Alexaサービスは、Alexa.ReportStateディレクティブを送信してデバイスの現在の状態をリクエストします。
    スキルはキャッシュされた状態データで応答します。スキルがデバイスに照会する場合もあります。
  8. ユーザーがAlexaアプリでデバイスの電源をオンにします。
  9. Alexaは、スキルにAlexa.PowerController.TurnOnディレクティブを送信します。スキルは、デバイス制御クラウドでAPIを呼び出すか、デバイス上で直接APIを呼び出して、デバイスの電源をオンにします。
  10. ユーザーが手動でデバイスの電源をオフにします。デバイスはスキルに通知を送信します。
  11. これに対応して、スキルはAlexaサービスにAlexa.ChangeReportを送信し、状態の変更をAlexaに通知します。Alexaサービスは、Alexaアプリのデバイスの状態を更新します。

検出を実装する

検出を実装して、Alexaにユーザーのコネクテッドデバイスの機能について通知します。詳細については、Alexa検出についてを参照してください。

検出応答には、ユーザーのデバイスアカウントに関連付けられている各エンドポイントの識別情報と機能を含めます。使用できるAlexa機能インターフェースについては、Alexaインターフェースとサポートしている言語の一覧を参照してください。機能インターフェースごとに、retrievableプロパティとproactivelyReportedプロパティをtrueに設定して、状態レポートのサポートを示します。デバイスで正常性の問題が発生した場合にAlexaがユーザーに通知できるように、必ずAlexa.EndpointHealthのサポートを含めてください。Alexa.EndpointHealthを使用して、OKまたはUNREACHABLEのいずれかのデバイス接続ステータスをAlexaにレポートします。バッテリーの健全性など、健全性状態をレポートすることもできます。また、すべてのエンドポイントにAlexaインターフェースを含める必要もあります。

検出応答の例については、サポートする各インターフェースのドキュメントを参照してください。

機能ディレクティブを実装する

検出応答に含めたエンドポイントの各機能には、デバイスを制御するユーザーリクエストに応答して、Alexaからディレクティブが送信されることがあります。ディレクティブに迅速に応答し、すべてのデバイス機能の状態を応答に含める必要があります。ディレクティブの詳細については、Alexaスキルでサポートする各インターフェースのドキュメントを参照してください。

状態レポートを実装する

デバイスの現在の状態をAlexaが把握できるように、状態レポートを実装します。状態レポートの詳細については、状態および変更レポートについてを参照してください。

Alexaに状態をレポートする方法は3つあります。

  • AlexaがAlexa.ReportStateディレクティブを使って状態をリクエストします。すべてのプロパティ値のスナップショットを含むAlexa.StateReport応答を返します。
  • ディレクティブのAlexa.Responseですべてのプロパティの状態をプロアクティブに送信します。たとえば、TurnOnディレクティブにすべてのプロパティ値のスナップショットを含めることができます。
  • 非同期のAlexa.ChangeReportイベントをプロアクティブに送信して、1つ以上の出力可能なプロパティが変更されたことを知らせます。イベントには、その他すべてのプロパティ値のスナップショットを含めることもできます。

非同期のイベントを実装する

Alexa.ChangeReportイベントと、非同期のAlexa.Responseイベントを、デバイス制御クラウドまたはLambda関数からAlexaイベントゲートウェイに直接送信します。さらに、インターフェースによっては、イベントゲートウェイに送信するその他のイベントを定義しているものがあります。

このメッセージフローでは、Alexa開発者コンソールでイベントを有効にし、各ユーザーのアクセストークンを取得する必要があります。コードで非同期イベントを有効にする詳細な手順については、Alexaイベントゲートウェイにイベントを送信するを参照してください。

サービスエンドポイントを設定する

AlexaとLambda関数の間のリンクを確立するには、Alexa開発者コンソールのスキル設定でLambdaのARNを指定します。サービスエンドポイントは、スキルの言語とリージョンに基づいて設定します。

  • スキルでサポートする言語とリージョンが1つだけの場合は、デフォルトのARNと選択したリージョンのARNに同じARNを指定します。
  • スキルが複数の言語とリージョンをサポートする場合は、リージョンごとにARNを指定する必要があります。リージョンARNの1つをデフォルトARNとして指定します。

Alexa開発者コンソールでサービスエンドポイントを設定するには

  1. Alexa開発者コンソールのスキルに戻ります。
  2. スマートホームページの2.スマートホームのサービスエンドポイントで、デフォルトのエンドポイントにLambda関数のデフォルトのARNを貼り付けます。
  3. 対象となるユーザーに最も近い地域を選択し、その地域のエンドポイントを設定しますで、Lambda関数を提供するリージョンを選択し、リージョンARNを貼り付けます。
  4. 保存をクリックします。

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

最終更新日: 2023 年 02 月 14 日