APLドキュメントの作成と編集



APLドキュメントの作成と編集

APLドキュメントとは、スキル応答のテンプレートを定義するJSON構造のことです。ドキュメントは視覚応答、オーディオ応答のどちらでも定義できます。

APLドキュメントの作成にはオーサリングツールを使用します。プリビルドのテンプレート、Lottieアニメーション、空のドキュメントのいずれかから作成できます。

APLドキュメントの作成と管理

オーサリングツールでは、視覚応答とオーディオ応答を作成できます。

  • 視覚応答にはAPLドキュメント形式を使用します。RenderDocumentディレクティブでAlexaにドキュメントを送信すると、Alexaはデバイスにコンテンツを表示します。
  • オーディオ応答にはAPLAドキュメント形式を使用します。RenderDocumentディレクティブでAlexaにドキュメントを送信すると、Alexaはドキュメントで生成したオーディオを再生します。

オーサリングツールで視覚応答とオーディオ応答を作成する手順は次のとおりです。

新しい視覚応答を作成する

  1. 開発者コンソールで、このドキュメントを作成するスキルを開きます。
  2. 左側のナビゲーションから、マルチモーダルをクリックします。
  3. 視覚をクリックします。オーサリングツールには、スキルに視覚応答が保存されたAPLドキュメントのみが一覧表示されます。

  4. 視覚応答を作成をクリックします。
  5. ドキュメントの作成方法を選択します。
    • サンプルテンプレートから作成する場合は、レスポンシブ対応テンプレートAPLの機能を表示のいずれかのセクションでテンプレートを探し、使用するテンプレートをクリックします。テンプレートの詳細については、プリビルドのテンプレートを使用するを参照してください。
    • 空白の状態から独自のドキュメントを作成するには、空のドキュメントをクリックします。
    • 既存のJSONドキュメントをインポートするには、アップロードをクリックします。アップロードするドキュメントの形式を設定する方法については、JSONファイルからAPLドキュメントをインポートするを参照してください。
    • 既存のLottieアニメーションをインポートするには、アップロードをクリックします。LottieアニメーションをAPLアニメーションに変換する方法の詳細については、Lottieアニメーションのインポートを参照してください。

    オーサリングツールで新しいドキュメントが開きます。

  6. ドキュメントを更新してプレビューします。以下を参照してください。
  7. 右上隅の保存保存アイコン)をクリックしてスキルにドキュメントを保存します。プロンプトが表示されたら、ドキュメントの名前を入力します。

新しいオーディオ応答を作成する

  1. 開発者コンソールで、このドキュメントを作成するスキルを開きます。
  2. 左側のナビゲーションから、マルチモーダルをクリックします。
  3. オーディオをクリックします。オーサリングツールには、スキルにオーディオ応答が保存されたAPLドキュメントのみが一覧表示されます。

  4. オーディオ応答を作成をクリックします。
  5. ドキュメントを更新してプレビューします。以下を参照してください。
  6. 右上隅の保存保存アイコン)をクリックしてスキルにドキュメントを保存します。プロンプトが表示されたら、ドキュメントの名前を入力します。

既存のドキュメントを管理する

  1. 開発者コンソールで、ドキュメントを保存したスキルを開きます。
  2. 左側のナビゲーションから、マルチモーダルをクリックします。

    新しいウィンドウまたはタブでオーサリングツールが開き、オーディオフィルターが表示されます。

  3. オーディオ視覚のいずれかをクリックすると、既存のドキュメントのリストが表示されます。
  4. ドキュメントのリストから、目的のアクションのリンクをクリックします。
    • 編集 – オーサリングツールでドキュメントを開きます。
    • 複製 – 同じスキルにドキュメントのコピーを作成します。
    • 削除 – ドキュメントを削除します。
    • ダウンロード – ドキュメント、データソース、ソースを含むJSONファイルをダウンロードします。このアクションはドキュメントの書き出しと同じです。詳細については、APLドキュメントのインポートと書き出しを参照してください。

プリビルドテンプレートの使用

視覚応答の場合、オーサリングツールはひな形として使用できるサンプルドキュメントのライブラリを提供します。これらのテンプレートは以下のセクションに整理されています。

  • レスポンシブ対応テンプレート – 画面付きのさまざまなデバイスで見栄え良く表示される全画面のテンプレートです。たとえば、テキストリストテンプレートには、背景とヘッダーを含むテキスト項目のスクロールリストが含まれていますので、データソースに表示するコンテンツを指定するだけで使用できます。
  • APLの機能を表示 – その他のデザインやAPLの可能性を表現する追加のテンプレートです。

各レスポンシブ対応テンプレートは、データソースを使用して、レイアウトで表示されるコンテンツを提供します。テンプレートを選択したら、DATAをクリックしてデータソースを確認します。たとえば、テキストリストには背景画像とリスト項目が含まれます。JSONデータソースのコンテンツを変更して、テンプレートが別のコンテンツでどのように表示されるかを確認できます。

オーサリングツールインターフェースの操作について詳しくは、視覚応答の作成を参照してください。

レスポンシブ対応テンプレートとAPLサンプルのライブラリ
レスポンシブ対応テンプレートとAPLサンプルのライブラリ

視覚応答の作成

オーサリングツールでは、コア機能を含む領域が常に表示されます。

オーサリングツールのメインインターフェース
オーサリングツールのメインインターフェース
UI要素 説明

1

左側のツールバードキュメントのコンポーネントのグラフィカルビュー、ドキュメントとデータソースのJSONコードビューを切り替えます。

2

上部のツールバー — ドキュメントのプレビュー、保存、書き出しを行うためのボタンです。

3

Viewportプロファイルツールバー — プレビューペインを異なるviewport間で切り替えるためのボタンです。Viewportはデバイスタイプ(「デバイス」や「モバイル」など)、viewport(「デバイス、横長、中」など)の順に整理されています。ドロップダウンリストから特定のサンプルデバイスを選択します。詳細については、視覚応答のプレビューを参照してください。

4

サイズ範囲のドロップダウンリスト — サイズ範囲をサポートするviewportプロファイルについて、このリストに範囲内の一般的なデバイスのサイズが表示されます。

5

ドキュメントプレビューペイン — さまざまなviewportでドキュメントがどのように表示されるかを大まかに確認できます。通常のオーサリングモードで、プレビューペインをクリックしてコンポーネントを選択します。コンポーネントをドラッグしてデザインを変更することもできます。タッチイベントやコマンドをテストするには、プレビューモードに切り替えます。詳細については、視覚応答のプレビューを参照してください。

6

コンポーネントパレット — すべてのコアAPLコンポーネントが表示されます。このパレットからプレビューペインに表示されているディスプレイにコンポーネントをドラッグして、ドキュメントを作成できます。

7

Amazon開発者アカウントに関連付けられているデバイスにドキュメントをプッシュするためのメニューです。デバイス名が表示されていることを確認してから、ボタンをクリックして実際のデバイスでドキュメントを確認します。

ツールバーボタン

次の表は、左側のツールバーのオプションをまとめたものです。

ツールバーボタン 説明

GUIツールバーボタン

GUI — レイアウトペインが開き、ドキュメントのコンポーネントのグラフィカルビューが表示されます。

APLツールバーボタン

APLドキュメント全体のJSONコードが表示されます。完全な構文については、APLドキュメントを参照してください。

DATAツールバーボタン

DATAデータソースのJSONコードが表示されます。データソースの完全な構文については、APLデータソースを参照してください。

SOURCESツールバーボタン

SOURCES — ドキュメントでaplAudioToSpeech transformerをテストするのに必要なsourcesのJSONコードが表示されます。APL for Audioトランスフォーマーをテストするを参照してください。

STYLESツールバーボタン

STYLES — ドキュメントのstylesプロパティのJSONコードが表示されます。APLスタイルの定義と評価を参照してください。

DOCUMENTツールバーボタン

DOCUMENTimportプロパティのJSONコードに加えて、トップレベルのドキュメントプロパティも表示されます。

RESOURCESツールバーボタン

RESOURCESresources配列のJSONコードが表示されます。APL Resourcesを参照してください。

GRAPHICSツールバーボタン

GRAPHICSgraphicsプロパティのJSONコードが表示されます。このコードには、ドキュメント内で使用可能なAlexa Vector Graphicsのコレクションを含めることができます。

SETTINGSツールバー

SETTINGSsettingsプロパティのJSONコードが表示されます。このコードには、ドキュメント全体の設定を定義する一連のキーと値のペアを含めることができます。

COMMANDSツールバーボタン

COMMANDScommandsプロパティのJSONコードが表示されます。このコードには、ドキュメント内で使用可能な一連のユーザー定義コマンドを含めることができます。

ONMOUNTツールバーボタン

ONMOUNTonMountプロパティのJSONコードが表示されます。このコードには、ドキュメントが最初に画面に表示されたときに実行される一連のコマンドが含まれます。

レイアウトペインでドキュメントを編集する(GUI)

ツールバーのGUIオプションをクリックすると、レイアウトペインが表示され、コンポーネントとレイアウトが階層ビューで表示されます。このペインには、最初にmainTemplateが表示され、次にlayoutsプロパティで定義したカスタムレイアウトが表示されます。レイアウトペイン内でコンポーネントをドラッグして、階層の配置を変更することもできます。

ペインでコンポーネントまたはレイアウトを選択し、プレビューペインでハイライト表示します。

オーサリングツールのレイアウトペイン
オーサリングツールのレイアウトペイン
UI要素 説明

1

レイアウト — ドキュメント内のすべてのコンポーネントが階層ビューで表示されます。コンポーネントを選択して+ボタンをクリックすると、階層に子コンポーネントを追加できます。

2

コンポーネントのプロパティフォーム — 選択したコンポーネントまたはレイアウトのプロパティを入力します。

mainTemplateまたはカスタムレイアウトにコンポーネントを追加するには

  1. レイアウトペインで、新しいコンポーネントの親になるコンポーネントを選択します。

    mainTemplateContainerなど、子コンポーネントを含むことができるコンポーネントを選択する必要があります。

  2. ペインの右上隅で+ボタンをクリックします。
  3. コンポーネントを選択し、追加をクリックします。

    ドキュメントにカスタムレイアウトが含まれている場合は、コンポーネントの代わりにレイアウトを選択することもできます。

  4. 右側のペインで、新しいコンポーネントのプロパティを編集します。

カスタムレイアウトを作成するには

  1. レイアウトペインで、mainTemplateを選択します。
  2. ペインの右上隅で+ボタンをクリックします。
  3. ドロップダウンリストで、カスタムレイアウトを作成を選択します。
  4. カスタムレイアウト名にカスタムレイアウト名を入力し、追加をクリックします。
  5. 必要に応じて、新しいレイアウトにコンポーネントを追加します。

コンポーネントのプロパティを更新するには

  • 階層のコンポーネントを選択し、レイアウトペインの隣のペインでプロパティ値を編集します。

ドラッグ&ドロップでドキュメントを構築する

ドキュメントのプレビューペインでコンポーネントをクリックしてドラッグすることで、ドキュメントを視覚的に編集できます。

  • コンポーネントパレットでコンポーネントをクリックし、ドキュメントにドラッグします。
  • TextImageVideoコンポーネントを空のプレビューにドラッグすると、オーサリングツールによってコンポーネントが自動的にContainer内に配置されます。
  • ツールバーのGUIをクリックしてからレイアウトペインでコンポーネントをクリックし、プレビューでそのコンポーネントをハイライト表示します。プレビューペインでコンポーネントをクリックしてレイアウトでハイライトすることもできます。
  • プレビュー内でコンポーネントをドラッグして、必要に応じて配置を変更します。

オーディオ応答の作成

オーサリングツールでは、コア機能を含む領域が常に表示されます。

オーディオ応答用のオーサリングツール
オーディオ応答用のオーサリングツール
UI要素 説明

1

左側のツールバー – ドキュメントとデータソースのJSONコードを切り替えるボタンです。

2

上部のツールバー – ドキュメントの保存と書き出しを行うボタンです。

3

編集ペイン – ドキュメントとデータソースのJSONコードの編集を行うペインです。

4

プレビューボタン/プレビューコントロール – オーディオをプレビューするためのボタンです。オーディオ応答のプレビューの詳細は、オーディオ応答をプレビューするを参照してください。

ツールバーボタン

次の表は、左側のツールバーのオプションをまとめたものです。

ツールバーボタン 説明

APLAアイコン

APLA – ドキュメント全体のJSONコードが表示されます。完全な構文については、ドキュメント(APL for Audio)を参照してください。

DATAツールバーボタン

DATAデータソースのJSONコードが表示されます。

APL for AudioドキュメントのJSONコードを更新したら、オーディオを生成してプレビューできます。詳細については、オーディオ応答をプレビューするを参照してください。

ドキュメントとデータソースのJSONコードを編集する

オーサリングツールには、ドキュメントとデータソースのJSONエディターが含まれています。

JSONエディターでは、コンマの配置ミスなど、JSON構文エラーの基本的な検証が行われます。視覚応答の場合、コンポーネントに属さないプロパティを含めると、エディターによって警告が表示されます。

ドキュメントのJSONエディター

APLアイコン APLAアイコン

APLまたはAPLAのツールバーボタンをクリックすると、ドキュメント全体のJSONコードが表示されます。

視覚応答の場合、ツールバーのその他のボタンを使用して、stylesresourcesプロパティなど、ドキュメントの特定の部分のJSONコードを表示して編集することができます。

APLドキュメントの完全な構文については、以下を参照してください。

データソースのJSONエディター

DATAアイコン

DATAツールバーボタンには、ドキュメントのデータソースのJSONコードが表示されます。このエディターを使用して、ドキュメントがデータバインディングを使用してアクセスできるJSON構造を作成します。

各データソースは、中かっこ({})内のトップレベルプロパティであり、データバインディング式でデータソースプロパティを参照するための名前が含まれている必要があります。

以下は、視覚応答の有効なデータソースの例です。

{
  "headlineTemplateData": {
    "type": "object",
    "objectId": "headlineSample",
    "properties": {
      "backgroundImage": {
        "contentDescription": null,
        "smallSourceUrl": null,
        "largeSourceUrl": null,
        "sources": [
          {
            "url": "https://d2o906d8ln7ui1.cloudfront.net/images/templates_v3/headline/HeadlineBackground_Dark.png",
            "size": "large"
          }
        ]
      },
      "textContent": {
        "primaryText": {
          "type": "PlainText",
          "text": "今日の植物トリビアにようこそ"
        }
      },
      "logoUrl": "https://d2o906d8ln7ui1.cloudfront.net/images/templates_v3/logo/logo-modern-botanical-white.png",
      "hintText": "次のように言ってみてください。\"アレクサ、今日の植物トリビアを教えて。\"",
      "welcomeSpeechSSML": "<speak><amazon:emotion name='excited' intensity='medium'>今日の植物トリビアにようこそ</amazon:emotion></speak>"
    },
    "transformers": [
      {
        "inputPath": "welcomeSpeechSSML",
        "transformer": "ssmlToSpeech",
        "outputName": "welcomeSpeech"
      }
    ]
  }
}

ドキュメント内のmainTemplate.parameters配列にpayloadが含まれていれば、${payload.headlineTemplateData.properties.textContent.primaryText.text}構文で、このデータソース内のプロパティを参照することができます。

RenderDocumentディレクティブを使ってドキュメントをAlexaに送信する場合、スキルコードを作成し、データソースをRenderDocumentdatasourcesプロパティに含める必要があります。スキルから実際の応答をレンダリングする際、Alexaがオーサリングツールに保存されたデータソースを使用することはありません。

データソースとデータバインディングの詳細については、以下を参照してください。