APLパッケージ

APLパッケージ

Alexa Presentation Language（APL）パッケージは、APLドキュメントにインポートできるレイアウト、リソース、スタイルのコンテナーです。APLパッケージは、APLドキュメント構造に従うJSONファイルです。パッケージでmainTemplateプロパティは使用しませんが、このプロパティを含めてもパッケージが無効になることはありません。

独自のパッケージを作成してドキュメントで使用できるようホストする方法の例については、APLパッケージでレイアウト、グラフィックスなどのリソースをホストするを参照してください。

APL向けAlexaデザインシステムには、スタイルやプリビルドレイアウトに使えるパッケージのセットが用意されています。詳細については、APL向けAlexaデザインシステムを参照してください。

パッケージリファレンス

パッケージリファレンスは、パッケージの名前、必要なバージョン、およびオプションでパッケージのソースを定義するデータレコードです。パッケージリファレンスは、ドキュメントにインポートするパッケージのリストを定義する場合や、インポートするパッケージをImportPackageコマンドで定義する場合に使用します。

基本的なパッケージリファレンスには、次の表に示すプロパティがあります。

プロパティ 型 デフォルト 説明

accept

文字列

version

許容されるパッケージバージョンの範囲です。APL 2024.3以降でサポートされます。

name

文字列

必須

インポートの名前です。

source

URL

—

パッケージのダウンロード元のURLです（指定した場合）。

version

文字列

必須

インポートのバージョンです。

パッケージは、2つの方法のいずれかでダウンロードされます。

  • sourceプロパティを指定すると、ドキュメントは指定されたソースURLからパッケージをダウンロードします。
  • sourceプロパティを指定していない場合、ドキュメントは、パッケージ名とバージョンのプロパティを使用して、Alexaがサポートするパッケージの中央リポジトリからパッケージを取得します。Amazonが提供するパッケージのセットについては、APL向けAlexaデザインシステムを参照してください。

パッケージで定義されているリソース、スタイル、レイアウトには、現在のパッケージからアクセスできます。

デバイスランタイムソフトウェアは、パッケージをキャッシュします。デバイスは、2つのパッケージのnameとversionのプロパティが一致する場合、それらを同一であるとみなします（特定の異なるsourceプロパティを持つ場合でも同様です）。パッケージの有効期限（TTL）は、ダウンロード中に受け取ったTTLによって決まります。パッケージの開発やテストを行う際、パッケージを変更するたびに固有のプレリリースタグやビルドタグを割り当ててください。これにより、ランタイムはテスト中にキャッシュしたバージョンのパッケージを使うのではなく、新しいバージョンをリロードします。

accept

acceptを使用するには、APL 2024.3以降に更新する必要があります。これよりも古いバージョンのAPLを実行しているデバイスには、別のエクスペリエンスを提供してください。

このパッケージで許容されるversionの範囲を指定します。APLランタイムでは、リクエストしたパッケージのコピーが既に存在していても、バージョン番号が異なる場合があります。パッケージのバージョン番号がacceptのバージョンの範囲と一致する場合、新しいコピーは読み込まれず、そのパッケージが使用されます。

accept構文は、セマンティックパターンの照合に使用される通常の範囲構文を簡略化したものです。各simple_rangeは演算子であり、1つのセマンティックバージョンです（例：>=1.1.3）。複数のsimple_rangeパターンはスペースで区切られ、ブール演算の「and」で結合されます。明示的なブール演算の「or」で、互いに排他的な範囲を指定できます。

以下はacceptの一般的な条件の例です。

>=1.1.3 <1.2.3      # 1.1.3以上1.2.3未満
>=1.4.0 <2.0        # メジャー番号が1の、1.4.0以上の全バージョン
>=1.1.0-0 <1.1.0    # プレリリース要素を1つ以上含む1.1.0の全バージョン

パッケージ順序の比較は、標準的なセマンティック規則に従います。

  • versionのbuild情報は無視されます（例：1.3.2+alpha.6 == 1.3.2）。
  • バージョンの最初の3つの数字（メジャー番号、マイナー番号、パッチ番号）が数値的に比較されます（例：1.2 < 1.4.3、2.0.0 > 1.99.999-alpha.44）。
  • メジャー番号、マイナー番号、パッチ番号が一致する場合、prereleaseのあるバージョンは常にprereleaseのないバージョンよりも前になります（例：1.1-alpha < 1.1.0）。
  • prereleaseデータを比較する場合は、ドットで区切られた各要素を個別に比較します。numberの値は数値として比較され、identifierの値は文字列として比較されます。numberの値は常にidentifierの値よりも小さくなります（例：1.0.0-alpha < 1.0.0-beta、2.1-134 > 2.1.0-99、1.3.2-alpha.23425 < 1.3.2-alpha.b16）。
  • prereleaseの2つの要素リストが一致していても、長さが異なる場合は、短いリストが前になります（例：2.1.0-alpha.16.beta < 2.1.0-alpha.16.beta.2）。

prereleaseの値があるセマンティックバージョンは、一致するメジャー、マイナー、パッチの各バージョンとprereleaseタグを含むsimple_rangeが、範囲に明示的に指定されている場合にのみ一致します。次に例を示します。

パッケージ： 2.0.3、2.1.0-alpha.1、2.1.0-beta.1、2.1.1-beta.1、2.1.1

>2                          =>  2.0.3、2.1.1
>2.1.0-beta                 =>  2.1.0-beta.1、2.1.1
>2 || >2.1.0-a              =>  2.0.3、2.1.0-alpha.1、2.1.0-beta.1、2.1.1
>2 <2.1.1 || 2.1.1-beta.1   =>  2.0.3、2.1.1-beta.1

acceptプロパティでは、次の文法規則がサポートされます。

accept       ::=  and_list ( ws* "||" ws* and_list )*
and_list     ::=  simple_range ( ws+ simple_range )*
simple_range ::=  ( "<" | ">" | "<=" | ">=" | "=" )? version
ws           ::=  [ \n\t\f]

versionプロパティは、versionプロパティの文法規則で定義されます。acceptプロパティが設定されていない場合は、パッケージのversionプロパティが完全に一致する必要があります。

name

パッケージ名は、[a-zA-Z][a-zA-Z0-9-]*の形式にします。

source

sourceプロパティが指定されている場合は、パッケージのダウンロード元URLの場所を示します。指定されていない場合は、Alexaがサポートする中央リポジトリからパッケージを取得します。Amazonが提供するパッケージのセットについては、APL向けAlexaデザインシステムを参照してください。

パッケージのソースURLには、httpではなくhttpsを使用します。セキュリティ上の理由から、多くのAlexaデバイスでは、スキルのAPLドキュメントでhttpスキームはサポートされません。

Amazon S3などのサイトで独自のAPLパッケージをホストする場合、HTTPSエンドポイントでホストするすべてのAPLリソースに対してCross-Origin Resource Sharingが有効になっていることを確認してください。独自のパッケージを作成してホストする方法の詳細については、APLパッケージでレイアウト、グラフィックスなどのリソースをホストするを参照してください。

version

パッケージバージョンは、次の文法で指定されたセマンティックバージョニング規則に従う必要があります。

vers         ::= <<release>> <<prerelease>>? <<build>>?
release      ::= <<number>> "." <<number>> "." <<number>>
prerelease   ::= "-" <<identifier>> ( "." <<identifier>> )*
build        ::= "+" <<identifier>> ( "." <<identifier>> )*
identifier   ::= [a-zA-Z0-9-]+
number       ::= [0-9] | [1-9][0-9]+

releaseの値の形式はMAJOR.MINOR.PATCHです。MINOR番号またはPATCH番号を省略した場合は、0とみなされます。ただし、パッケージキャッシュの実装における潜在的な問題を回避するために、ベストプラクティスとして、完全なMAJOR.MINOR.PATCH形式を使用することをお勧めします。

有効なパッケージバージョンの例には、 10.2.1、0.1.10-beta.3、0.9.7-alpha2.17+build.1002などがあります。

パッケージインポートリスト

APLのドキュメントとパッケージには、現在のドキュメントまたはプロパティよりも先に読み込むべきパッケージを定義するimportプロパティがあります。ランタイムシステムでは、インポートされたパッケージが最初に読み込まれることが保証されます。読み込みに失敗すると、ドキュメント全体が失敗します。

パッケージのインポートにより、有向依存関係図が形成されます。リソース、スタイル、レイアウトの検索は、パッケージのインポート順に従って深さ優先で行われます。たとえば、ドキュメントAがパッケージBとCに依存し、パッケージBとCがパッケージDに依存しているとします。この場合、リソースの定義の検索順序はA、B、C、Dです。したがって、ドキュメントAは、B、C、Dで定義されたどのリソース、スタイル、レイアウトも上書きできます。

依存関係図では、loadAfterプロパティを使用してパッケージの順序を制御できます。前の例では、依存関係図でBとCの間の順序は指定されていません。loadAfterプロパティを使用すると、特定の順序を適用できます。

importプロパティでは、データバインディングがサポートされます。importプロパティ内のデータバインディング式で、初期状態のデータバインディングコンテキストで使用可能なプロパティにアクセスできます。詳細については、初期状態のデータバインディングコンテキストを参照してください。

基本的なパッケージインポートリストは、パッケージリファレンスの配列です。以下は、APLドキュメントのimportプロパティの例です。このimportでは、alexa-layoutsとmy-custom-stuffという2つのパッケージが指定されています。

{
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.7.0"
    },
    {
      "name": "my-custom-stuff",
      "version": "1.1.0-alpha",
      "source": "https://example.com/packages/"
    }
  ]
}

ドキュメントがインフレートされると、データバインディングコンテキストのpackages環境プロパティには、読み込まれたすべてのパッケージの配列が格納されます。これを使用して、より複雑なパッケージの読み込み操作をデバッグできます。

より複雑なインポートをサポートするために、インポートリストではパッケージの指定用に次の追加オプションがサポートされています。

  • リッチパッケージセレクター（packageタイプ）- 1つのパッケージを読み込み、そのパッケージをほかのパッケージと比較して順序付けをサポートします。

    この構文は、2023.3より前のバージョンのAPLにおけるパッケージインポートと同等です。2023.3より前のバージョンでは、loadAfter、type、whenの各プロパティはサポートされません。2024.3より前のバージョンでは、acceptプロパティはサポートされません。

  • 配列パッケージセレクター（allOfタイプまたはoneOfタイプ）- パッケージセレクターのリスト、およびそれらのセレクターの1つまたはすべてを読み込むための述部を定義します。

リッチパッケージセレクター

リッチパッケージセレクターは、1つのパッケージを条件付きで読み込み、そのパッケージをほかのパッケージと比較して読み込みの順序付けをサポートします。リッチパッケージセレクターには、次の表に示すプロパティがあります。

プロパティ 型 必須 説明

accept

文字列

version

パッケージのacceptプロパティです（APL 2024.3以降）。

loadAfter

配列

[]

このインポートの後に読み込まれるインポート名のリストです（APL 2023.3以降）。

name

文字列

必須

パッケージのnameプロパティです。

source

URL

—

（オプション）パッケージのsourceプロパティです。

type

文字列

package

ポリモーフィックなタイププロパティです。リッチパッケージセレクターを使用する場合は、packageに設定します（APL 2023.3以降）。

version

文字列

必須

パッケージのversionプロパティです。

when

ブール値

true

falseの場合、このインポートは無視されます（APL 2023.3以降）。

以下は、すべてのプロパティが定義された完全修飾パッケージインポートの例です。この例にはtypeプロパティが含まれていますが、typeプロパティが指定されていない場合はデフォルトでpackageになるため、必須ではありません。

{
  "import": [
    {
      "type": "package",
      "when": "${viewport.mode == 'hub'}",
      "loadAfter": [
        "alexa-layouts"
      ],
      "name": "MyDisplayColors",
      "version": "1.2.2-release12",
      "source": "https://mycompany.com/packages"
    },
    {
      "name": "alexa-layouts",
      "version": "1.7.0"
    }
  ]
}

loadAfter

このインポートが読み込まれる前に同じインポートブロックに読み込まれるインポートのセットを識別します。nameと同じパターンに従います。この配列にはパッケージ名がリストされ、パッケージのバージョンは指定されません。したがって、配列で指定されたパッケージは、インポート配列内のほかの場所で定義する必要があります。

循環的な依存関係があると、ドキュメントの処理が失敗します。

when

trueの場合、パッケージが含められます。falseの場合、このパッケージは無視されます。

以下は、whenを使用して環境に応じてデフォルトスタイルをカスタムスタイルでオーバーライドする方法の例です。

"import": [
  {
    "when": "${environment.overrideName && environment.overrideVersion}",
    "name": "${environment.overrideName + viewport.mode}",
    "version": "${environment.overrideVersion}",
    "loadAfter": "default-styles"
  },
  {
    "name": "default-styles",
    "version": "1.0"
  }
]

配列パッケージセレクター

配列パッケージセレクターは、パッケージセレクターのリスト、およびそれらのセレクターの1つまたはすべてを読み込むための述部を定義します。配列パッケージセレクターでは、次の表に示すプロパティがサポートされます。

プロパティ 型 デフォルト 説明

accept

文字列

version

パッケージのacceptプロパティです。

items

配列

必須

パッケージセレクターの配列です。

loadAfter

配列

[]

このインポートの後に読み込まれるインポート名のリストです。

name

文字列

—

パッケージのnameプロパティです。

otherwise

配列

[]

items配列で何も選択されなかった場合に処理するパッケージの配列です。

type

文字列

allOf、oneOfのいずれか

ポリモーフィックなタイププロパティです。

version

文字列

—

パッケージのversionプロパティです。

when

ブール値

true

falseの場合、このインポートは無視されます。

allOfタイプは、items配列のすべてのパッケージをインポートします。oneOfタイプは、whenがtrueであるitems配列内の最初のパッケージをインポートします。

配列パッケージセレクターのaccept、name、versionの各プロパティは、基盤となるパッケージセレクターに渡され、特に定義されていない場合はそこで使用されます。これにより、より簡潔な表記が可能になります。

{
  "import": [
    {
      "type": "oneOf",
      "name": "my-layouts",
      "items": [
        {
          "when": "${viewport.type == 'hub'}",
          "version": "1.1.5",
          "accept": ">=1.1.5 <1.2"
        },
        {
          "version": "1.1.2"
        }
      ]
    }
  ]
}

allOfタイプは、複数のパッケージを条件付きで含める場合に便利です。次の例では、デバイスのviewport.modeがhubの場合に、hub-stylesとhub-overridesの両方のパッケージをインポートします。

{
  "import": [
    {
      "type": "allOf",
      "when": "${viewport.mode == 'hub'}",
      "items": [
        {
          "name": "hub-styles",
          "version": "1.0"
        },
        {
          "name": "hub-overrides",
          "version": "1.0",
          "loadAfter": [ "hub-styles" ]
        }
      ]
    }
  ]
}

oneOfの配列パッケージセレクターは、同じパッケージ名とバージョンを維持しながら、別のsourceからパッケージの内容を読み込む場合に便利です。次の例では、ドキュメントはviewport.modeの値に応じて、3つの異なるソースのそれぞれからstylesというパッケージをインポートします。

{
  "import": [
    {
      "type": "oneOf",
      "name": "styles",
      "version": "1.0",
      "items": [
        {
          "when": "${viewport.mode == 'hub'}",
          "source": "https://styles.com/hub.json"
        },
        {
          "when": "${viewport.mode == 'tv'}",
          "source": "https://styles.com/tv.json"
        },
        {
          "source": "https://styles.com/generic.json"
        }
      ]
    }
  ]
}

oneOfタイプでは、itemsリスト内のインポートがどれも選択されていない場合にインポートする、特別なパッケージのotherwise配列がサポートされます。これは、複雑にネストされたパッケージセレクターにおいて、確実なフォールバックとして役立ちます。

{
  "import": [
    {
      "type": "oneOf",
      "name": "styles",
      "items": [
        {
          "when": "${viewport.mode == 'hub'}",
          "type": "oneOf",
          "version": "1.0",
          "items": [
            {
              "when": "${viewport.width > viewport.height}",
              "source": "https://styles.com/hub-landscape.json"
            },
            {
              "source": "https://styles.com/hub-portrait.json"
            }
          ]
        },
        {
          "when": "${viewport.mode == 'tv'}",
          "version": "1.0",
          "source": "https://styles.com/tv.json"
        }
      ],
      "otherwise": [
        {
          "source": "https://styles.com/generic.json"
        }
      ]
    },
    {
      "name": "overrides",
      "version": "1.0"
    }
  ]
}

このページは役に立ちましたか？

最終更新日: 2025 年 11 月 11 日