あなたのAlexaコンソール
?
サポート

スマートホームスキルの作成手順

スマートホームスキルの作成手順

このトピックでは、ディレクティブに同期的に応答するスマートホームスキルを作成する手順について取り上げます。開発者ポータルでのスキルの作成、AWS Lambda関数の作成、スキルの構成とテスト、認証の申請を行うための手順について、段階的に説明します。

Amazon開発者ポータルに登録してスキルを作成する

新しいスマートホームスキルを構成するには、Amazon開発者ポータルのアカウントが必要です。アカウントを持っていない場合は、https://developer.amazon.com/login.htmlにアクセスしてアカウントを新規作成してください。登録は無料です。登録が完了したら、次の手順を実行します。

  1. ブラウザでAmazon開発者ポータルを開き、ログインします。
  2. 一番上のナビゲーションバーでAlexaを選択してAlexaセクションを開きます。
  3. Alexa Skills Kit」ボックスの「概要」をクリックします。
  4. Add a New Skill」ボタンをクリックします。
  5. Skill Information」ページで「Smart Home Skill API」を選択し、「Name」にスキルの名前を入力します。スキル名には、機能限定版であることを表す語句を使用しないでください。たとえば、「basic」(ベーシック)、「reduced」(機能限定版)、「simple」(簡易版)といった言葉は使用しないでください。
  6. スキルの言語を選択します。後で他の言語を追加することもできます。スキルに別の言語を追加する方法について詳しくは、「スマートホームスキルを複数の言語で開発する」を参照してください。
  7. Payload Version」でv3を選択します。v2をターゲットのスキルは現在非推奨です。
  8. Save」をクリックし、スキルのアプリケーション IDをクリップボードにコピーします。アプリケーションIDは次のような形式です。amzn1.ask.skill.1a2b55555-c325-1234-d56e-1f234d5e6a78

Lambda関数を追加する

AWSのアカウントと、ある程度のAWSの基礎知識が必要です。スマートホームスキルのコードはAWS上でLambda関数としてホストされます。AWS Lambdaは、サーバーを管理することなくクラウドでコードを実行できるサービスです。Alexaがスキルリクエストを送信し、コードがそのリクエストを検証して、必要なアクション(対象のお客様のデバイス制御クラウドとの通信など)を実行し、応答を返します。

開始するには、AWSアカウントにサインインします。

Lambda用のIAMロールを作成する

Lambdaを使用して初めて作業する場合には、基本的な操作を実行できるようにするIDとアクセス管理(IAM)ロールを作成する必要があります。IAMロールを作成するには、IAMコンソールに移動します。Lambdaの基本的な操作を行えるロールが既にある場合には、次のセクションにスキップします。

  1. Roles」を選択し、「Create a new role」をクリックします。
  2. AWS Service Role」で「AWS Lambda」を選択します。
  3. フィルターボックスに「basic」と入力してAWSLambdaBasicExecutionRoleを選択し、「次のステップ」をクリックします。
  4. このロールを識別する名前を入力して、「Create role」をクリックします。

Lambda関数を作成して追加する

  1. AWSコンソールの「Compute」で、「Lambda」を選択します。
  2. リージョンを選択します。日本語対応のスキルではOregonリージョンを、英語(米国)のスキルではN.Virginiaリージョンを、英語(英国)、英語(インド)、ドイツ語のスキルではEU(Ireland)リージョンを選択します。リージョンは右上隅に表示されます。正しいリージョンにLambda関数を提供することで、レイテンシーの問題を防ぐことができます。
  3. Create a Lambda function」をクリックします。
  4. Select blueprint」ページのフィルターボックスに「home」と入力します。「alexa-smart-home-skill-adapter」を選択します。
  5. Configure triggers」ページでは、既に「Alexa Smart Home」トリガーが指定されています。開発ポータルのアプリケーションIDを追加します。
  6. トリガーの有効化」をオンします。オンにすることで、Amazon Alexaサービスから作成したLambda関数を呼び出せるようになります。
  7. 基本的な情報 」で、以下の情報を入力します。
    • 名前」:作成するLambda関数の名前です。この名前は、AWSコンソールに表示され、AWSコマンドラインインターフェース(CLI)ListFunctions APIからも返されます。そのため、自分が作成するすべてのLambda関数の中で一意の名前でなければなりません。
    • ロール」: 作成済みのロールを選択するか、Lambdaの基本的な実行ポリシーがアタッチされたロールを選択します。
  8. [関数の作成]をクリックします。
  9. 関数コード」の「コードエントリタイプ」は「コードをインラインで編集」を選択します。
  10. 関数コード」の「ランタイム」は、Node.js 6.10を選択するか、作成する予定のコードのランタイムを選択します。サポートされている言語は次のとおりです。Node.js、Java、Python、C#。
  11. 次のコードに貼り付けます。このコードは、スマートホームスキルの実装の開始点となり、検出と制御リクエストに対する応答用の基本的な構造を示しています。ご使用のデバイスでサポートされているデバイスタイプとインターフェース用のコードを追加する必要があります。その他のサンプルコードは、AlexaスマートホームのGitHubリポジトリにあります。
exports.handler = function (request, context) {
    if (request.directive.header.namespace === 'Alexa.Discovery' && request.directive.header.name === 'Discover') {
        log("DEGUG:", "Discover request",  JSON.stringify(request));
        handleDiscovery(request, context, "");
    }
    else if (request.directive.header.namespace === 'Alexa.PowerController') {
        if (request.directive.header.name === 'TurnOn' || request.directive.header.name === 'TurnOff') {
            log("DEBUG:", "TurnOn or TurnOff Request", JSON.stringify(request));
            handlePowerControl(request, context);
        }
    }

    function handleDiscovery(request, context) {
        var payload = {
            "endpoints":
            [
                {
                    "endpointId": "demo_id",
                    "manufacturerName": "Smart Device Company",
                    "friendlyName": "Bedroom Outlet",
                    "description": "Smart Device Switch",
                    "displayCategories": ["SWITCH"],
                    "cookie": {
                        "key1": "arbitrary key/value pairs for skill to reference this endpoint.",
                        "key2": "There can be multiple entries",
                        "key3": "but they should only be used for reference purposes.",
                        "key4": "This is not a suitable place to maintain current endpoint state."
                    },
                    "capabilities":
                    [
                        {
                          "type": "AlexaInterface",
                          "interface": "Alexa",
                          "version": "3"
                        },
                        {
                            "interface": "Alexa.PowerController",
                            "version": "3",
                            "type": "AlexaInterface",
                            "properties": {
                                "supported": [{
                                    "name": "powerState"
                                }],
                                 "retrievable": true
                            }
                        }
                    ]
                }
            ]
        };
        var header = request.directive.header;
        header.name = "Discover.Response";
        log("DEBUG", "Discovery Response: ", JSON.stringify({ header: header, payload: payload }));
        context.succeed({ event: { header: header, payload: payload } });
    }

    function log(message, message1, message2) {
        console.log(message + message1 + message2);
    }

    function handlePowerControl(request, context) {
        // get device ID passed in during discovery
        var requestMethod = request.directive.header.name;
        // get user token pass in request
        var requestToken = request.directive.payload.scope.token;
        var powerResult;

        if (requestMethod === "TurnOn") {

            // Make the call to your device cloud for control 
            // powerResult = stubControlFunctionToYourCloud(endpointId, token, request);
            powerResult = "ON";
        }
       else if (requestMethod === "TurnOff") {
            // Make the call to your device cloud for control and check for success 
            // powerResult = stubControlFunctionToYourCloud(endpointId, token, request);
            powerResult = "OFF";
        }
        var contextResult = {
            "properties": [{
                "namespace": "Alexa.PowerController",
                "name": "powerState",
                "value": powerResult,
                "timeOfSample": "2017-09-03T16:20:50.52Z", //retrieve from result.
                "uncertaintyInMilliseconds": 50
            }]
        };
        var responseHeader = request.directive.header;
        responseHeader.name = "Alexa.Response";
        responseHeader.messageId = responseHeader.messageId + "-R";
        var response = {
            context: contextResult,
            event: {
                header: responseHeader
            },
            payload: {}

        };
        log("DEBUG", "Alexa.PowerController ", JSON.stringify(response));
        context.succeed(response);
    }
};

Lambda関数の構成を完了してテストする

  1. この例では、「ハンドラー」の設定で、ハンドラー名をデフォルト(index.handler)のままにします。関数のハンドラーはLambda関数のメインのエントリーポイントとなります。ハンドラー名は、fileName.entryPointFunctionNameの形式で指定します。このサンプルでは、デフォルトのファイル名がindexで、handler関数がこのコードのエントリーポイントであることを示しています。
  2. 環境変数」やその他設定はデフォルトのままにしておきます。画面上の「保存」をクリックします。
  3. 右上隅に表示されるLambda関数のAmazonリソースネーム(ARN)をコピーし、クリップボードに貼り付けます。この値は、開発者ポータルでスマートホームスキルを構成する際に使用します。ARNは次のような形式の値です。arn:aws:Lambda:us-east-1:012345678901:function:FunctionName。 スキルのターゲットを複数の言語にしている場合、開発者ポータルで「Provide geographical region endpoints」を選択して該当する地域を選び、適切なARN番号を追加します。(詳細はこの後に説明する「ARNを構成する」を参考にしてください)
  • LambdaコードエディターでDiscoveryリクエストの簡単なテストを実行するには、「Test」をクリックします。このとき、「Sample event template」はデフォルトの「Hello World」のままにします。テストエディターで、すべてのコードを以下のコードで上書きします。
{
    "directive": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover",
            "payloadVersion": "3",
            "messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
        },
        "payload": {
            "scope": {
                "type": "BearerToken",
                "token": "some-access-token"
            }
        }
    }
}
  • Save and test」を選択します。テストが正常に実行されると、実行結果は次のようになります。
{
  "event": {
    "header": {
      "correlationToken": "12345692749237492",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "name": "Discover.Response",
      "namespace": "Alexa.Discovery",
      "payloadVersion": "3"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "demo_id",
          "manufacturerName": "Smart Device Company",
          "friendlyName": "Bedroom Outlet",
          "description": "Smart Device Switch",
          "displayCategories": ["SWITCH"],
          "cookie": {
            "key1": "arbitrary key/value pairs for skill to reference this endpoint.",
            "key2": "There can be multiple entries",
            "key3": "but they should only be used for reference purposes.",
            "key4": "This is not a suitable place to maintain current endpoint state."
          },
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            },
            {
              "interface": "Alexa.PowerController",
              "version": "3",
              "type": "AlexaInterface",
              "properties": {
                "supported": [
                  {
                    "name": "powerState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            }
          ]
        }
      ]
    }
  }
}

ARNを構成する

開発者ポータルのスキル構成で、ご使用のLambda関数用のARNを提供する必要があります。

  1. 開発者ポータルの自分のスキルに戻ります。開発中のスキルに戻るには、ログインして、Alexaセクションを開きます。表示されたリストからスキルを選択します。
  2. Interaction model」タブはスキップします。対話モデル、すなわちスマートホームスキルを呼び出すためにユーザーが言うべきフレーズはあらかじめ定義されているため、ここで指定する必要はありません。スマートホームの音声対話モデルの詳細については、各インターフェーストピックに記載されたフレーズを参照してください。
  3. Configuration」ページの「Endpoint」の「Default」ボックスに、作成したLambda関数のARN番号を指定します。スキルを複数言語に対応させる場合、地域毎の固有のエンドポイントを指定する必要があります。次の表に、スキルに選択する言語、リージョンのエンドポイント、Lambda関数のリージョンのマッピングを示します。
スキル言語 エンドポイントリージョン Lambda関数リージョン
英語(米国) North America US East (N. Virginia)
英語(英国)、ドイツ語 Europe EU (Ireland)
英語(インド) India EU (Ireland)
日本 Far East US West (Oregon)
  • スキルが1つの言語/リージョンのみをサポートする場合は、デフォルトのARNと選択したリージョンARNに同じARNを指定します。
  • スキルが複数の言語/リージョンをサポートする場合は、各リージョンにARNを指定する必要があります。デフォルトとしてリージョンARNのいずれかを指定します。

アカウントのリンク情報を提供する

OAuth 2.0プロバイダーとアカウントリンクするための情報を設定する必要があります。アカウントリンクを通して、ユーザーのデバイス制御クラウドアカウントとスマートホームスキルを関連付けることができます。OAuth 2.0プロバイダーとしては、Login with Amazonまたは別のOAuthプロバイダーを使用できます。次の情報を設定する必要があります。

  • OAuthプロバイダー用の認証URL
  • クリエストを識別し、認可サーバーから認可を受けるためのクライアントIDとクライアントシークレット
  • スコープ(OAuthプロバイダーで必要となる場合)

必要なフィールドについての詳細と説明については、システムでAlexaユーザーを認証するを参照してください。

スキルをテストする

スキルの実装と、Lambda関数のテストが完了したら、スマートホームスキルの機能をテストできます。スキルのテストは、Alexa搭載端末またはアプリを使用して行います。前提条件として、デバイス制御クラウド用にアカウントが構成されていること、そのアカウントを検出可能なデバイスがあることが必要です。

  1. スマートホームトリガーが追加され有効になっていることを確認してください。この点を確認するには、Lambdaコンソールに移動して対象のスマートホームスキルを選択し、Alexa Smart Homeトリガーが選択されていることを確かめます。
  2. 開発者アカウントと同じ認証情報で、Alexaアプリ(Android、IOS、ウェブhttps://alexa.amazon.comで利用可能)にサインインします。
  3. Alexaアプリで対象スキルを検索します。そのためには、「スキル」に移動し、「All Skills」ページの右上隅にある「Your Skills」をタップします。スキルのリストで対象スキルを見つけます。
  4. ENABLE」ボタンをクリックしてスキルを有効にします。デバイス制御クラウドアカウントへのスキルのアカウントリンクに誘導されます。アカウントリンクを実行できない場合、デバイス制御クラウドの有効な認証情報を使用していることを確認してください。あるいは、開発者ポータルで指定したアカウントリンク情報に問題がある可能性もあります。この場合のヘルプについては、 開発者フォーラムのAlexa:アカウントリンク情報のデバッグに関する部分を参照してください。後でアカウントリンクを解除するには、「Skills」タブでスキルを無効にします。
  5. ウィンドウを閉じて、Alexaアプリの「DISCOVER DEVICES」ボタンをタップします。
  6. スキルがデバイスを検出しない場合には、Lambda関数のログを確認し、Alexaから Discovery ディレクティブを受信したかどうかを確かめて、問題のトラブルシューティングにログを使用します。一般的な問題として、イベント応答の形式が間違っている場合があります。
  7. スキルがデバイスを正常に検出した場合、検出プロセスで見つかったデバイス名と、スキルがサポートしている発話例を使用してAlexaにコマンドを出します。スキルを有効な発話と無効な発話を使用してテストします。つまり、正常に動作すべき場合、動作できない場合、それぞれをさまざまな条件下でスキルに指示します。また、対象デバイスの電源を切った状態など正常な動作ができない場合についてもテストします。
  8. スマートホームスキルが問題なく動作することを確認したら、ベータ版テストに提出したり、スキルの審査を申請したりできます。

公開情報を提供し、オプションでベータ版テストを実行する

ベータ版テストのためにお客様にスキルを公開したり、スキルの審査を申請したりするには、Alexaアプリで対象のスキルについて記述するための公開情報を提供する必要があります。

  • Skill Information」タブでは、「Language」と「Name」を指定する必要があります。
  • Configuration」タブでは、スキルのLambda関数のエンドポイント(ARN)を指定する必要があります。
  • 公開情報」ページに移動します。このページでリクエストされる情報は、Alexaアプリで対象スキルと一緒に表示されます。詳細な説明と簡単な説明、検査に合格したサンプルフレーズなど、すべての情報を提供します。
  • プライバシーとコンプライアンス」タブの質問すべてに回答しなければなりません。「プライバシーポリシーURL」を指定します。任意で、「利用規約URL」を入力します。これらのフィールドを完成させる方法について詳しくは、スマートホームスキル公開ガイドをご覧ください。

この時点で、「スキルのベータ版テスト」ボタンが有効になり、ベータ版テストを開始するための情報すべてを指定できます。詳細については、スキルのベータ版テストを参照してください。

スキルの審査を申請する

開発者ポータルのすべてのセクションを完成させ、緑色のチェックマークが表示されると、スキルの審査を申請できます。

  1. スキルを申請する前に、ご使用のテスト手順と他の公開情報が公開ガイドのガイドラインに準拠していることを確認してください。
  2. ページ下部にある「Submit for Certification」をクリックします。

ライブのスキルへの変更を申請する

いったんライブになったスキルを変更するには、その都度、審査が必要となります。たとえば、開発者ポータルでスキルの情報を変更したり、AWS Lambda関数を変更したりするには、そのたびにスキルの再審査が必要となります。審査の内容は変更内容によっても異なりますが、Lambda関数も更新された場合、追加の審査が必要になる場合があります。

スキルのステータスがライブに変更されると、新しい開発バージョンが開発者ポータルで自動的に作成されます。開発バージョンには、ライブバージョンと同じ情報が含まれています。スキルの改良や機能の追加を行うには、開発バージョンを使用します。

ライブバージョンと開発バージョンは、どちらも開発者ポータルのスキルリストに表示されます。リスト項目を展開すると、開発バージョンとライブバージョンが両方表示されます。

リスト項目が展開された公開済みスキル
リスト項目が展開された公開済みスキル

更新されたスキルを開発者ポータルに送信する際は、「Testing Instructions」フィールドに変更内容を詳細に説明する変更ログを入力します。

Lambda関数を更新するには

AWS Lambda関数を更新するには、以下の手順を実行します。

  1. 新しいARNでLambda関数を新規作成し、ライブバージョンのLambda関数を新しいLambda関数にコピーします。

  2. 新しいLambda関数に対して更新を行います。ライブバージョンのスキルをサポートするライブバージョンのLambda関数を更新しないようにしてください。また、Lambdaエイリアスやバージョンの更新も避けてください。スキルが更新されると正常動作が保証されなくなるためです。

  3. スキルの開発段階で、新しいLambda ARNを指すようにLambda ARNコンフィギュレーションを更新します。

スキルが再審査されてライブになった後、スキルは新しいLambda ARNを指すようになります。古いLambda関数は削除することもできますし、将来の開発や更新のために使用することもできます。

非同期応答とプロアクティブ状態レポートを実装する

状態レポートと非同期応答を実装することは必須ではありませんが、推奨されています。このセクションを完了するための前提条件として、開発者ポータルで「Provide geographical region endpoints?」オプションを選択し、スキルを提供する各リージョンのLambda ARNを指定する必要があります。これは、ユーザーの地域によって決まるLambda関数のリージョンに基づいてユーザーの認証情報を格納し、使用しなければならないためです。その後、次のステップを実行します。

  • スキルの設定でイベントをAlexaイベントゲートウェイに送信するためのPermissionsの設定を行います。
  • ユーザーがスキルを有効にするとAcceptGrantディレクティブを受信するようになります。認可情報を取得するためのコードを追加します。
  • 格納されたトークンを使用してAlexaイベントゲートウェイにメッセージを送信します。

Permissionsの設定

AlexaイベントをAlexaに送信するための権限をリクエストするには、次のようにします。

  1. 開発者ポータルにサインインし、スキルを選択します。
  2. 「Configuration」ページの「Permissions」セクションで、「Send Alexa Events」を選択します。
  3. Alexaにメッセージを送信するために必要となるため、clientIdclientSecretをメモに取ります。

認証用コードを追加する

  1. AcceptGrantディレクティブを処理するためのコードを追加します。Alexa.Authorizationインターフェースで取り上げられています。
  2. AcceptGrantメッセージから認証トークンを取り出します。認証トークンを、開発者ポータルからのclientIdclientSecretと一緒に使用して、Login with Amazon(LWA)から各ユーザーの認証とリフレッシュのトークンをリクエストします。このフローについて詳しくは、「Permissionsを設定してAlexaへのユーザー認証を実現する」を参照してください。
  3. 対象リージョンでアクセスできるセキュリティで保護された場所にトークンを保管します。

Alexaイベントゲートウェイにメッセージを送信するためのコードを追加する

最後に、イベントゲートウェイに対するHTTP Postメッセージをフォーマットします。このメッセージには、メッセージヘッダーにユーザーの認証トークンが、メッセージ本文にディレクティブが含まれています。メッセージを次のいずれかのエンドポイントに送信します。

  • North America:https://api.amazonalexa.com/v3/events
  • Europe:https://api.eu.amazonalexa.com/v3/events
  • Far East:https://api.fe.amazonalexa.com/v3/events

これらのメッセージ例の1つを以下に示します。詳細は、「Alexaイベントゲートウェイにイベントを送信する」を参照してください。

POST /v3/events HTTP/1.1 Host: api-amazonalexa.com Authorization:Bearer Alexa-access-token Content-Type: application/json { "context":{ "properties":[ ] }, "event":{ "header":{ "messageId":"abc-123-def-456", "correlationToken":"abcdef-123456", "namespace":"Alexa", "name":"Response", "payloadVersion":"3" }, "endpoint":{ "scope":{ "type":"BearerToken", "token":"Alexa-access-token" }, "endpointId" :"endpoint-id" }, "payload":{ } } }