APLデータソース

APLデータソース

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

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

任意のdatasourcesオブジェクトでAlexaにデータソースを渡します。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": "1.6",
          "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": "1.6",
  "mainTemplate": {
    "parameters": [
      "myDocumentData"
    ],
    "items": []
  }
}

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

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

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

データソースをペイロードまたはその他のパラメータにバインドすることについて

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

「payload」をmainTemplate.parametersとして使用するドキュメントは今後も引き続き機能します。ただし、新しいAPLドキュメントには簡略化したフォームを使用することをお勧めします。パラメーターとして他の文字列を使用しても機能しません。「payload」またはデータソースキーを使用する必要があります。

データソースの型

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

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

オブジェクトデータソース

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

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

プロパティ 型 必須 説明

type

オブジェクト

◯

「オブジェクト」である必要があります。

properties

オブジェクト

✕

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

objectID

文字列

✕

オブジェクトデータソースの任意の識別子です。

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配列内の先頭アイテムのインデックスです。任意のオフセットでエクスペリエンスを開始するには、ゼロ以外の値を指定します。たとえば、「M」で始まる連絡先名のアルファベット順のリストを表示します。

minimumInclusiveIndex

整数

✕

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

maximumExclusiveIndex

整数

✕

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

items

配列

✕

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

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

{
  "dynamicSourceExample": {
    "type": "dynamicIndexList",
    "listId": "my-list-id",
    "startIndex": 0,
    "minimumInclusiveIndex": 0,
    "maximumExclusiveIndex": 200,
    "items": [
      {"primaryText":"item 1"},
      {"primaryText":"item 2"},
      {"primaryText":"item 3"},
      {"primaryText":"item 4"},
      {"primaryText":"item 5"},
      {"primaryText":"item 6"},
      {"primaryText":"item 7"},
      {"primaryText":"item 8"},
      {"primaryText":"item 9"},
      {"primaryText":"item 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": "1.6",
  "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のサイズを相対または絶対ディメンションのいずれかに設定します。

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

最終更新日: 2021 年 06 月 04 日