スマートホームスキルの作成手順
このドキュメントでは、スマートホームスキルの作成手順を説明します。開発者コンソールでのスキルの作成、スキルコードをホスティングするAWS Lambda関数の作成、スキルの設定とテスト、認定の申請について、手順を追って説明します。Alexaスマートホーム スキルAPIの詳細については、スマートホームスキルAPIについてを参照してください。
前提条件
スマートホームスキルを開発するには以下が必要です。
- Alexa開発者アカウント。登録は無料です。
- クラウドAPIを使用して制御することができる照明、サーモスタット、カメラ、ロック、その他のデバイスなどのコネクテッドデバイス。
- Amazon EchoなどのAlexa搭載デバイス。
- アマゾンウェブサービス（AWS）アカウント。スキルコードはAWS Lambda関数でホストします。
- JSONとAWS Lambdaがサポートするいずれか1つの言語に関する知識。 Node.js、Java、Python、C#、Goのいずれかです。
- OAuth 2.0に関する理解。
スキルを作成する
- Alexa開発者コンソールを開きます。
- スキルの作成ボタンをクリックします。
- スキル名を入力します。
スキル名に、機能制限があることを示す文言は使用できません。たとえば、「基本」、「簡易版」、「簡単」などはスキルのタイトルには使わないでください。 - スキルのデフォルトの言語は英語（米国）です。別の地域/言語を対象にする場合は、ドロップダウンを使用してデフォルトの言語を変更します。
各言語でサポートされるデバイスのカテゴリーについては、スマートホームスキルを複数の言語で開発するを参照してください。 - スキルに追加するモデルを選択セクションでスマートホームを選択し、スキルを作成をクリックします。
- ペイロードのバージョンでv3（推奨）を選択します。
- 保存をクリックしてスキルIDをクリップボードにコピーします。
IDは次のような形式です。amzn1.ask.skill.1a2b55555-c325-1234-d56e-1f234d5e6a78
開発者コンソールの使用方法の詳細については、開発者コンソールを使用したスキルの作成と管理を参照してください。
次に、スマートホームスキルのサービスエンドポイントを設定できるよう、Lambda関数を作成します。
Lambda関数を追加する
スキルコードを記述するには、AWSアカウントとAWSに関する基本的な知識が必要です。スキルコードはAWSのLambda関数としてホスティングします。 AWS Lambdaとは、クラウドでコードを実行できるサービスで、サーバーを管理する必要がありません。Alexaはスキルにリクエストを送信します。コードはリクエストを検査し、照明をつけるなどのアクションを実行してAlexaに応答を返します。
Lambda関数を作成するには、AWSアカウントにサインインします。
Lambda用のIAMロールを作成する
Lambdaを使ったことがない場合、Lambda関数の実行が可能なIdentity and Access Management（IAM）ロールを作成する必要があります。IAMロールを作成するには、IAMコンソールに移動します。既にLambda関数を実行するロールがある場合は、次のセクションに進みます。
- ロールを選択し、ロールの作成をクリックします。
- AWSサービスロールのAWS Lambdaを選択します。
- フィルターのボックスに「basic」と入力してAWSLambdaBasicExecutionRoleを選択し、次のステップをクリックします。
- このロールを識別する名前を入力してロールの作成をクリックします。
Lambda関数を作成してコードを追加する
- AWSコンソールで、コンピューティングをクリックし、Lambdaを選択します。
-
リージョンとスキルの言語に合ったLambda関数のリージョンを選択します。
リージョンは、右上隅に表示されます。スマートホームデバイスの検出を正常に行うためには、デバイスが設置されている地域を選択する必要があります。正しい地域を選択することで、レイテンシーを短縮できます。複数の言語と地域をサポートするには、コードを各地域にデプロイする必要があります。詳細については、Lambda関数を複数のリージョンにデプロイするを参照してください。
- 関数の作成をクリックします。
-
一から作成を選択し、以下の情報を入力します。
- 名前： Lambda関数の名前を入力します。この名前はAWSコンソールに表示され、AWSコマンドラインインターフェース（CLI）ListFunctions APIによって返されます。Lambda関数全体で一意である必要があります。
- ランタイム： このトピックで提供されるサンプルコードを使用するには、Node.js 6.10または作成するコードのランタイムを選択します。サポートされる言語は、 Node.js、Java、Python、C#、Goのいずれかです。
- ロール：既存のロールを選択するか、Lambdaの基本的な実行のポリシーをアタッチしたロールを選択します。
- 関数の作成をクリックします。関数が作成され、設定ページが開きます。
- 設定タブのDesignerのトリガーの追加で、Alexa Smart Homeトリガーを選択します。
- トリガーの設定セクションで、開発者コンソールのスキルIDを指定のボックスに追加します。
- トリガーの有効化はオンのままにしておきます。これにより、Amazon AlexaサービスでLambda関数を呼び出せるようになります。スキル作成時に有効にしない場合、コンソールで後から有効にすることはできません。
- 追加をクリックしてから、保存をクリックします。
注： Lambda関数のコードは、C#、Java、Node.js、Pythonで記述できます。このトピックのサンプルコードはNode.jsで記述されており、一部の手順はサンプルコードに固有のものです。
- ページの上部で、Lambda関数を選択して関数コードを表示します。以下は、Lambda関数の例です。
- 関数コードセクションで、コードをインラインで編集が選択されていることを確認します。ランタイムとハンドラはデフォルトのままにしておきます。
- 以下のコードを貼り付け、index.jsのコードをすべて置き換えます。
ReportStateディレクティブに応答するコードと、デバイスの種類とデバイスをサポートするインターフェースに固有のコードを追加する必要があります。その他のサンプルコードについては、AlexaスマートホームのGitHubリポジトリにあります。exports.handler = function (request, context) {
if (request.directive.header.namespace === 'Alexa.Discovery' && request.directive.header.name === 'Discover') {
log("DEBUG:", "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": "スマートデバイス株式会社",
"friendlyName": "寝室のコンセント",
"description": "スマートデバイスのスイッチ",
"displayCategories": ["SWITCH"],
"additionalAttributes": {
"manufacturer" : "スマートデバイス株式会社",
"model" : "サンプルモデル",
"serialNumber": "U11112233456",
"firmwareVersion" : "1.24.2546",
"softwareVersion": "1.036",
"customIdentifier": "サンプルカスタムID"
},
"cookie": {
"key1": "このエンドポイントを参照するためのスキルの任意のキー／値のペアです。",
"key2": "複数のエントリーがある場合があります。",
"key3": "ただし、参照のためにだけ使用してください。",
"key4": "現在のエンドポイントの状態を維持するのに適切な場所ではありません。"
},
"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) {
// 検出中に渡されたデバイスIDを取得します
var requestMethod = request.directive.header.name;
var responseHeader = request.directive.header;
responseHeader.namespace = "Alexa";
responseHeader.name = "Response";
responseHeader.messageId = responseHeader.messageId + "-R";
// リクエスト中のユーザートークンパスを取得します
var requestToken = request.directive.endpoint.scope.token;
var powerResult;
if (requestMethod === "TurnOn") {
// デバイス制御クラウドを呼び出して制御します
// powerResult = stubControlFunctionToYourCloud(endpointId, token, request);
powerResult = "ON";
}
else if (requestMethod === "TurnOff") {
// デバイス制御クラウドを呼び出して制御し、成功したかどうか確認します
// powerResult = stubControlFunctionToYourCloud(endpointId, token, request);
powerResult = "OFF";
}
var contextResult = {
"properties": [{
"namespace": "Alexa.PowerController",
"name": "powerState",
"value": powerResult,
"timeOfSample": "2017-09-03T16:20:50.52Z", //結果から取得します。
"uncertaintyInMilliseconds": 50
}]
};
var response = {
context: contextResult,
event: {
header: responseHeader,
endpoint: {
scope: {
type: "BearerToken",
token: requestToken
},
endpointId: "demo_id"
},
payload: {}
}
};
log("DEBUG", "Alexa.PowerController ", JSON.stringify(response));
context.succeed(response);
}
};
設定を完了してLambda関数をテストする
- 保存をクリックします。
Discoveryリクエストの簡易テストをLambdaコードエディターで実施する場合、テストをクリックします。テストイベントの設定ページが表示されます。- 新しいテストイベントの作成が選択されたままにします。イベントテンプレートは、デフォルトのHello Worldのままにします。イベント名に、
discoveryと入力し、エディターのコンテンツをすべて以下のコードで置き換えます。
{
"directive": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover",
"payloadVersion": "3",
"messageId": "1bd5d003-31b9-476f-ad03-71d471922820"
},
"payload": {
"scope": {
"type": "BearerToken",
"token": "access-token-from-skill"
}
}
}
}
- 作成をクリックし、
テストをクリックします。成功すると、実行結果は以下のようになります。
{
"event": {
"header": {
"correlationToken": "12345692749237492",
"messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
"name": "Discover.Response",
"namespace": "Alexa.Discovery",
"payloadVersion": "3"
},
"payload": {
"endpoints": [
{
"endpointId": "demo_id",
"manufacturerName": "スマートデバイス株式会社",
"friendlyName": "寝室のコンセント",
"description": "スマートデバイスのスイッチ",
"displayCategories": ["SWITCH"],
"additionalAttributes": {
"manufacturer" : "スマートデバイス株式会社",
"model" : "サンプルモデル",
"serialNumber": "U11112233456",
"firmwareVersion" : "1.24.2546",
"softwareVersion": "1.036",
"customIdentifier": "サンプルカスタムID"
},
"cookie": {
"key1": "このエンドポイントを参照するためのスキルの任意のキー／値のペアです。",
"key2": "複数のエントリーがある場合があります。",
"key3": "ただし、参照のためだけに使用してください。",
"key4": "現在のエンドポイントの状態を維持するのに適切な場所ではありません。"
},
"capabilities": [
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
},
{
"interface": "Alexa.PowerController",
"version": "3",
"type": "AlexaInterface",
"properties": {
"supported": [
{
"name": "powerState"
}
],
"retrievable": true
}
}
]
}
]
}
}
}
サービスのエンドポイントを設定する
開発者コンソールのスキルの設定でLambda関数のARNを指定する必要があります。
- 開発者コンソールのスキルに戻ります。
- スマートホームサービスのエンドポイントのデフォルトのエンドポイントボックスに、作成したLambda関数のARNを入力し、保存をクリックします。複数言語のスキルを作成する場合、リージョン固有のエンドポイントを指定する必要があります。詳細については、Lambda関数を複数のリージョンにデプロイするを参照してください。
- スキルが1つの言語または地域のみをサポートする場合、デフォルトのARNと選択した地域のARNには同じARNを指定します。
- スキルが複数の言語または地域をサポートする場合、地域ごとのARNを指定する必要があります。どれか1つの地域のARNをデフォルトとして指定します。
アカウントリンク情報を提供する
スマートホームスキルでのアカウントリンクの詳細については、スキルにアカウントリンクを追加するおよびスマートホームなどのドメインのアカウントリンクを参照してください。
セクション3. アカウントリンクで、アカウントリンクを設定をクリックします。このセクションでは、OAuth 2.0プロバイダーからのアカウント情報が必要です。ユーザーはこの情報を使用して、デバイス制御クラウドのアカウントとスマートホームスキルを関連付けることができます。このセクションでは、Login with Amazonまたは別のOAuthプロバイダーを利用できます。
以下を指定します。
- OAuthプロバイダーの認証画面のURI
- OAuthプロバイダーのクライアントID
- OAuthプロバイダーで必要な場合はスコープ
- OAuthプロバイダーのアクセストークンのURI
- クライアントIDに関連付けられたクライアントシークレット
必須フィールドの詳細については、Authorization code grantを設定するを参照してください。
状態および変更レポートを実装する
スマートホームには状態レポートを実装することをお勧めします。状態レポートでは、ユーザーにデバイスの現在の状態が表示されるからです。状態レポートは、Works With Alexa認定を受けたデバイスを対象とするスマートホームスキルでは必須です。
詳細については、状態および変更レポートについてを参照してください。
状態レポートを実装するには以下の手順を実施します。
- スキルが、
ReportStateディレクティブにStateReportイベントで応答するようにコードを記述します。StateReportイベントの例については、各インターフェースのドキュメントを参照してください。 - Alexaイベントゲートウェイにイベントを送信する権限をリクエストします。
AcceptGrantディレクティブを処理して認証情報を取得するようコードを追加します。詳細については、Alexa.Authorizationを参照してください。- 保存したユーザー認証トークンを使用してAlexaイベントゲートウェイに
ChangeReportイベントを送信するよう、コードを追加します。ChangeReportイベントの例については、各インターフェースのドキュメントを参照してください。
スキルをテストする
スマートホームスキルのテストとデバッグのオプションについては、スマートホームスキルのテストとデバッグを参照してください。
実装が完了し、Lambda関数のテストが完了したら、スマートホームスキルの機能をテストできます。
- スマートホームのトリガーを追加し、有効にしていることを確認してください。Lambdaコンソールでスキルを選択し、Alexa Smart Homeトリガーが表示されることを確認します。
- Alexaアプリ（Android、iOS、ウェブ（https://alexa.amazon.co.jp）で利用可能）に、開発者アカウントと同じアカウントでサインインします。
- Alexaアプリでスキルを検索します。スキルに移動し、すべてのスキルページ右上隅の有効なスキルをタップします。開発スキルまでスクロールして、スキルを見つけます。
- 有効にするボタンをクリックしてスキルを有効にすると、スキルをデバイス制御クラウドにアカウントリンクするページにリダイレクトされます。アカウントリンクを完了できない場合、デバイス制御クラウドの有効な認証情報を使用していることを確認します。それでも完了できない場合、開発者コンソールで提供したアカウントリンク情報に問題がある可能性があります。ヘルプが必要な場合、開発者フォーラムのAlexa: Debugging account linkingを参照してください。後でアカウントリンクを削除する場合、スキルタブでスキルを無効にする必要があります。
- ウィンドウを閉じて、Alexaアプリの検出ボタンをタップします。
- スキルがデバイスを検出しない場合、Lambda関数のログでAlexaからdiscoverディレクティブを受信したかどうかを確認し、問題のトラブルシューティングを行います。よくある問題としては、イベント応答が正しい形式でないなどがあります。
- スキルが正常にデバイスを検出した場合、開発者コンソールのテストページに戻ります。テストページで、テストスライダーを右側にスライドさせて有効にし、Alexaシミュレーターを使ってAlexaコマンドを渡します。その際、検出プロセスで見つかったデバイス名とスキルがサポートする発話を使用します。スキルを有効な発話（スキルが機能するはずのリクエスト）と無効な発話（機能しないはずのリクエスト）、ターゲットデバイスが電源オフの状態などのさまざまな条件でテストします。
- スマートホームスキルのパフォーマンステストで満足できる結果が出たら、ベータテストまたは認定の申請を行うことができます。
公開情報を提供する
ベータテストのためにユーザーにスキルを提供する、または認定を申請するには、Alexaアプリでスキルを説明するための情報を提供する必要があります。
-
公開を選択し、日本語（日本）ストアでのプレビューページで、以下を指定します。
- 公開名
- 簡単な説明
- 詳細な説明
- サンプルフレーズ
- 小さなスキルアイコン
- 大きなスキルアイコン
- キーワード
- プライバシーポリシーのURL
- 利用規約のURL
これらのフィールドに指定する際、こちらのページで提供されているヒント（「？」マークにカーソルを当てると表示）を活用してください。詳細については、スマートホームスキル公開のガイドを参照してください。
- 保存して続行をクリックします。
プライバシーとコンプライアンスページの質問に答えます。テストの手順に、テストアカウントの認証情報を提供します。テストの手順やその他の公開情報が公開ガイドのガイドラインに従っていることを確認してください。
- 保存して続行をクリックします。
- 公開範囲ページで、公開、Alexa for Businessに参入している企業のいずれかにチェックします。
- スキルが利用できる国と地域を選択します。
- 保存して続行をクリックします。
スキルのベータテストを行う（任意）
この時点で、ベータテストボタンが有効になっているはずです。すべての情報を入力してベータテストを開始できます。詳細については、スキルのベータテストを参照してください。
スキルの認定を申請する
すべてのフィールドの入力が完了し、大きな緑色のチェックマークが表示されたら、スキルの認定を申請できます。
- ページの下の審査を申請をクリックします。
公開中のスキルの変更を申請する
スキルが公開中になると、それ以降の変更には認定が必要になります。たとえば、開発者コンソールでスキルについて入力する情報を変更した場合やAWS Lambda関数を変更した場合は、スキルの再認定が必要になります。認定の審査は変更内容によって異なります。Lambda関数を更新した場合は追加の審査が必要になる場合があります。
スキルのステータスが公開中になったら、新しい開発中バージョンが自動的に開発者コンソールに作成され、公開中スキルのすぐ下に表示されます。このバージョンには、元の公開中のバージョンと同じ情報が登録されています。このバージョンを使用してスキルの開発を続け、改良を加えたり、新しい機能を追加することができます。
更新したスキルを申請する場合、開発者コンソールのテストの手順にすべての変更についての詳細説明を記載した変更ログを追加します。
Lambda関数を更新する
AWS Lambda関数を更新するには、以下を実施します。
-
新しいARNでLambda関数を新規作成し、公開中のLambda関数を新しいLambda関数にコピーします。
-
新しいLambda関数を更新します。公開中のスキルをサポートしているLambda関数を更新しないでください。また、Lambdaのエイリアスとバージョニングはしないでください。スキルを更新すると正しく動作しなくなるためです。
-
開発中のスキルで、Lambda ARNを新しいLambda ARNに更新します。
スキルが再認定されて公開中になると、スキルは新しいLambda ARNを使用するようになります。前のLambda関数は削除することもできますし、将来の開発や更新のために使用することもできます。