チュートリアル： 初めての視覚応答をカスタムスキルに追加する
このチュートリアルでは、Alexa Presentation Language（APL）を使って視覚応答をカスタムスキルに追加する方法を紹介します。応答では、レイアウトにレスポンシブ対応テンプレート、コンテンツにデータソースを使って「Hello World」を表示します。
前提条件
Amazon開発者アカウントと動作するカスタムスキルが必要です。チュートリアルでは、Node.jsの「Hello World」サンプルスキルに追加できるコード例を提供しています。元のサンプルスキルは、GitHubのskill-sample-nodejs-hello-worldで入手できます。gitリポジトリの指示に従って、このチュートリアルを開始する前にスキルをセットアップしてください。
開発者コンソールにログインし、テストシミュレーターを使ってスキルを呼び出せることを確認してください。インテントのいずれかを呼び出して、エラーなく応答を取得できることを確認します。「Hello World」サンプルを使用する場合、HelloWorldIntentを呼び出せることを確認します。
カスタムスキルに視覚応答を追加する手順
APLは、カスタムスキルのリクエストと応答のインターフェース内で動作します。スキルがLaunchRequestやIntentRequestなどのリクエストを受け取ると、応答の一部としてAPLドキュメントとデータソースを指定できます。Alexaは、画面に応答を表示します。
このチュートリアルでは、APLドキュメントとデータソースを作成します。その後、応答にAPLコンテンツを追加してスキルコードのインテントハンドラーを更新します。以下がチュートリアルの各ステップです。
- APLインターフェースに対応するようスキルを設定する。
- APLオーサリングツールを使って、表示するAPLドキュメントを作成して保存する。
- ドキュメント内に表示するコンテンツに追加するデータソースを作成し、ドキュメントのプロパティとデータソースをバインドするデータバインディング式を記述する。
- 応答の一部としてドキュメントとデータソースをAlexaに送信するようスキルコードを更新する。
- 開発者コンソールでスキルをテストして、新しい視覚応答を確認する。
ステップ1： 開発者コンソールでAPLインターフェースを有効にする
APLコンテンツを含む応答を送信するには、スキルがAlexa.Presentation.APLインターフェースに対応している必要があります。開発者コンソールでこのオプションを有効にします。
開発者コンソールでAPLインターフェースを有効にする
- 開発者コンソールを開き、設定するスキルの編集をクリックします。
- ビルド＞インターフェースページに移動します。
-
Alexa Presentation Languageオプションを有効にします。
このアクションにより、スキルは表示するAlexa APLコンテンツを送信できるようになります。
-
viewportプロファイルのリストで、すべてのプロファイルを選択します。
- インターフェースを保存、モデルをビルドの順にクリックして、対話モデルを再ビルドします。
ステップ2： オーサリングツールでAPLドキュメントを作成する
APLドキュメントは、視覚応答のテンプレートを定義します。以下のセクションでは、オーサリングツールでAPLドキュメントを新規作成し、テキストを1行表示するようドキュメントを更新します。
APLドキュメントを新規作成する
- 開発者コンソールで、引き続きスキルのビルドページを開いていることを確認してください。
- サイドバーでマルチモーダルをクリックします。このアクションにより、新規のウィンドウかブラウザのタブでAPLオーサリングツールが開きます。
- 視覚を選択します。
- 視覚応答を作成をクリックします。このアクションにより、使用可能なテンプレートが表示されたページが開きます。
- 空のドキュメントをクリックして、コンテンツのない新規のAPLドキュメントを作成します。
-
保存アイコンをクリックします。プロンプトが出たら、「HelloWorldDocument」という名前を入力します。
チュートリアルのステップを実施する間、保存をこまめにクリックして作業を保存してください。オーサリングツールでは自動保存されません。
APLパッケージでは、APLドキュメントに読み込めるレイアウト、リソース、スタイルのセットを定義します。Amazonが提供するalexa-layoutsパッケージには、レスポンシブ対応コンポーネントとレスポンシブ対応テンプレートのセットが含まれます。これらのレイアウトは、さまざまなモード、サイズ、形状を持つviewportに自動的に対応します。視覚応答を作成すると決めたら、まず利用可能なプリビルドのテンプレートとコンポーネントを確認します。
ドキュメントでパッケージを使用するには、まずパッケージを読み込む必要があります。
alexa-layoutsパッケージを読み込む
-
オーサリングツールで、コードビュータブをクリックしてAPLドキュメントのJSONコードを表示します。
-
import配列で、以下のオブジェクトを追加します。{ "name": "alexa-layouts", "version": "1.5.0" }注： Amazonが提供するパッケージの場合、nameとversionを指定します。独自のパッケージやほかの開発者が共有しているパッケージの場合、name、version、sourceを指定します。sourceはパッケージのURLです。
変更を行うと、JSONコードは以下の例のようになります。
{
"type": "APL",
"version": "2022.1",
"license": "Copyright 2021 Amazon.com, Inc. or its affiliates.All Rights Reserved.\nSPDX-License-Identifier: LicenseRef-.amazon.com.-AmznSL-1.0\nLicensed under the Amazon Software License http://aws.amazon.com/asl/",
"settings": {},
"theme": "dark",
"import": [
{
"name": "alexa-layouts",
"version": "1.5.0"
}
],
"resources": [],
"styles": {},
"onMount": [],
"graphics": {},
"commands": {},
"layouts": {},
"mainTemplate": {
"parameters": [
"payload"
],
"items": []
}
}
APLドキュメントでは、mainTemplateプロパティはドキュメントが最初に画面に表示されるときに表示するレイアウトを指定します。mainTemplate.itemsプロパティには、表示する項目の配列が含まれます。以降のステップでは、AlexaHeadlineレスポンシブ対応テンプレートをitems配列に追加します。
AlexaHeadlineのJSONコードを追加する
- オーサリングツールでは引き続きコードビューを開いています。
-
mainTemplate.items配列に、以下のコードブロックを追加します。{ "type": "AlexaHeadline", "primaryText": "このテキストを表示します" }プレビューペインが更新され、viewportに「このテキストを表示します」が中央揃えで表示されます。
変更を行うと、JSONコードは以下の例のようになります。
{
"type": "APL",
"version": "1.8",
"license": "Copyright 2021 Amazon.com, Inc. or its affiliates.All Rights Reserved.\nSPDX-License-Identifier: LicenseRef-.amazon.com.-AmznSL-1.0\nLicensed under the Amazon Software License http://aws.amazon.com/asl/",
"settings": {},
"theme": "dark",
"import": [
{
"name": "alexa-layouts",
"version": "1.4.0"
}
],
"resources": [],
"styles": {},
"onMount": [],
"graphics": {},
"commands": {},
"layouts": {},
"mainTemplate": {
"parameters": [
"payload"
],
"items": [
{
"type": "AlexaHeadline",
"primaryText": "このテキストを表示します"
}
]
}
}
ステップ3： ドキュメントをデータソースに接続する
ここまでに作成したドキュメントでもスキルで動作しますが、外観と表示するコンテンツを分けることをお勧めします。このアプローチは、テンプレート内に表示するデータがスキルの一定の条件下で変化する場合に重要です。たとえば、スキルがユーザーに名前をたずね、その名前を画面に表示する場合を考えてみてください。デバイスがドキュメントをレンダリングするたびに、表示するデータが変わる可能性があります。
スキルからドキュメントにデータを渡す正しい方法は、データソースにコンテンツを配置し、その後でデータバインディング式を使用してそのコンテンツをAPLドキュメントに接続することです。各応答で同じドキュメントをコードから送信しますが、更新したデータソースを使って送信します。
データソースをオーサリングツールに追加する
-
オーサリングツールで、DATAボタンをクリックしてデータソースペインを開きます。
データソースペインでは、データソースをドキュメントに渡すシミュレーションができます。後でドキュメントをコードに追加すると、ディレクティブの一部としてデータソースが送信されます。
-
このペインの内容を以下のコードで置き換えます。
{ "helloWorldDataSource": { "primaryText": "ハローワールド", "secondaryText": "Alexa Presentation Languageへようこそ。", "color": "@colorTeal800" } }テンプレートのプロパティをデータソースのプロパティにまだバインドしていないため、プレビューペインは変わりません。
独自のAPLドキュメントを作成する場合、データソースの構造を自分でデザインします。
データソースをドキュメントに追加してデータバインディング式を記述する
- オーサリングツールで、APLボタンをクリックしてドキュメントページに戻ります。まだコードビューを開いていることを確認してください。
-
parameters配列で、既存のpayload項目を削除して"helloWorldDataSource"で置き換えます。{ "mainTemplate": { "parameters": [ "helloWorldDataSource" ], "items": [ { "type": "AlexaHeadline", "primaryText": "このテキストを表示します" } ] } } -
primaryTextプロパティは、「このテキストを表示します」を以下の式に変更します。${helloWorldDataSource.primaryText}プレビューペインに表示されるテキストが、「ハローワールド」に変わります。
-
secondaryTextプロパティとbackgroundColorプロパティを追加して、それぞれをデータソース内の対応するデータにバインドします。{ "type": "AlexaHeadline", "primaryText": "${helloWorldDataSource.primaryText}", "secondaryText": "${helloWorldDataSource.secondaryText}", "backgroundColor": "${helloWorldDataSource.color}" }プレビューペインが更新され、2つのテキストブロックと青緑色の背景が表示されます。
ステップ4： スキルに応答をレンダリングするコードを追加する
動作するAPLドキュメントを作成できたので、応答のドキュメントを含めるようスキルにコードを追加します。応答でAlexa.Presentation.APL.RenderDocumentディレクティブをAlexaに送信します。ドキュメントへのリンクとデータソース全体のJSONコードを、ディレクティブプロパティのRenderDocumentディレクティブに渡します。
スキル応答にRenderDocumentディレクティブを追加する
- IDEでスキルコードを開きます。Alexa-hostedスキルの場合、開発者コンソールのコードタブに移動します。
-
更新するインテントハンドラーを見つけます。「Hello World」サンプルスキルの場合、
HelloWorldIntentHandlerを見つけます。 -
RenderDocumentディレクティブを追加するには、if...elseブロックをhandle関数のコードの1行目とreturn文の間に追加します。handle(handlerInput) { const speakOutput = handlerInput.t('HELLO_MSG'); // 新しいIFブロックをここに追加 return handlerInput.responseBuilder .speak(speakOutput) //.reprompt('ユーザーが応答できるようセッションを開いたままにする場合は再プロンプトを追加してください') .getResponse(); } - コードへの変更内容を保存します。
RenderDocumentを返すIf…elseブロック
if (Alexa.getSupportedInterfaces(handlerInput.requestEnvelope)['Alexa.Presentation.APL']){
console.log("ユーザーのデバイスはAPLに対応しています");
const documentName = "HelloWorldDocument"; // オーサリングツールに保存されたドキュメントの名前
const token = documentName + "Token";
// RenderDocumentディレクティブを応答に追加します
handlerInput.responseBuilder.addDirective({
type: 'Alexa.Presentation.APL.RenderDocument',
token: token,
document: {
src: 'doc://alexa/apl/documents/' + documentName,
type: 'Link'
},
datasources: {
"helloWorldDataSource": {
"primaryText": "ハローワールド",
"secondaryText": "Alexa Presentation Languageへようこそ。",
"color": "@colorTeal800"
}
}
});
} else {
// デバイスがAPLに対応していないことをログに記録するだけです。
// 実際のスキルでは、ユーザーに別の内容を読み上げることもできます。
console.log("ユーザーのデバイスはAPLに対応していません。画面付きのデバイスで再テストしてください")
}
以下の例は、APLコードとHelloWorldIntentHandlerのコード全体です。
更新内容をテストする前に、スキルコードをデプロイする必要があります。
Alexa-hostedスキルを保存してデプロイする
- コードエディタタブを開いていることを確認します。
- 保存をクリックしてから、デプロイをクリックします。
表示されたRenderDocumentコードでは、documentプロパティがオーサリングツールで保存したドキュメントへのリンクに設定されています。オーサリングツールで保存したAPLドキュメントをスキルのバックエンドコードで使用できるようにするには、スキルの対話モデルを作成する必要があります。
対話モデルを再ビルドする
- 開発者コンソールに戻り、ビルドタブを開きます。
- 呼び出し > スキルの呼び出し名など、対話モデルのいずれかのセクションを開き、モデルをビルドをクリックします。
ステップ5： 更新されたスキルをテストする
スキルのテストには、デバイスを使うことも、開発者コンソールのスキルシミュレーターを使うこともできます。
開発者コンソールでスキルをテストする
- 開発者コンソールで、テストタブを開きます。
- スキルテストが有効になっているステージオプションで、開発中を選択します。
- 画面付きデバイスのシミュレーターを表示するには、デバイスの表示を選択します。
-
Alexaシミュレーターの下で、スキルを呼び出し、テスト発話を入力します。
Hello Worldスキルの場合、呼び出し名を入力し、発話「ハロー」を入力します。
- スキルI/Oセクションの下までスクロールして、デバイスシミュレーターを表示します。ビルド済みの「Hello World」ドキュメントが表示されます。
Hello Worldスキルのトラブルシューティング
シミュレーターにAPLコンテンツが表示されない場合、以下の問題を確認してください。
問題： URLが無効であることを示すエラー
現象
インテントを呼び出すと、Alexaが「指定されたスキルに設定されたURIは有効ではありません」というエラーメッセージを読み上げます。
このエラーは、RenderDocumentディレクティブのdocument.srcプロパティで指定したURIがスキルに保存したドキュメントと一致しない場合に発生します。
解決方法
対話モデルを再ビルドしてオーサリングツールに保存したドキュメントをスキルで使用できるようにしてください。このエラーは、ドキュメントを保存しても、モデルを再ビルドしていない場合に発生する可能性があります。モデルを再ビルドし、スキルをもう一度テストします。
解決方法
document.srcプロパティに渡すURIは、doc://alexa/apl/documents/{documentName}の形式にし、{documentName}にはオーサリングツールのドキュメント名を入れる必要があります。このチュートリアルでは、ドキュメントをHelloWorldDocumentとして保存しています。このため、正しいURIは、doc://alexa/apl/documents/HelloWorldDocumentとなります。
- スキル応答にRenderDocumentディレクティブを追加するの例を参照して、コードを再確認してください。名前のスペルがすべて正しいことを確認します。
- オーサリングツールに戻り、正しい名前でドキュメントを保存したことを確認します。
問題： 画面上のAPLコンテンツに情報が欠けているか、画面が空白
現象
スキルをテストしてもAlexaはエラーを報告しませんが、画面に表示されるコンテンツには情報が不足しています。たとえば、「ハローワールド」行は表示されても、「Alexa Presentation Languageへようこそ」行がなかったり、画面全体が空白で表示されます。
解決方法
この問題は、ドキュメントのデータバインディング式がデータソースの構造と一致しない場合に発生します。画面全体が空白の場合、RenderDocumentディレクティブがドキュメントと一緒にデータソース全体を渡すように設定されていない可能性があります。
データバインディング式をデータソースに一致させる
-
addDirective()を呼び出すと、datasourcesプロパティがhelloWorldDataSourceのJSONに設定されることを確認します。handlerInput.responseBuilder.addDirective({ type: 'Alexa.Presentation.APL.RenderDocument', token: token, document: { src: 'doc://alexa/apl/documents/' + documentName, type: 'Link' }, datasources: { "helloWorldDataSource": { "primaryText": "ハローワールド", "secondaryText": "Alexa Presentation Languageへようこそ。", "color": "@colorTeal800" } } }); -
データソースのすべてのプロパティがドキュメントで使用されるプロパティと一致していることを確認します。サンプルのHello Worldドキュメントでは、3つの式を使っています。
${helloWorldDataSource.primaryText}${helloWorldDataSource.secondaryText}${helloWorldDataSource.color}
-
ドキュメントで、
mainTemplate.parameters配列にhelloWorldDataSource文字列が含まれていることを確認します。
次のステップ
- APLのコースでさらに学ぶ - Alexa Learning Lab（英語）
AlexaHeadlineレスポンシブ対応テンプレートについて詳しく見る – AlexaHeadline- その他のレスポンシブ対応テンプレートを見る – レスポンシブ対応テンプレート
- APLのしくみや作成するその他の要素を詳しく見る – APLの視覚応答を構成する要素
- APLオーサリングツールの詳しい使い方を見る – オーサリングツールを使用したAPLドキュメントの作成
最終更新日: 2022 年 11 月 02 日