APLパッケージリファレンス
APLパッケージは、特定のビューポートでAPLエクスペリエンスをレンダリングするために使用される、APLドキュメントと関連アセットの自己完結型リソースです。APLパッケージを使用すると、ウィジェットのビューポートでレンダリングされるAPLエクスペリエンスを定義できます。ユーザーがデバイスにウィジェットをインストールすると、Alexaによってデバイスにパッケージがインストールされます。デバイスは、パッケージのコンテンツを使用してウィジェットパネルでウィジェットをレンダリングします。
新しいウィジェットを作成すると、ウィジェットのオーサリングツールでAPLパッケージが自動的に作成されます。パッケージは、Alexa Skills Kitコマンドラインインターフェース（ASK CLI）を使用して、ローカルコンピューターにダウンロードできます。詳細については、ASK CLIを使用してAPLパッケージのダウンロードと更新を行うを参照してください。
APLパッケージのマニフェスト
APLパッケージのマニフェストは、パッケージのメタデータを含む必須のJSONファイルです。パッケージのマニフェストは、ウィジェットのオーサリングツールで直接編集できます。
以下の例は、MyNewWidgetという名前のウィジェットのパッケージマニフェストを示しています。
{
"packageVersion": "1.0",
"packageType": "APL_PACKAGE",
"publishingInformation": {
"schemaVersion": "1.0",
"locales": {
"ja-JP": [
{
"targetViewport": "WIDGET_M",
"metadata": {
"name": "ウィジェット名",
"description": "ウィジェットの説明",
"keywords": [
"キーワード1",
"キーワード2"
],
"iconUri": "https://d3ozx4qyxcxwzd.cloudfront.net/default_icon.png",
"previews": [
"https://d3ozx4qyxcxwzd.cloudfront.net/default_preview.png"
]
}
}
]
}
},
"manifest": {
"id": "MyNewWidget",
"version": "1.0.0",
"presentationDefinitions": [
{
"url": "presentations/default.tpl"
}
],
"appliesTo": "${viewport.mode == 'HUB'}"
}
}
以下の表は、APLパッケージのマニフェストにおける最上位プロパティの定義です。
| プロパティ | 型 | 説明 | 必須 |
|---|---|---|---|
|
|
文字列 |
Alexaで定義されたパッケージマニフェストのバージョンです。 |
◯ |
|
|
文字列 |
マニフェストが表すパッケージのタイプです。 |
◯ |
|
|
オブジェクト |
ウィジェットギャラリーでユーザーがパッケージを利用できるロケールを定義するJSONオブジェクトです。プロパティの詳細については、publishingInformationオブジェクトを参照してください。 |
× |
|
|
オブジェクト |
ウィジェットのメタデータを定義するJSONオブジェクトです。プロパティの詳細については、manifestオブジェクトを参照してください。 |
◯ |
publishingInformationオブジェクト
以下の表は、APLマニフェストのpublishingInformationオブジェクトの定義です。
| プロパティ | 型 | 説明 | 必須 |
|---|---|---|---|
|
|
文字列 |
公開情報のスキーマバージョンを定義します。 |
◯ |
|
|
ロケールオブジェクトのマップ |
ロケールオブジェクトのマップです。ロケールごとに、ウィジェットの公開時に使用されるウィジェットのメタデータを定義します。キーには標準のロケール表記（ |
◯ |
|
|
公開情報オブジェクトの配列 |
指定された |
◯ |
|
|
列挙値 |
公開情報が定義されているビューポートです。 |
◯ |
|
|
オブジェクト |
ウィジェットギャラリーでウィジェットを表示するために使用されるメタデータを指定します。 |
◯ |
|
|
文字列 |
パッケージの名前です。ユーザーがウィジェットギャラリーでウィジェットを参照すると、この名前が表示されます。 |
◯ |
|
|
文字列 |
パッケージの説明です。ユーザーがウィジェットギャラリーでウィジェットを選択すると、この説明が表示されます。ウィジェットをインストールした場合に何ができるかをユーザーに説明します。 |
◯ |
|
|
文字列の配列 |
ユーザーがウィジェットを検索しやすくするための、パッケージのキーワードです。 |
◯ |
|
|
文字列 |
パッケージのアイコンのURIです。ユーザーがウィジェットギャラリーでウィジェットを参照すると、このアイコンが表示されます。 アイコンは、サイズが450 x 450ピクセルのPNG画像である必要があります。 |
◯ |
|
|
文字列の配列 |
ウィジェットのプレビュー画像の配列です。ウィジェットでサポートされるウィジェットサイズごとに1つ以上のURIを指定します。文字列は次のサイズの画像に解決されるURIである必要があります。
|
◯ |
locales
以下の表に示すロケールを使用します。
| ロケールコード | 言語 |
|---|---|
|
|
アラビア語（SA） |
|
|
ドイツ語（DE） |
|
|
英語（AU） |
|
|
英語（CA） |
|
|
英語（UK） |
|
|
英語（IN） |
|
|
英語（US） |
|
|
スペイン語（ES） |
|
|
スペイン語（MX） |
|
|
スペイン語（US） |
|
|
フランス語（CA） |
|
|
フランス語（FR） |
|
|
ヒンディー語（IN） |
|
|
イタリア語（IT） |
|
|
日本語（JP） |
|
|
オランダ語（NL） |
|
|
ポルトガル語（BR） |
manifestオブジェクト
以下の表は、APLマニフェストのmanifestオブジェクトの定義です。
| プロパティ | 型 | 説明 | 必須 |
|---|---|---|---|
|
|
文字列 |
パッケージの一意のIDです。大文字と小文字が区別される英数字（ |
◯ |
|
|
文字列 |
パッケージに指定するバージョン番号です。 |
◯ |
|
|
列挙値 |
Alexaがパッケージのインストールリクエストをどのように処理するかを示す列挙値です。
指定しない場合は、デフォルトで |
× |
|
|
列挙値 |
Alexaが新しいバージョンへのパッケージの更新リクエストをどのように処理するかを示す列挙値です。
指定しない場合は、デフォルトで |
× |
|
|
式 |
APLスタイルの条件式です。ウィジェットギャラリーはこの式を使用して、指定されたデバイスにウィジェットを表示するかどうかを決定します。
|
◯ |
|
|
オブジェクトの配列 |
表示するプレゼンテーションテンプレートを定義するオブジェクトの配列です。テンプレートは、 |
◯ |
appliesTo
trueまたはfalseと評価されるAPLスタイルの式を指定します。ウィジェットギャラリーはこの式を使用して、指定されたデバイスにウィジェットを表示するかどうかを決定します。式には、データバインディング構文で説明されている論理演算子と比較演算子を使用できます。
この式では、viewportとlocationを含む限定されたコンテキストにアクセスできます。
| プロパティ | 型 | 説明 |
|---|---|---|
|
|
オブジェクト |
デバイスのビューポートに関するプロパティを指定します。 |
|
|
列挙値 |
ビューポートのモードです。 |
|
|
列挙値 |
ビューポートの形状です。 |
|
|
整数 |
密度非依存ピクセル（dp）単位のビューポートの幅です。値は常に0～3000の範囲の正の整数になります。 |
|
|
整数 |
密度非依存ピクセル（dp）単位のビューポートの高さです。値は常に0～3000の範囲の正の整数になります。 |
|
|
列挙値 |
パッケージをインストールできる場所です。
|
たとえば、${viewport.mode == 'HUB'}という式は、ウィジェットが据え置き型デバイスに表示できることを示しています。
presentationDefinitions
presentationDefinitions配列には、プレゼンテーション定義を識別するオブジェクトが含まれています。プレゼンテーション定義は、表示するAPLドキュメントとデータソースを識別します。
presentationDefinitions配列の各オブジェクトには、プレゼンテーション定義ファイルの場所を識別するurlプロパティが含まれています。この場所は、パッケージのルートディレクトリを基準としています。たとえば、場所がpresentations/default.tplの場合は、パッケージ内にdefault.tplというテンプレートを含むpresentationsというディレクトリがあることを意味します。
ウィジェットでは1つのプレゼンテーション定義ファイルを指定できるため、この配列には項目が1つ含まれている必要があります。
TPLファイルの内容の詳細については、プレゼンテーション定義ファイルの形式を参照してください。
APLパッケージのファイル構造
スキルのAPLパッケージは、スキルの完全なスキルパッケージのサブセットです。スキルパッケージのダウンロードと管理は、ASK CLIを使用して行うことができます。
スキルのAPLパッケージは、スキルパッケージ内のdataStorePackagesフォルダに保存されます。パッケージは、ウィジェットIDを名前としたフォルダです。
以下は、helloWorldResponseという1つの標準APLドキュメントと、MyNewWidgetという1つのウィジェットを持つスキルの、スキルパッケージ構造の例です。
skill-package
├── dataStorePackages
│ └── MyNewWidget
│ ├── datasources
│ │ └── default.json
│ ├── documents
│ │ └── document.json
│ ├── manifest.json
│ └── presentations
│ └── default.tpl
├── interactionModels
│ └── custom
│ └── ja-JP.json
├── response
│ └── display
│ └── helloWorldResponse
│ ├── datasources
│ │ └── default.json
│ ├── document.json
│ └── sources
│ └── default.json
└── skill.json
以下の表は、ウィジェットのフォルダ構造を示しています。
| ファイルまたはフォルダ | 説明 | 必須 |
|---|---|---|
|
|
スキルに関連付けられた各APLパッケージのフォルダが含まれるスキルパッケージ内のフォルダです。 |
◯ |
|
|
特定のパッケージのフォルダです。名前はウィジェットに使用するIDと一致する必要があります。 |
◯ |
|
|
ウィジェットのデータソースを表すJSONファイルを格納するフォルダです。ウィジェットでは、静的データのデータソースを使用します。データソースを含むJSONファイルを用意し、プレゼンテーションテンプレートファイル（ オーサリングツールでウィジェットを作成すると、ツールで指定したデータソースが |
× |
|
|
ウィジェットの表示に使用するAPLドキュメントを格納するフォルダです。ドキュメントを含むJSONファイルを用意し、プレゼンテーションテンプレートファイル（ オーサリングツールでウィジェットを作成すると、ツールで指定したドキュメントが |
◯ |
|
|
APLパッケージのマニフェストファイルです。詳細については、APLパッケージのマニフェストを参照してください。 |
◯ |
|
|
プレゼンテーションファイルを格納するフォルダです。プレゼンテーション定義ファイルは、表示するAPLドキュメントとデータソースを識別します。 オーサリングツールでウィジェットを作成すると、デフォルトのプレゼンテーション定義ファイルが |
◯ |
完全なスキルパッケージの構造の詳細については、スキルパッケージAPIのリファレンスを参照してください。
プレゼンテーション定義ファイルの形式
プレゼンテーション定義ファイルは、TPL拡張子を持つJSONファイルです。ファイル内のJSONオブジェクトには、以下の表に示すフィールドが含まれます。
| プロパティ | 型 | 説明 | 必須 |
|---|---|---|---|
|
|
列挙値 |
ビューポートにレンダリングされるプレゼンテーションを表します。 |
◯ |
|
|
文字列 |
パッケージの一部として作成されたドキュメントを指す、パッケージのルートディレクトリへの相対パスを指定します。 |
◯ |
|
|
文字列 |
パッケージの一部として作成されたデータソースを指す、パッケージのルートディレクトリへの相対パスを指定します。 |
◯ |
以下は、プレゼンテーション定義ファイルの例です。このパッケージには、document.jsonというAPLドキュメントを含むdocumentsディレクトリと、default.jsonという名前のデータソースファイルを含むdatasourcesディレクトリがあります。
{
"type": "APL_PRESENTATION",
"documentUrl": "documents/document.json",
"datasourceUrl": "datasources/default.json"
}
ウィジェットでは1つのプレゼンテーション定義ファイルを指定できます。開発者コンソールで新しいウィジェットを作成すると、単一のAPLドキュメントとデータソースを参照するように設定された、デフォルトのTPLファイルを含むパッケージが作成されます。このファイルを表示するには、ASK CLIを使用してAPLパッケージをダウンロードします。
ASK CLIを使用してAPLパッケージのダウンロードと更新を行う
スキルのスキルパッケージは、ASK CLIを使用してダウンロードできます。APLパッケージはスキルパッケージのサブセットです。
作業を始める前に、以下が手元にあることを確認してください。
- ASK CLIの最新バージョン（コンピューターにインストールされていること）。詳細については、クイックスタート： Alexa Skills Kitコマンドラインインターフェース（ASK CLI）を参照してください。ASK CLIをインストールして設定を行い、開発者アカウントに接続します。
- スキルID。
パッケージをダウンロードするには、export-packageコマンドを使用します。
ask smapi export-package --skill-id {スキルID} -g development
コマンドが完了したら、skill-package/dataStorePackages/{APLパッケージID}フォルダでウィジェットのAPLパッケージを探します。APLパッケージの構造の詳細については、APLパッケージのファイル構造を参照してください。
ローカルの変更をAPLパッケージにアップロードするには、スキルの種類に応じて、ask deployまたはgit pushを使用します。
- Alexa-hostedスキルに変更をアップロードする場合は、
git pushを使用します。 - セルフホストスキルに変更をアップロードする場合は、
ask deployを使用します。
これらのコマンドは、変更をアップロードしてスキルを再ビルドします。ビルドの進行状況を確認するには、ask smapi get-skill-statusコマンドを使用します。
関連トピック
最終更新日: 2025 年 12 月 04 日