オーサリングツールを使用したAPLドキュメントの作成
APLオーサリングツールを使用すると、APLドキュメントを作成し、それをプレビューで確認することができます。ドキュメントは最初から作成することも、サンプルテンプレートから作成することもできます。ドキュメントを作成したら、スキル内で使用するドキュメントのJSONコードを書き出すことができます。
APLについて詳しくは、Alexa Presentation Language（APL）の概要を参照してください。
- APLオーサリングツールを理解する
- APLドキュメントを作成および編集する
- コンポーネントとデータを使用してドキュメントを構築する
- 異なるviewportでドキュメントを表示する
- スキルでドキュメントを保存する
- ドキュメントとデータソースを書き出す
- 関連トピック
APLオーサリングツールを理解する
APLオーサリングツールでは、APLドキュメントを作成してプレビューすることができます。ドキュメントを視覚的に構築したり、JSONを直接編集したりすることもできます。ドキュメントを構築したら、そのドキュメントが画面付きデバイスでどのように表示されるかを大まかに確認できます。
確認後、これらのドキュメントをスキルで保存し、後で使用できるようにします。スキルでドキュメントを使用するには、JSONコードをコピーまたは書き出して、そのJSONをRenderDocumentディレクティブの一部として含める必要があります。
APLドキュメントを作成および編集する
通常は、既存のスキル内から新しいドキュメントを作成します。その後、スキルにドキュメントを保存し、後でそのドキュメントを編集できるようにします。ドキュメントは、サンプルテンプレートを使って作成したり、最初から作成したりできるほか、既存のドキュメントをアップロードして作成することもできます。
特定のスキルの新しいドキュメントを作成するには
- 開発者コンソールで、対象のスキルを開きます。
- 左側のナビゲーションで、画面表示をクリックします。これにより、オーサリングツールが新しいウィンドウまたはタブで開き、このスキルで保存されている既存のドキュメントが表示されます。
- テンプレートを作成をクリックします。
- 以下のいずれかを実行します。
- サンプルテンプレートを使用するには、いずれかのテンプレートをクリックします。サンプルテンプレートを参照してください。
- まったく空白の状態から独自のドキュメントを作成するには、最初から作成をクリックします。
- コンピューターから既存のJSONドキュメントを読み込むには、コードをアップロードをクリックし、読み込むファイルを選択します。ドキュメントとデータを読み込む場合の形式を参照してください。
上記のいずれかを行うと、新しいドキュメントがオーサリングツールで開きます。
- コンポーネントとデータを使用してドキュメントを構築すると異なるviewportでドキュメントを表示するの説明に従って、ドキュメントを更新してプレビューします。
- 保存アイコン（
）をクリックして、スキルでドキュメントを保存します。 - 書き出しアイコン（
）を使用して、スキルコードのRenderDocumentディレクティブで使用するために、ドキュメントのJSONを書き出します。
特定のスキルで保存された既存のドキュメントを編集するには
- 開発者コンソールで、ドキュメントを保存したスキルを開きます。
- 左側のナビゲーションで、画面表示をクリックします。これにより、オーサリングツールが新しいウィンドウまたはタブで開き、このスキルで保存されている既存のドキュメントが表示されます。
- 目的のドキュメントの編集をクリックします。
サンプルテンプレート
オーサリングツールに含まれているサンプルテンプレートのベースはDisplayテンプレートです。画面にコンテンツを表示するAlexaスキルの開発経験がある方は、このテンプレートを使用したことがあるかもしれません。たとえば、詳細テキストサンプルはBodyTemplate1に似ています。
各テンプレートは、データソースを使用して、レイアウトで表示されるコンテンツを提供します。データソースを確認するには、DATAをクリックします。次に、BodyTemplate1の場合、背景画像、テキストコンテンツ、ロゴURL画像の参照が含まれます。このJSONデータのコンテンツを変更して、テンプレートが別のコンテンツでどのように表示されるか確認できます。
各テンプレートは、ドキュメントのmainTemplateで使用されるリソースとスタイルを定義します。ドキュメントをすべて確認する場合は、JSONを見るか、左側のツールバーのRESOURCESまたはSTYLESをクリックします。
オーサリングツールのインターフェースの操作について詳しくは、コンポーネントとデータを使用してドキュメントを構築するを参照してください。
ドキュメントとデータを読み込む場合の形式
コードをアップロードオプションを使用してドキュメントを読み込む場合、オーサリングツールはドキュメントが単一トップレベルの「document」プロパティ内に存在することを前提としています。たとえば、以下のようになります（詳細は省略しています）。
{
"document": {
"type": "APL",
"version": "1.2",
"theme": "dark",
"import": [],
"resources": [],
"styles": {},
"layouts": {},
"mainTemplate": {
"parameters": [
"payload"
],
"items": [
]
}
}
}
読み込む際には、データソースを含めることもできます。多くの場合、APLドキュメントは、テンプレートデザインと表示されるデータを切り離すために、別のデータソースを使用します。コードのアップロード時にデータソースを含めるには、ユーザーのドキュメントのJSONとデータを、2つのトップレベルプロパティ（documentとdatasources）を含む1個のJSONファイルと結合します。これは、オーサリングツールからテンプレートのコードをダウンロードしたときに取得する出力に似ています。
この例では、アップロードするファイルの全体の構造を示します（詳細は省略しています）。
{
"document": {
"type": "APL",
"version": "1.2",
"theme": "dark",
"import": [],
"resources": [],
"styles": {},
"layouts": {},
"mainTemplate": {
"parameters": [
"payload"
],
"items": []
}
},
"datasources": {
"bodyTemplate7Data": {
"type": "object",
"objectId": "bt7Sample",
"title": "今日のチーズの写真",
"backgroundImage": {},
"image": {},
"logoUrl": "https://d2o906d8ln7ui1.cloudfront.net/images/cheeseskillicon.png",
"hintText": "試してください\"アレクサ、ブルーチーズについて調べて\""
}
}
}
別の方法として、オーサリングツールで直接データソースを作成または貼り付けることもできます。
コンポーネントとデータを使用してドキュメントを構築する
オーサリングツールでは、コア機能を含む領域が常に表示されます。
| 説明 | |
|---|---|
|
1 |
左側のツールバー： ドキュメントのコンポーネントのグラフィカルビュー、ドキュメントのJSONコード、およびJSONデータソースを切り替えます。 |
|
2 |
|
|
3 |
ドキュメントのプレビューペイン： さまざまなviewportでドキュメントがどのように表示されるかを大まかに確認できます。 |
|
4 |
viewportツールバー： プレビューペインを異なるviewport間で切り替えるためのボタン。Amazon開発者アカウントに関連付けられているデバイスにドキュメントをプッシュすることもできます。 |
|
5 |
コンポーネントパレット： ドキュメントに追加可能なすべてのコアAPLコンポーネントが表示されます。このパレットからプレビューペインに表示されているディスプレイにコンポーネントをドラッグして、ドキュメントを構築できます。 |
次の表は、左側のツールバーのオプションをまとめたものです。
| ツールバーボタン | 説明 |
|---|---|
|
GUI |
レイアウトペインが開き、ドキュメントのコンポーネントがグラフィカルに表示されます。 |
|
APL |
ドキュメント全体のJSONコードが表示されます。完全な構文については、APLドキュメントを参照してください。 |
|
DATA |
データソースのJSONコードが表示されます。APLデータソースとトランスフォーマーを参照してください。 |
|
STYLES |
ドキュメントの |
|
DOCUMENT |
|
|
RESOURCES |
|
|
GRAPHICS |
|
|
SETTINGS |
|
|
COMMANDS |
|
|
ONMOUNT |
|
レイアウトペインでドキュメントを編集する（GUI）
ツールバーのGUIオプションをクリックすると、レイアウトペインが表示され、コンポーネントとレイアウトが階層ビューで表示されます。最初にmainTemplateが表示され、次にlayoutsプロパティで定義したカスタムレイアウトが表示されます。レイアウトペイン内でコンポーネントをドラッグして、階層の配置を変更することもできます。
| 説明 | |
|---|---|
|
1 |
レイアウト： ドキュメント内のすべてのコンポーネントが階層ビューで表示されます。コンポーネントを選択してプラス記号をクリックすると、階層に子コンポーネントを追加できます。 |
|
2 |
コンポーネントのプロパティフォーム： 選択したコンポーネントのプロパティを入力します。 |
mainTemplateまたはカスタムレイアウトにコンポーネントを追加するには
- レイアウトペインで、新しいコンポーネントの親になるコンポーネントを選択します。
mainTemplateやContainerなど、子コンポーネントを含むことができるコンポーネントを選択する必要があります。 - ペインの右上隅に表示される「+」ボタンをクリックします。
- コンポーネントを選択し、追加をクリックします。ドキュメントにカスタムレイアウトが含まれている場合は、コンポーネントの代わりにレイアウトを選択することもできます。
- 右側のペインで、新しいコンポーネントのプロパティを編集します。
カスタムレイアウトを作成するには
- レイアウトペインで、mainTemplateを選択します。
- ペインの右上隅に表示される「+」ボタンをクリックします。
- ドロップダウンリストで、Create Custom Layoutを選択します。
- Custom Layout Nameにカスタムレイアウト名を入力し、追加をクリックします。
- 必要に応じて、新しいレイアウトにコンポーネントを追加します。
コンポーネントのプロパティを更新するには
- 階層のコンポーネントを選択し、レイアウトペインの隣のペインでプロパティ値を編集します。
ドキュメントのJSONを表示および編集する（APL）
ツールバーのAPLオプションをクリックすると、ドキュメント全体のJSONが表示されます。JSONエディターでは、コンマの配置ミスなど、JSON構文エラーの基本的な検証が行われます。また、コンポーネントに属さないプロパティを含めると、エディターによって警告が表示されます。
ツールバーのその他のボタンを使用して、stylesやresourcesプロパティなど、ドキュメントの特定の部分のJSONを表示し、必要に応じて編集することができます。
ドキュメントのデータソースを表示および編集する（DATA）
ツールバーのDATAオプションをクリックすると、データソースのJSONが表示されます。各データソースは、中かっこ（{}）内のトップレベルプロパティであり、データバインディング式でデータソースプロパティを参照するための名前が含まれている必要があります。
以下は有効なデータソースの例です。
{
"bodyTemplate7Data": {
"type": "object",
"objectId": "bt7Sample",
"title": "今日のチーズの写真",
"backgroundImage": {},
"image": {},
"logoUrl": "https://d2o906d8ln7ui1.cloudfront.net/images/cheeseskillicon.png",
"hintText": "試してください\"アレクサ、ブルーチーズについて調べて\""
}
}
ドキュメント内のmainTemplate.parameters配列に「payload」が含まれていれば、${payload.bodyTemplate7Data.title}のように、このデータソース内のプロパティを参照することができます。
データを変更すると、プレビューペインが更新され、更新されたデータでテンプレートがどのように表示されるかが示されます。
ドラッグ&ドロップでドキュメントを構築する
ドキュメントのプレビューペインでコンポーネントをクリックしてドラッグすることで、ドキュメントを視覚的に編集できます。
- コンポーネントパレットでコンポーネントをクリックし、ドキュメントにドラッグします。
Text、Image、Videoコンポーネントを空のプレビューにドラッグすると、オーサリングツールによってコンポーネントが自動的にContainer内に配置されます。- ツールバーのGUIをクリックしてからレイアウトペインでコンポーネントをクリックし、プレビューでそのコンポーネントをハイライト表示します。
- プレビュー内でコンポーネントをドラッグして、必要に応じて配置を変更します。
異なるviewportでドキュメントを表示する
ドキュメントの作業中、viewportツールバーのさまざまなviewportのアイコンをクリックして、ドキュメントがそれぞれのデバイスでどのように表示されるかを確認できます。viewportプロファイルパッケージで使用できるviewportパッケージに対応する、5つのviewportを使用してプレビューできます。
- 小型デバイス（円形）
- 小型デバイス（横長）
- 中型デバイス
- 大型デバイス
- 超大型TV
viewportのプロパティについて詳しくは、Alexa Viewportプロファイルパッケージを参照してください。
後述のように、カスタムviewportを作成することもできます。
viewportは、すべて画面付きデバイスを表していることに注意してください。Echo Dot with clockなどのキャラクターディスプレイ付きデバイスを表すviewportはありません。
カスタムviewportを作成する
カスタムviewportを作成して、作成したデザインが5つの定義済みプロファイルとは異なるデバイスではどのように表示されるのか、確認することができます。
- プラス記号のアイコンをクリックします。
- 表示するviewportのプロパティを変更します。形状、ピクセル幅、ピクセル高さ、ピクセル密度を設定できます。
- 適用をクリックします。
カスタムviewportは、現在のブラウザのセッション中は引き続き使用できます。ブラウザを閉じて、後でオーサリングツールを再度開くと、カスタムviewportを再作成する必要があります。
スキルでドキュメントを保存する
後で作業を行えるように、ドキュメントをスキルに保存することができます。これはあくまで後の作業のための保存であり、ドキュメントをスキルのバックエンドに関連付けるものではありません。スキルコード内で使用するには、JSONを書き出す必要があります。
ドキュメントを保存するスキルから、オーサリングツールを開いてください。
ドキュメントとデータソースを保存する
- 右上隅にある保存ボタン（）をクリックします。
- プロンプトが表示されたら、ドキュメントの名前を入力します。
-
ドキュメントがスキルに関連付けられていない場合は、ドロップダウンリストからスキルを選択する必要があります。
オーサリングツールをスキル内からではなく、直接リンク（https://developer.amazon.com/alexa/console/ask/displays/?）を使用して開いた場合は、この操作を行う必要があります。
以前に保存したドキュメントを開く
- ドキュメントを保存したスキルを開きます。
- 画面表示をクリックします。
- ドキュメントの一覧から目的のドキュメントを見つけ、編集をクリックします。
ドキュメントを複製する
- ドキュメントを保存したスキルを開きます。
- 画面表示をクリックします。
- ドキュメントの一覧から目的のドキュメントを見つけ、複製をクリックします。
-
ドロップダウンリストからスキルを選択し、複製をクリックします。
ヒント： ドキュメントを複製して同じスキルに保存するには、スキルドロップダウンで現在のスキルを選択したままにします。
ドキュメントとデータソースを書き出す
スキルコードでドキュメントを使用するには、コードを書き出しボタン（）をクリックします。
これにより、ドキュメントとデータがトップレベルにdocumentとdatasourcesのプロパティを持つ1個のJSONファイルに結合されます。オーサリングツール以外で変更を加えた場合は、後でこのファイルを再読み込みできます。
関連トピック
- Alexa Presentation Language（APL）の概要
- ASK SDK v2でのAlexa Presentation Languageの使用
- APLドキュメント
- マルチモーダルなAlexaスキルを開発する方法