APLデータソース(1.3)



APLデータソース

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

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

データソースを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.3",
          "mainTemplate": {
            "parameters": [
              "myDocumentData"
            ],
            "items": []
          }
        },
        "datasources": {
          "myDocumentData": {
            "title": "これはとても単純な例です"
          }
        }
      }
    ]
  }
}

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

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

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

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

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

{
  "myDocumentData": {
    "title": "これはとても単純な例です"
  }
}

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

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

最後に、データバインディング式を使用して、コンポーネントプロパティをmyDocumentDataのデータにバインドします。プロパティにアクセスするには、myDocumentDataキーを使用します。たとえば、${myDocumentData.title}という式は「これはとても単純な例です」という値に解決されます。

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

{
  "type": "APL",
  "version": "1.3",
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.1.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」またはデータソースキーを使用する必要があります。

型指定ありと型指定なしのデータソース

データソースは、型指定なし、型指定ありのいずれかです。

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

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

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"
      }
    ]
  }
}

dynamicIndexListデータソース

dynamicIndexListデータソースは、遅延読み込みと動的データソースに必要なプロパティを追加します。遅延読み込みでは、ユーザーがコンテンツをスクロールすると、Alexaが大きなリストを徐々に表示します。動的データソースでは、データソースをAlexaに送信した後で更新できるため、完全に新しいドキュメントを送信することなく画面上の値を変更できます。

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

プロパティ 必須 説明
type 文字列 "dynamicIndexList"です。
listId 文字列 同じAPLドキュメント内のデータソースを区別するための識別子です。
startIndex 整数 items配列内の先頭アイテムのインデックスです。任意のオフセットでエクスペリエンスを開始するには、ゼロ以外の値を指定します。たとえば、「M」で始まる連絡先名のアルファベット順のリストを表示します。
minimumInclusiveIndex 整数 配列の最初の項目のインデックスです(インデックスはこの値を含みます)。minimumInclusiveIndexstartIndexより小さい場合、リストは逆方向スクロールリストになります。指定しない場合でもリストは逆方向にスクロールできますが、配列の最初のインデックスが不明になります。このプロパティをstartIndexプロパティと等しくなるように明示的に設定すると、ユーザーが逆方向にスクロールしたときにそれ以上項目を読み込まないリストになります。
maximumExclusiveIndex 整数 配列の最後のインデックスです(インデックスはこの値を含みません)。設定されなかった場合、リストは正方向スクロールリストですが、配列の最後のインデックスが不明になります。このプロパティを項目の配列の最後のインデックス + 1 に明示的に設定すると、ユーザーが正方向にスクロールしたときにそれ以上項目を読み込まないリストになります。たとえば、200項目にわたる単純な正方向スクロールエクスペリエンスを作成するには、startIndexminimumInclusiveIndexを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"}      
    ]
  }
}

dynamicIndexListデータソースをバインドする

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

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

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

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

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

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

項目を徐々に読み込むには、RenderDocumentディレクティブで項目の初期セットを含むdynamicDataIndexデータソースを送信します。ユーザーがリストをスクロールすると、AlexaはスキルにLoadIndexListDataリクエストを送信して、表示する追加の項目を要求します。それを受けて、スキルはSendIndexListDataディレクティブと合わせて、次に表示する項目のセットを含む別のdynamicIndexListデータソースを返します。

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

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

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

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

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