APLデータソース

APLデータソース

データソースは、Alexa Presentation Language（APL）ドキュメントにバインドできるデータを定義するJSON構造です。RenderDocumentディレクティブを使用してAPLドキュメントをAlexaに送信するときに、1つ以上のデータソースを含めることができます。データソースをバインドするには、APLドキュメントのパラメーターにデータソースを含めます。その後で、データバインディング式を使用して、データをドキュメント内のコンポーネントプロパティにバインドできます。

RenderDocumentディレクティブでデータソースを送信する

Alexaにデータソースを渡すには、オプションのdatasourcesオブジェクトを使用します。datasourcesオブジェクトはRenderDocumentディレクティブの一部ですが、APLドキュメントには含まれません。datasourcesオブジェクトは、各データソースを表すオブジェクトを格納します。

以下は、RenderDocumentディレクティブを使用するスキル応答の例です。これにより、ドキュメントとmyDocumentDataという名前のデータソースがAlexaに渡されます。簡潔にするために、この例ではドキュメントのコンテンツ全体は省略しています。

{
  "version": "1.0",
  "response": {
    "outputSpeech": {
      "type": "SSML",
      "ssml": "<speak>これはサンプルです</speak>"
    },
    "sessionAttributes": {},
    "directives": [
      {
        "type": "Alexa.Presentation.APL.RenderDocument",
        "token": "[SkillProvidedToken]",
        "document": {
          "type": "APL",
          "version": "2024.3",
          "mainTemplate": {
            "parameters": [
              "myDocumentData"
            ],
            "items": []
          }
        },
        "datasources": {
          "myDocumentData": {
            "title": "基本的なデータソース内のタイトルフィールドの例"
          }
        }
      }
    ]
  }
}

データソースをドキュメントにバインドする

データソースのデータをAPLドキュメントのコンポーネントプロパティにバインドするには、データバインディング式を使用します。

データソースのデータをドキュメントのコンポーネントプロパティにバインドするには

  1. mainTemplate.parameters配列で、データソースオブジェクトのキーと一致するパラメーターを宣言します。
  2. コンポーネントプロパティで、${dataSourceName.propertyName}という構文を使用してデータソースのプロパティを参照します。dataSourceNameはmainTemplate.parametersで使用したキーと同じです。

たとえば、次のデータソースオブジェクトがあるとします。

{
  "myDocumentData": {
    "title": "基本的なデータソース内のタイトルフィールドの例"
  }
}

このデータソースのキーはmyDocumentDataです。mainTemplate.parametersで、パラメーターmyDocumentDataを宣言します。

{
  "type": "APL",
  "version": "2024.3",
  "mainTemplate": {
    "parameters": [
      "myDocumentData"
    ],
    "items": []
  }
}

次に、データバインディング式を使用して、コンポーネントプロパティをmyDocumentDataのデータにバインドします。プロパティにアクセスするには、myDocumentDataキーを使用します。たとえば、${myDocumentData.title}という式は「基本的なデータソース内のタイトルフィールドの例」という値に解決されます。

以下は、myDocumentData.titleプロパティのコンテンツをテキストコンポーネントに表示するAPLドキュメントの例です。

{
  "type": "APL",
  "version": "2024.3",
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.7.0"
    }
  ],
  "mainTemplate": {
    "parameters": [
      "myDocumentData"
    ],
    "items": [
      {
        "type": "Container",
        "width": "100vw",
        "height": "100vh",
        "items": [
          {
            "type": "Text",
            "text": "${myDocumentData.title}"
          }
        ]
      }
    ]
  }
}

payloadまたはその他のパラメーターへのデータソースのバインドについて

1.3より前のバージョンのAPLでは、データソースのキーをmainTemplate.parametersのパラメーターとして使用することはできませんでした。代わりに、"payload"などの文字列をパラメーターに設定し、そのpayloadパラメーターを、スキル応答で提供されるdatasourcesオブジェクト全体にマッピングしていました。次に、データバインディング式にこのパラメーターを含める必要がありました。たとえば、上の例のtitleプロパティを取得する式は${payload.myDocumentData.title}のようになります。

「payload」をmainTemplate.parametersとして使用するドキュメントは、現在も引き続き機能します。ただし、新しいAPLドキュメントでは簡略化された形式を使用することをお勧めします。その他の文字列をパラメーターとして使用した場合は機能しません。「payload」かデータソースキーのいずれかを使用する必要があります。

データソースの型

APLは、型指定ありと自由形式（型指定なし）のデータソースをサポートしています。

  • 自由形式（型指定なし） - 開発者が定義する任意のプロパティのセットを持つJSONオブジェクトです。前述のmyDocumentDataの例は、自由形式データソースの例です。
  • 型指定あり - Alexa Skills Kitで定義された構造を持つJSONオブジェクトです。一部の機能では、型指定ありのデータソースを使用する必要があります。APLは、型指定ありの3つのデータソースをサポートしています。
    • object - トランスフォーマーを使用してデータを操作する場合に必要です。たとえば、SSMLテキストを音声に変換したり、デバイスに設定されているウェイクワードを含むヒントを作成したりする場合に使用されます。
    • dynamicIndexList - 遅延読み込みを使用して、ユーザーのスクロールに応じてデータを段階的に読み込む場合や、ドキュメントのレンダリング後にデータソースを変更する場合に必要です。
    • dynamicTokenList - トークンベースの遅延読み込みを使用して一度に1ページ分のデータを読み込む場合に必要です。

objectデータソース

objectデータソース型は、トランスフォーマーに必要なプロパティを追加します。データを操作するにはトランスフォーマーを使用します。たとえば、トランスフォーマーを使用して、ユーザーのデバイスに設定されたウェイクワードをヒント文字列に挿入できます。

objectデータソースには次のプロパティがあります。

プロパティ 型 必須 説明

type

オブジェクト

◯

「object」に設定する必要があります。

properties

オブジェクト

×

トランスフォーマーで使用できるプロパティを含むオブジェクトです。トランスフォーマーは常に、データはpropertiesオブジェクトに含まれていると想定しています。properties内のデータの構造は開発者が定義します。

objectID

文字列

×

（任意）objectデータソースの識別子です。

description

文字列

×

（任意）データソースの説明です。

transformers

配列

×

propertiesオブジェクト内の値に適用するトランスフォーマーの配列です。

objectデータソースにはその他の任意のプロパティを含めることもでき、必要に応じてそれらをドキュメントにバインドできます。

以下は、propertiesオブジェクトと任意のプロパティ（hello）の両方にデータを含むobjectデータソースの例です。データソースにはtextToSpeechトランスフォーマーも含まれています。トランスフォーマーはpropertiesオブジェクト内のデータを参照します。トランスフォーマーの使用方法の詳細については、トランスフォーマーを参照してください。

{
  "myDocumentData": {
    "type": "object",
    "properties": {
      "title": "これはとても単純な例です。",
      "mainText": "これらのプロパティは<code>properties</code>オブジェクトにあります。"
    },
    "hello": "ハローワールド"
    "transformers": [
      {
        "inputPath": "title",
        "outputName": "titleSpeech",
        "transformer": "textToSpeech"
      }
    ]
  }
}

動的なデータソース

APLは、2種類の動的なデータソースをサポートしています。動的データソースを使用すると、データソースをAlexaに送信した後で更新することが可能になります。このため、完全に新しいドキュメントを送信することなく画面上の値を変更できます。これらのデータソースは遅延読み込みにも対応しています。遅延読み込みを有効にした場合、Alexaは、ユーザーがコンテンツをスクロールするにつれて大きいリストを段階的に表示します。

動的なデータソースには、次の2種類があります。

  • dynamicIndexList - インデックスを使用して項目を追跡します。ユーザーはリストの任意の場所にスクロールできます。
  • dynamicTokenList - トークンを使用して項目を追跡します。ユーザーは一度に1ページずつ前後にスクロールできます。

dynamicIndexListデータソース

dynamicIndexListデータソースは、遅延読み込みと動的データソースに必要なプロパティを追加します。

次の表は、dynamicIndexListデータソースのプロパティです。

プロパティ 型 必須 説明

type

文字列

◯

dynamicIndexListに設定する必要があります。

listId

文字列

◯

同じAPLドキュメント内のデータソースを区別するための識別子です。

startIndex

整数

◯

items配列内の先頭項目のインデックスです。任意のオフセットからエクスペリエンスを開始するには、0以外の値を指定します。たとえば、連絡先のアルファベット順のリストを、「M」で始まる名前から表示できます。

minimumInclusiveIndex

整数

×

配列の最初の項目のインデックスです（インデックスはこの値を含みます）。minimumInclusiveIndexがstartIndexより小さい場合、リストは逆方向スクロールリストになります。指定しない場合、リストは逆方向にスクロールできますが、配列の最初のインデックスは不明になります。ユーザーが逆方向にスクロールしたときにリストがそれ以上項目を読み込まないようにするには、このプロパティを明示的にstartIndexプロパティと等しく設定します。

maximumExclusiveIndex

整数

×

配列の最後のインデックスです（インデックスはこの値を含みません）。設定しない場合、リストは正方向スクロールリストになりますが、配列の最後のインデックスは不明になります。ユーザーが正方向にスクロールしたときにリストがそれ以上項目を読み込まないようにするには、このプロパティを明示的に項目の配列の最後のインデックス+1に設定します。たとえば、200項目にわたる正方向スクロールエクスペリエンスを作成するには、startIndexとminimumInclusiveIndexを0、maximumExclusiveIndexを200に設定します。0から199までのすべての項目が読み込まれると、Alexaはそれ以上の項目をスキルに要求しなくなります。

items

配列

×

最初にレンダリングする項目のオブジェクトデータの配列です。表示する最初の要素は、startIndexのインデックスに位置している必要があります。Alexaは、リストの表示領域の左上に最初の項目を表示します。

以下は、最初に10個の項目を表示するdynamicIndexListデータソースの例です。ユーザーが正方向にスクロールすると、Alexaは、200個の項目がすべて読み込まれるまで続きの項目を要求します。

{
  "dynamicSourceExample": {
    "type": "dynamicIndexList",
    "listId": "my-list-id",
    "startIndex": 0,
    "minimumInclusiveIndex": 0,
    "maximumExclusiveIndex": 200,
    "items": [
      {"primaryText":"項目1"},
      {"primaryText":"項目2"},
      {"primaryText":"項目3"},
      {"primaryText":"項目4"},
      {"primaryText":"項目5"},
      {"primaryText":"項目6"},
      {"primaryText":"項目7"},
      {"primaryText":"項目8"},
      {"primaryText":"項目9"},
      {"primaryText":"項目10"}      
    ]
  }
}

dynamicTokenListデータソース

dynamicTokenListデータソースには、次の表に示すプロパティがあります。

プロパティ 型 必須 説明

propertyName

文字列

◯

dynamicTokenListに設定する必要があります。

listId

文字列

◯

同じAPLドキュメント内のデータソースを区別するための識別子です。

pageToken

文字列

◯

データソースに含まれる項目に関連付けられるトークンです。pageTokenに使用する文字列は開発者が決定します。スキルでは、トークンに関連付けられたデータを追跡する必要があります。

backwardPageToken

文字列

×

前のページの項目データを取得するトークンです。backwardPageTokenに使用する文字列は開発者が決定します。スキルでは、このトークンに関連付けられたデータを追跡する必要があります。また、これが項目リストを遡るトークンであることを識別する必要もあります。

指定しない場合、レンダリングする前のリスト項目はありません。ユーザーはリストを逆方向にスクロールすることはできません。

forwardPageToken

文字列

×

次のページの項目データを取得するトークンです。forwardPageTokenに使用する文字列は開発者が決定します。スキルでは、このトークンに関連付けられたデータを追跡する必要があります。また、これが項目リストを進むトークンであることを識別する必要もあります。

指定しない場合、レンダリングする次のリスト項目はありません。ユーザーはリストを正方向にスクロールすることはできません。

items

配列

×

最初にレンダリングする項目のオブジェクトデータの配列です。Alexaは、リストの表示領域の左上に最初の項目を表示します。

APLドキュメントに動的なデータソースをバインドする

ドキュメントで動的なデータソースを使用するには、mainTemplate.parameterでデータソースキーを使用する必要があります。1.3より前の「payload」パラメーターは使用しないでください。

次に、データバインディング式でデータソースキーを使用します。たとえば、dynamicSourceExampleというデータソースを作成したとします。このデータソースをバインドするには、${dynamicSourceExample}という式を使用します。この構文は、ドキュメントにitemsプロパティ内の項目のセットを提供します。式にitemsプロパティを含めないでください。

データソースをPager、GridSequence、Sequence、Containerのdataプロパティのいずれかにバインドします。Containerは遅延読み込みをサポートしていませんが、動的データソースはサポートしています。dynamicIndexListは、ほかのコンポーネントタイプと共に使用することはできません。

以下は、dynamicSourceExampleデータソースで定義されている10個の項目を表示するSequenceの例です。

{
  "type": "APL",
  "version": "2024.3",
  "mainTemplate": {
    "parameters": [
      "dynamicSourceExample"
    ],
    "items": [
      {
        "type": "Sequence",
        "data": "${dynamicSourceExample}",
        "items": {
          "type": "Text",
          "text": "${data.primaryText}"
        }
      }
    ]
  }
}

ディレクティブとリクエストを使用してリストを管理する

Alexa.Presentation.APLインターフェースは、動的なデータソースを管理するいくつかのディレクティブとリクエストを提供します。

dynamicIndexListデータソースを使用すると、項目を段階的に読み込むことができます。リストのコンテンツを変更することもできます。dynamicTokenList使用すると、ユーザーがリストをスクロールするにつれて追加のコンテンツページを読み込むことができます。

dynamicIndexListを使用して項目を段階的に読み込むには

  1. RenderDocumentディレクティブで、項目の初期セットを含むdynamicIndexListデータソースを送信します。
  2. ユーザーがリストをスクロールすると、AlexaはスキルにLoadIndexListDataリクエストを送信して、表示する追加の項目を要求します。
  3. LoadIndexListDataリクエストにSendIndexListDataディレクティブで応答して、次に表示する項目のセットを含む別のdynamicIndexListデータソースを送信します。

dynamicIndexListのコンテンツを変更するには

  1. RenderDocumentディレクティブで、リスト項目のセットを含む最初のdynamicIndexListデータソースを送信します。
  2. UpdateIndexListDataディレクティブを使用して、新しい項目の挿入や既存の項目の削除などのデータ更新を行います。

dynamicTokenListを使用してデータのページを読み込むには

  1. RenderDocumentディレクティブで、項目の初期セットを含むdynamicTokenListデータソースを送信します。
  2. ユーザーがリストをスクロールすると、AlexaはスキルにLoadTokenListDataリクエストを送信して、表示する追加の項目を要求します。
  3. LoadTokenListDataリクエストにSendTokenListDataディレクティブを応答して、表示する次の項目のセットを含む別のdynamicTokenListデータソースを送信します。

リクエストとディレクティブの詳細については、Alexa.Presentation.APLインターフェースのリファレンスを参照してください。

Sequenceコンポーネントのサイズと読み込む項目数

遅延読み込みのためにSequenceで動的なデータソースを使用する場合は、応答ごとに、Sequenceを少なくとも3回満たすのに十分な数の項目を送信します。たとえば、Sequenceに5個の項目を表示できる高さがある場合、最初のdynamicIndexListには15個以上の項目が含まれている必要があります。後続のSendIndexListDataディレクティブまたはSendTokenListDataディレクティブにも、15個以上の項目を含める必要があります。水平スクロールのSequenceでも同様です。Sequenceに5個の項目を表示できる幅がある場合は、各呼び出しで15個以上の項目を送信します。

十分な大きさの項目セットを提供することで、リストのパフォーマンスとユーザーエクスペリエンスが向上します。各応答で送信する項目の数が少ないと、ユーザーがスクロールするたびに絶えずAlexaが新しい項目をリクエストする必要が生じるため、ユーザーエクスペリエンスが低下する可能性があります。

項目の読み込み時やスクロール時にSequenceの高さまたは幅が変化しないようにするには、Sequenceのheightプロパティまたはwidthプロパティにauto設定を使用しないようにします。 Sequenceのサイズを相対ディメンションまたは絶対ディメンションに設定します。

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

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