APLパッケージでレイアウト、グラフィックスなどのリソースをホストする

APLパッケージでレイアウト、グラフィックスなどのリソースをホストする

再利用可能なレイアウトやグラフィックスなどのリソースのセットを、Alexa Presentation Language（APL）パッケージとして定義できます。このパッケージをインターネット上でホストすると、ほかのAPLドキュメントでもこれらのリソースを使用できます。パッケージは、コードを複製せずに複数のAPLドキュメントで共通の項目を共有したり、スキル応答のコードを単純化してサイズを小さくしたりするために役立ちます。

パッケージをAPLドキュメントとして定義する

パッケージは、APLドキュメントと同じJSON構造を使用します。パッケージではmainTemplateプロパティを省略できます。mainTemplateプロパティが存在しても、パッケージでは無視されます。パッケージの項目は最上位のプロパティとして定義します。

  • commands
  • extensions
  • graphics
  • layouts
  • resources
  • styles

たとえば、layoutsプロパティにレイアウトのセットを定義し、それらのレイアウトをほかのAPLドキュメントで使用できます。

以下は、CircleWithTextというレイアウトを定義するパッケージの例です。

{
  "type": "APL",
  "version": "2024.3",
  "import": [
    {
      "name": "alexa-styles",
      "version": "1.6.0"
    }
  ],
  "layouts": {
    "CircleWithText": {
      "parameters": [
        {
          "name": "backgroundColor",
          "default": "green"
        },
        {
          "name": "textToDisplay",
          "default": "表示するテキストを設定してください。"
        }
      ],
      "items": [
        {
          "type": "Frame",
          "borderRadius": "@shapeCircle",
          "width": "300dp",
          "height": "300dp",
          "backgroundColor": "${backgroundColor}",
          "item": {
            "type": "Text",
            "width": "100%",
            "height": "100%",
            "padding": "@spacingSmall",
            "text": "${textToDisplay}",
            "textAlign": "center",
            "textAlignVertical": "center"
          }
        }
      ]
    }
  }
}

ほかのパッケージをインポートする

パッケージでは、ほかのパッケージをインポートできます。たとえば、alexa-layoutsパッケージで提供されるレスポンシブ対応コンポーネントを使用するカスタムレイアウトを作成できます。標準のAPLドキュメントでパッケージを使用するときと同じように、インポートをimport配列に追加します。

{
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.7.0"
    }
  ]
}

前に示したCircleWithTextの例は、alexa-stylesパッケージをインポートして、スペースと境界線の丸みリソースを使用しています。

import配列でインポートを定義する方法の詳細については、パッケージインポートリストを参照してください。

特定の項目をエクスポートする

パッケージのインポートを通じてほかのドキュメントから使用される項目を定義するには、exportプロパティを使用します。このプロパティは、コードのモジュール性を高めるために1つのレイアウトの定義に複数の「内部」レイアウトを使用しているものの、外部では最終的な「公開」バージョンだけが使用される想定である場合に役立ちます。

オーサリングツールなどのツールは、exportプロパティを使用してドキュメントにエラーがないかどうかをチェックし、エクスポートされた項目を利用可能として表示します。ただし、exportプロパティは参考情報です。パッケージをインポートしたAPLドキュメントは、パッケージに定義されているすべてのリソースにアクセスでき、exportに含まれていないリソースにもアクセスが可能です。

以下の例は、2つのレイアウトを持つパッケージを示しています（簡潔にするために、レイアウトのitemsは省略されています）。

  • CircleWithTextレイアウトは、指定されたテキストを円の中に表示します。
  • ListOfCirclesは文字列の配列を受け取り、CircleWithTextオブジェクトのリストを表示します。
  • この例では、ListOfCirclesレイアウトを明示的にエクスポートして、ListOfCirclesが使用するべきレイアウトであることを示しています。

オーサリングツールでドキュメントを作成する場合、CircleWithTextを直接使用すると、使用を想定されていないレイアウトとしてエラーが表示されます。ただし、APLはそのレイアウトもレンダリングします。

{
  "type": "APL",
  "version": "2024.3",
  "import": [
    {
      "name": "alexa-styles",
      "version": "1.6.0"
    }
  ],
  "export": {
    "layouts": [
      {
        "name": "ListOfCircles",
        "description": "円のリストです。テキストと背景色を指定してください。"
      }
    ]
  },
  "layouts": {
    "ListOfCircles": {
      "parameters": [
        {
          "name": "textItems",
          "type": "array"
        },
        {
          "name": "defaultColor",
          "type": "string",
          "default": "purple"
        }
      ],
      "items": []
    },
    "CircleWithText": {
      "parameters": [
        {
          "name": "backgroundColor",
          "default": "green"
        },
        {
          "name": "textToDisplay",
          "default": "表示するテキストを設定してください。"
        }
      ],
      "items": []
    }
  }
}

パッケージをホストする

ほかのAPLドキュメントでパッケージを使用するには、インターネット上でパブリックにJSONファイルをホストする必要があります。パッケージをホストするには、アマゾンウェブサービス（AWS）S3などのサービスを利用できます。ホストされるパッケージは、以下の要件を満たす必要があります。

  • JSONファイルへのリンクが完全にパブリックであること。
  • ホストのCross-Origin Resource Sharing（CORS）が*.amazon.comを許可していること。
  • JSONファイルに有効期限がないこと。

Amazon S3に保存されているオブジェクトをパブリックにする

Amazon S3のパッケージへのリンクをパブリックにするには、バケットポリシーを追加してアクセスを付与します。詳細については、ウェブサイトアクセスのアクセス許可の設定を参照してください。

または、AWS CloudFrontを使ってパッケージをアクセス可能にすることができます。ただし、ダイレクトS3 URLへのアクセスは制限します。以下のAWSリソースを参照してください。

S3 CORSポリシーを設定する

S3バケット上の以下のCORSポリシーにより、Alexaデバイスからパッケージにアクセスできるようになります。

[
    {
        "AllowedHeaders": [],
        "AllowedMethods": [
            "GET"
        ],
        "AllowedOrigins": [
            "*.amazon.com"
        ],
        "ExposeHeaders": []
    }
]

S3バケットでCORSを設定する方法の詳細については、Cross−Origin Resource Sharing（CORS）の使用を参照してください。

パッケージをドキュメントにインポートする

外部パッケージを使用するには、パッケージをインポートします。sourceプロパティにパッケージのパブリックURLを指定します。versionとnameには、パッケージに合った文字列を設定します。これらのプロパティは必須ですが、パッケージの実際のコンテンツと一致する必要はありません。便宜上、一貫した命名規則を使用してください。たとえば、JSONファイル名をパッケージ名として使用します。

{
  "import": [
    {
      "name": "circle-list",
      "version": "1.0",
      "source": "https://d111111abcdef8.cloudfront.net/circle-list.json"
    }
  ]
}

複数のパッケージをインポートできます。たとえば、ドキュメントがレスポンシブ対応コンポーネントだけでなくカスタムパッケージのレイアウトも使用している場合、独自のパッケージとalexa-layoutsの両方をインポートします。インポートの条件を定義して、どのパッケージをインポートするかを制御することもできます。

import配列でインポートを定義する方法の詳細については、パッケージインポートリストを参照してください。

パッケージの例

以下は、Lottieからインポートしたグラフィックを定義する外部パッケージの例です。

以下は、このパッケージをインポートしてAPLドキュメント内でグラフィックを使用する方法の例です。この例で示したCloudFront URLは架空のものです。

{
  "type": "APL",
  "version": "2024.3",
  "import": [
    {
      "name": "my-lottie-graphics",
      "version": "1.0",
      "source": "https://d111111abcdef8.cloudfront.net/my-lottie-graphics.json"
    }
  ],
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": {
      "type": "VectorGraphic",
      "source": "blockTowerAnimation",
      "width": "100%",
      "height": "100%",
      "scale": "best-fit",
      "align": "center",
      "frame": "${(elapsedTime*0.06)%360}"
    }
  }
}

外部パッケージのトラブルシューティング

問題： パッケージを取得しようとすると403エラーが発生する

現象

パッケージで指定されているリソースにAPLドキュメントからアクセスできません。オーサリングツールは、「Request failed with status code 403」エラーを報告します。

解決方法

このエラーは通常、パッケージURLへのリンクがパブリックアクセス可能でないことを示します。ブラウザでリンクをテストし、JSONファイルのコンテンツを表示できることを確認してください。

ファイルをパブリックアクセス可能にする手順は、パッケージをホストしている方法によって異なります。Amazon S3の場合は、CloudFrontを使用してリソースへのアクセスを提供することを検討してください。以下は参考資料です。

問題： リソースが見つからない

現象

パッケージはパブリックアクセス可能ですが、パッケージで指定されているリソースにAPLドキュメントからアクセスできません。たとえば、オーサリングツールは「Unable to find layout <レイアウト名>」というエラーを報告します。

解決方法

アップロードしたパッケージが有効なAPLドキュメントであることを確認してください。APLドキュメントがファイルの最上位にあり、ほかのプロパティ内に入っていないようにします。オーサリングツールの書き出し機能では、ドキュメント、データソース、ソースが、document、datasources、sourcesの各プロパティを持つ1つのJSONファイルに保存されます。この形式は、APLドキュメントとして有効ではありません。

たとえば、書き出されたAPLドキュメントは次のようになります。

{
  "document": {
    "type": "APL",
    "version": "1.8",
    "settings": {},
    "theme": "dark",
    "import": [],
    "resources": [],
    "styles": {},
    "onMount": [],
    "graphics": {},
    "commands": {},
    "layouts": {
      "ListOfCircles": {},
      "CircleWithText": {}
    },
    "mainTemplate": {
      "parameters": [
        "payload"
      ],
      "items": []
    }
  },
  "datasources": {},
  "sources": {}
}

これを有効なパッケージにするには、documentプロパティに割り当てられているオブジェクトを最上位に移動し、datasourcesとsourcesのプロパティを削除します。

{
  "type": "APL",
  "version": "1.8",
  "settings": {},
  "theme": "dark",
  "import": [],
  "resources": [],
  "styles": {},
  "onMount": [],
  "graphics": {},
  "commands": {},
  "layouts": {
    "ListOfCircles": {},
    "CircleWithText": {}
  },
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "items": []
  }
}

解決方法

Cross-Origin Resource Sharing（CORS）が*.amazon.comを許可するように設定されていることを確認します。

Amazon S3とAmazon CloudFrontを使用している場合、CORSの設定については以下のリンクを参照してください。

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

最終更新日: 2025 年 12 月 02 日