スマートホームスキルの作成手順
ここでは、ディレクティブに非同期で応答するスマートホームスキルを作成する手順を説明します。開発者コンソールでのスキルの作成、AWS Lambda関数の作成、スキルの設定とテスト、認定の申請について、手順を追って説明します。
- Amazon開発者として登録してスキルを作成する
- Lambda関数を追加する
- スマートホームサービスのエンドポイントを設定する
- アカウントリンク情報を提供する
- スキルをテストする
- 公開情報を提供する
- オプションのベータテストを実施する
- スキルの認定を申請する
- 公開中のスキルの変更を申請する
- 状態レポートを実装する
Amazon開発者として登録してスキルを作成する
新しいスマートホームスキルを作成するには、Amazon開発者コンソールのアカウントが必要です。既存のアカウントを持っていない場合は、https://developer.amazon.com/alexa/console/askにアクセスしてアカウントを新規作成してください。登録は無料です。登録が完了したら、以下を実行します。
- ブラウザでAmazon開発者コンソールを開きます。
- スキルの作成ボタンをクリックします。
- スキル名を入力します。スキル名に、機能制限があることを示す文言は使用できません。たとえば、「基本」、「簡易版」、「簡単」などはスキルのタイトルには使わないでください。スキルのデフォルトの言語は英語（米国）です。別の地域／言語を対象にする場合は、ドロップダウンを使用してデフォルトの言語を変更します。各言語でサポートされるデバイスのカテゴリーを確認するには、スマートホームスキルを複数の言語で開発するを参照してください。
- スキルに追加するモデルを選択セクションでスマートホームを選択し、スキルを作成をクリックします。スマートホームはプリビルドモデルです。
- ペイロードのバージョンでv3（推奨）を選択します。
- 保存をクリックしてスキルIDをクリップボードにコピーします。IDは次のような形式です。
amzn1.ask.skill.1a2b55555-c325-1234-d56e-1f234d5e6a78
開発者コンソールの使用方法の詳細については、開発者コンソールを使用したスキルの管理を参照してください。
次に、スマートホームスキルのサービスエンドポイントを設定できるよう、Lambda関数を作成します。
Lambda関数を追加する
AWSアカウントとAWSに関する基本的な知識が必要です。スマートホームスキルのコードは、AWSのLambda関数としてホストされます。 AWS Lambdaとは、クラウドでコードを実行できるサービスで、サーバーを管理する必要がありません。Alexaはスキルにリクエストを送信すると、コードがリクエストを検査し、ユーザーに代わってデバイス制御クラウドと通信するなどの必要なアクションを実行してから、応答を返します。
Lambda関数を作成するには、AWSアカウントにサインインします。
Lambda用のIAMロールを作成する
Lambdaを使ったことがない場合、基本的な実行が可能なIdentity and Access Management（IAM）ロールを作成する必要があります。IAMロールを作成するにはIAMコンソールに移動します。Lambdaの基本的な実行が可能なロールがある場合は、次のセクションに進みます。
- ロールを選択し、ロールの作成をクリックします。
- AWSサービスロールのAWS Lambdaを選択します。
- フィルターのボックスに「basic」と入力してAWSLambdaBasicExecutionRoleを選択し、次のステップをクリックします。
- このロールを識別する名前を入力してロールの作成をクリックします。
Lambda関数を作成してコードを追加する
- AWSコンソールで、コンピューティングをクリックし、Lambdaを選択します。
- 以下のいずれかが選択されていることを確認します。
- 英語（米国）または英語（カナダ）のスキルの場合は米国東部（バージニア北部）
- 英語（英国）、英語（インド）、ドイツ語、フランス語（フランス）のスキルの場合はEU（アイルランド）
- 日本語および英語（オーストラリア）スキルの場合は米国西部（オレゴン）
地域は、右上隅に表示されます。スマートホームデバイスの検出を正常に行うためには、デバイスが設置されている地域を選択する必要があります。正しい地域を選択することで、レイテンシーを短縮できます。複数の言語と地域をサポートするには、コードを各地域にデプロイする必要があります。詳細については、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"],
"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"],
"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を指定する必要があります。
- 開発者コンソールのスキルに戻ります。
- 2. スマートホームサービスのエンドポイントのデフォルトのエンドポイントボックスに、作成したLambda関数のARNを入力し、保存をクリックします。複数言語のスキルを作成する場合、地域固有のエンドポイントを指定する必要があります。以下の表は、スキルに選択した言語、地域のエンドポイントとLambda関数の地域の関連をまとめたものです。
| スキルの言語 | エンドポイントの地域 | Lambda関数の地域 |
|---|---|---|
| 英語（米国）、英語（カナダ） | 北米 | 米国東部（バージニア北部） |
| 英語（英国）、フランス語（フランス）、ドイツ語、イタリア語、スペイン語（スペイン） | ヨーロッパ、インド | EU（アイルランド） |
| 英語（インド） | ヨーロッパ、インド | EU（アイルランド） |
| 日本語、英語（オーストラリア） | 極東 | 米国西部（オレゴン） |
- スキルが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を設定するを参照してください。スマートホームスキルのアカウントリンクの概要については、以下を参照してください。
スキルをテストする
実装が完了し、Lambda関数のテストが完了したら、スマートホームスキルの機能をテストできます。
- スマートホームのトリガーを追加し、有効にしていることを確認してください。Lambdaコンソールでスキルを選択し、Alexa Smart Homeトリガーが表示されることを確認します。
- Alexaアプリ（Android、iOS、ウェブ（https://alexa.amazon.com）で利用可能）に、開発者アカウントと同じアカウントでサインインします。
- Alexaアプリでスキルを検索します。スキルに移動し、すべてのスキルページ右上隅の有効なスキルをタップします。DEVスキルまでスクロールして、スキルを見つけます。
- 有効にするボタンをクリックしてスキルを有効にすると、スキルをデバイス制御クラウドにアカウントリンクするページにリダイレクトされます。アカウントリンクを完了できない場合、デバイス制御クラウドの有効な認証情報を使用していることを確認します。それでも完了できない場合、開発者コンソールで提供したアカウントリンク情報に問題がある可能性があります。ヘルプが必要な場合、開発者フォーラムのAlexa: Debugging account linkingを参照してください。後でアカウントリンクを削除する場合、スキルタブでスキルを無効にする必要があります。
- ウィンドウを閉じて、Alexaアプリの検出ボタンをタップします。
- スキルがデバイスを検出しない場合、Lambda関数のログでAlexaからdiscoverディレクティブを受信したかどうかを確認し、問題のトラブルシューティングを行います。よくある問題としては、イベント応答が正しい形式でないなどがあります。
- スキルが正常にデバイスを検出した場合、開発者コンソールのテストページに戻ります。テストページで、テストスライダーを右側にスライドさせて有効にし、Alexaシミュレーターを使ってAlexaコマンドを渡します。その際、検出プロセスで見つかったデバイス名とスキルがサポートする発話を使用します。スキルを有効な発話（スキルが機能するはずのリクエスト）と無効な発話（機能しないはずのリクエスト）、ターゲットデバイスが電源オフの状態などのさまざまな条件でテストします。
- スマートホームスキルのパフォーマンステストで満足できる結果が出たら、ベータテストまたは認定の申請を行うことができます。
公開情報を提供する
ベータテストのためにユーザーにスキルを提供する、または認定を申請するには、Alexaアプリでスキルを説明するための情報を提供する必要があります。
-
公開を選択し、日本語（日本）ストアでのプレビューページで、以下を指定します。
- 公開名
- 説明
- 詳細な説明
- サンプルフレーズ
- 小さなスキルアイコン
- 大きなスキルアイコン
- キーワード
- プライバシーポリシーのURL
- 利用規約のURL
これらのフィールドに指定する際、こちらのページで提供されているヒント（「？」マークにカーソルを当てると表示される）を活用してください。これらのフィールドの指定方法の詳細については、スマートホームスキル公開のガイドを参照してください。
- 保存して続行をクリックします。
プライバシーとコンプライアンスページの質問に答えます。テストの手順に、テストアカウントの認証情報を提供します。テストの手順やその他の公開情報が公開ガイドのガイドラインに従っていることを確認してください。
- 保存して続行をクリックします。
- 公開範囲ページで、公開、Alexa for Businessに参入している企業のいずれかにチェックします。
- スキルが利用できる国と地域を選択します。
- 保存して続行をクリックします。
オプションのベータテストを実施する
この時点で、ベータテストボタンが有効になっているはずです。すべての情報を入力してベータテストを開始できます。詳細については、スキルのベータテストを行うを参照してください。
スキルの認定を申請する
すべてのフィールドの入力が完了し、大きな緑色のチェックマークが表示されたら、スキルの認定を申請できます。
- ページの下の審査を申請をクリックします。
スキルの認定は、デバイスのWorks with Alexa認定とは異なりますので注意してください。詳細については、Works with Alexaの認定を受けるを参照してください。
公開中のスキルの変更を申請する
スキルが公開中になると、それ以降の変更には認定が必要になります。たとえば、開発者コンソールでスキルについて入力する情報を変更した場合やAWS Lambda関数を変更した場合は、スキルの再認定が必要になります。認定の審査は変更内容によって異なります。Lambda関数を更新した場合は追加の審査が必要になる場合があります。
スキルのステータスが公開中になったら、新しい開発中バージョンが自動的に開発者コンソールに作成され、公開中スキルのすぐ下に表示されます。このバージョンには、元の公開中のバージョンと同じ情報が登録されています。このバージョンを使用してスキルの開発を続け、改良を加えたり、新しい機能を追加することができます。
更新したスキルを申請する場合、開発者コンソールのテストの手順にすべての変更についての詳細説明を記載した変更ログを追加します。
Lambda関数を更新する
AWS Lambda関数を更新するには、以下を実施します。
-
新しいARNでLambda関数を新規作成し、公開中のLambda関数を新しいLambda関数にコピーします。
-
新しいLambda関数を更新します。公開中のスキルをサポートしているLambda関数を更新しないでください。また、Lambdaのエイリアスとバージョニングはしないでください。スキルを更新すると正しく動作しなくなるためです。
-
開発中のスキルで、Lambda ARNを新しいLambda ARNに更新します。
スキルが再認定されて公開中になると、スキルは新しいLambda ARNを使用するようになります。前のLambda関数は削除することもできますし、将来の開発や更新のために使用することもできます。
状態レポートを実装する
最高のユーザーエクスペリエンスを提供するため、状態レポートはすべてのスマートホームスキルで提供することをおすすめします。詳細については、スマートホームスキルの状態レポートについてを参照してください。状態レポートは、Works With Alexa認定を受けたデバイスを対象とするスマートホームスキルでは必須です。詳細については、Works with Alexa認定スキルの要件を参照してください。
状態レポートを実装するには以下の手順を実施します。
- スキルが、ReportStateディレクティブにStateReportイベントで応答するようにします。
- Alexaイベントゲートウェイにイベントを送信する権限をリクエストします。
- AcceptGrantディレクティブを受信して認証情報を取得するようコードを追加します。
- 保存したユーザー認証トークンを使用してAlexaイベントゲートウェイにChangeReportメッセージを送信するよう、コードを追加します。
