APLデータストア拡張機能

APLデータストア拡張機能

Alexa Presentation Language（APL）ドキュメントでデバイス上のデータストアにアクセスするには、データストア拡張機能を使用します。データストアとは、APLドキュメントがデータバインディングを使用してアクセスできるデータを格納する、デバイスにローカルにインストールされる領域です。ウィジェットでは、データストアを使用することで、スキルにリクエストを送信して応答を待つ必要なくコンテンツを表示できます。

データストアのデータにバインドするデータバインディング式を使用するには、データストア拡張機能を使用する必要があります。

拡張機能の概要

サポートされるAPLの最小バージョン

APL 1.4

拡張機能のURI

alexaext:datastore:10

設定

環境プロパティ

ライブデータプロパティ

コマンド

イベントハンドラー

スキルマニフェストへの追加

必要。manifest.apis.custom.interfaces配列で、ALEXA_EXTENSIONオブジェクトのrequestedExtensionsプロパティにalexaext:datastore:10を追加します。

設定の自動初期化

なし

データストアとデータストア拡張機能について

データストア拡張機能は、スキルのデータを格納するデバイス上のデータストレージをサポートするデバイスで使用できます。このようなデバイスには、ウィジェットをサポートするすべてのデバイスが含まれます。

データストア階層

デバイス上のデータストアは、データをオブジェクトまたはオブジェクトの配列として格納します。データストアは、これらのオブジェクトまたは配列を、リージョン、名前空間、キーで構成される階層に編成します。

データストア階層

次の一覧は、データストア階層に関する用語の定義を説明したものです。

  • リージョン - データストア内でグローバルに分離された、データを格納するストレージパーティション。スキルは、スキルIDに基づいた特定のリージョンにアクセスできます。データストアのコマンドと操作では、このリージョンが自動的に設定されます。この場所を直接指定することはできません。
  • 名前空間 - リージョン内のパーティション。スキルで使用するデータストアの名前空間を定義します。
  • キー - 名前空間内の一意の識別子。名前空間内で使用するキーを定義します。
  • オブジェクト - オブジェクトまたはオブジェクトの配列の形式で格納されるコンテンツ。データストアオブジェクトにアクセスするには、リージョン、名前空間、キーで構成される階層識別子を使用します。

データストアのセキュリティ

データストアは、格納されたコンテンツへの権限のないアクセスを防ぎます。データストア内のオブジェクトを読み書きするには、APLドキュメントに読み取り権限または書き込み権限が必要です。次の一覧は、データストア階層の各レベルで適用されるセキュリティポリシーを示しています。

  • リージョン - APLドキュメントにリージョンレベルでの読み取り権限または書き込み権限がある場合、ドキュメントは、そのリージョン内のすべての名前空間のすべてのキーのコンテンツを読み書きできます。スキルには、スキルのIDに基づいたリージョンへの読み取りおよび書き込みアクセス権があります。スキルでは、ほかのスキルのデータストアリージョンにアクセスすることはできません。
  • 名前空間 - APLドキュメントに名前空間レベルでの読み取り権限または書き込み権限がある場合、ドキュメントは、その名前空間内のすべてのキーのコンテンツを読み書きできます。
  • キー - APLドキュメントにキーレベルでの読み取り権限または書き込み権限がある場合、ドキュメントは、データストア内でその単一のキーに対して格納されているオブジェクトや配列を読み書きできます。

データストア拡張機能を有効にする

スキルマニフェストとAPLドキュメントで拡張機能を有効にします。拡張機能を使用するには、両方の場所に拡張機能を含める必要があります。次に、ドキュメントのsettingsプロパティで、拡張機能のドキュメントレベルの設定を行います。

データストア拡張機能のURIは、alexaext:datastore:10です。

スキルマニフェストに拡張機能を追加するには、manifest.apis.custom.interfaces配列で、ALEXA_EXTENSIONオブジェクトのrequestedExtensionsプロパティにalexaext:datastore:10を追加します。

次の例は、スキルマニフェストで拡張機能を有効にする方法を示しています。

{
  "manifest": {
    "apis": {
      "custom": {
        "interfaces": [
          {
            "type": "ALEXA_EXTENSION",
            "autoInitializedExtensions": [],
            "requestedExtensions": [
              {
                "uri": "alexaext:datastore:10"
              }
            ]
          }
        ]
      }
    }
  }
}

詳細については、スキルマニフェストで拡張機能をリクエストするを参照してください。

APLドキュメントで拡張機能をリクエストするには、ドキュメントのextensions配列のオブジェクトとしてalexaext:datastore:10を追加し、nameを割り当てます。ドキュメント内で拡張機能を参照するには、この名前を使用します。

次の例では、データストア拡張機能をリクエストしてDataStoreという名前を付けます。

クリップボードにコピーされました。

{
  "type": "APL",
  "version": "2024.3",
  "extensions": [
    {
      "name": "DataStore",
      "uri": "alexaext:datastore:10"
    }
  ]
}

APLドキュメントでAPL拡張機能をリクエストする方法の詳細については、APLドキュメントで拡張機能をリクエストするを参照してください。

デバイスでデータストア拡張機能がサポートされるかどうかを確認する

デバイスでデータストア拡張機能がサポートされるかどうかを確認するには、ドキュメントでenvironment.extensionプロパティを使用します。たとえば、extensionsプロパティでnameにDataStoreを指定したとすると、デバイスでデータストアがサポートされていれば、次のデータバインディング式からtrueが返されます。

${environment.extension.DataStore}

拡張機能の設定

データストア拡張機能には、次の設定があります。

名前 型 デフォルト 説明

dataBindings

オブジェクト

[ ]

データストアのバインディングを定義するオブジェクト配列です。

APLドキュメントでこれらの設定を行うには、settings.AssignedNameという形式を使用します。AssignedNameは、extensionsプロパティで拡張機能に割り当てた名前です。

次の例では、拡張機能にDataStoreという名前を割り当て、dataBindingsプロパティを設定します。

{
  "type": "APL",
  "version": "2024.3",
  "extensions": [
    {
      "name": "DataStore",
      "uri": "alexaext:datastore:10"
    }
  ],
  "settings": {
    "DataStore": {
      "dataBindings": []
    }
  },
  "mainTemplate": {}
}

dataBindings

オブジェクトの配列です。この配列内の各オブジェクトで、dataBindingNameを指定してライブデータのDataBindingオブジェクトを定義します。DataBindingオブジェクトは、データストア内の1つのオブジェクトを表します。データストア内のそのオブジェクトからデータを取得するには、ドキュメントのデータバインディング式でdataBindingNameを使用します。

dataBindings配列内の各定義には、次の表に示すプロパティが必要です。

名前 型 デフォルト 説明

namespace

文字列

必須

アクセスするオブジェクトが格納されているデータストア名前空間を指定します。スキルのリージョン内で一意である必要があります。名前空間は、次の要件を満たす空でない文字列にする必要があります。

  • 512バイト未満
  • 先頭の文字列が「sqlite_」でない
  • SQLiteの予約済みキーワードのいずれにも一致しない
  • 先頭がアンダースコア（_）でない
  • 使用できる文字セット：[_ - . a-z A-Z 0-9]

namespaceの名前は、スキルに割り当てられたデータストアストレージのサイズにカウントされます。制限の詳細については、データストアの制限を参照してください。

key

文字列

必須

アクセスするオブジェクトを識別するデータストアキーを指定します。このキーは、指定したnamespaceに存在している必要があります。キーは、次の要件を満たす空でない文字列にする必要があります。

  • 512バイト未満
  • 先頭がアンダースコア（_）でない
  • 使用できる文字セット：[_ - . a-z A-Z 0-9]

keyの名前は、スキルに割り当てられたデータストアストレージのサイズにカウントされます。制限の詳細については、データストアの制限を参照してください。

dataBindingName

文字列

必須

DataBindingオブジェクトへのアクセスに使用する名前を設定します。データストア拡張機能は、この名前をドキュメントで利用できるデータバインディングコンテキストに追加します。この名前をデータバインディング式で使用することで、namespaceのkeyに格納されているオブジェクトのデータにアクセスできます。

dataType

文字列

object

アクセスするオブジェクトのデータ型です。有効な値は、 OBJECT、ARRAYです。

startIndex

数値

0

dataTypeがARRAYの場合に適用されます。namespaceのkeyに格納されている配列の項目の範囲を表す開始インデックスを指定します。ライブデータのDataBindingプロパティは、startIndexからendIndexまでの要素を含むサブ配列に初期化されます。

endIndex

数値

–1

dataTypeがARRAYの場合に適用されます。namespaceのkeyに格納されている配列の項目の範囲を表す終了インデックスを指定します。ライブデータのDataBindingプロパティは、startIndexからendIndexまでの要素を含むサブ配列に初期化されます。

namespaceとkey

データバインディング式でアクセスするオブジェクトを参照するには、これらのプロパティを設定します。データのnamespaceとkeyは開発者が定義します。

次の例は、LocationWeatherというnamespaceとDS_Weatherというkeyを指定するデータバインディングを示しています。

{
  "settings": {
    "DataStore": {
      "dataBindings": [
        {
          "namespace": "LocationWeather",
          "key": "weather",
          "dataBindingName": "DS_Weather"
        }
      ]
    }
  }
}

dataBindingName

DataBindingオブジェクトへのアクセスに使用する名前を設定します。データストア拡張機能は、この名前をドキュメントで利用できるデータバインディングコンテキストに追加します。この名前をデータバインディング式で使用することで、データストア内の指定したnamespaceのkeyに格納されているオブジェクトのデータにアクセスできます。

前の例では、dataBindingNameをDS_Weatherという名前に設定しました。weatherオブジェクト内のデータにアクセスするには、この名前をデータバインディング式で使用して、${DS_Weather.propertyName}として参照します。propertyNameは、格納されているオブジェクト内のプロパティ名です。完全な例については、例： dataBindingsを設定してデータにアクセスするを参照してください。

拡張機能は、データストアにnamespaceとkeyで識別されるオブジェクトが存在するかどうかにかかわらず、指定されたdataBindingNameのDataBindingオブジェクトを常に作成します。

  • オブジェクトが存在しない場合、提供されるdataBindingNameはnullになります。
  • オブジェクトが存在する場倍、提供されるdataBindingNameはそのオブジェクトになります。

dataType

データストアに格納されている項目のデータ型です。OBJECTまたはARRAYを指定できます。

startIndex、endIndex

startIndexプロパティとendIndexプロパティは、dataTypeがARRAYの場合に適用されます。これらのプロパティは、指定したnamespaceのkeyに格納されている配列の項目の範囲を表す、開始インデックスと終了インデックスの値を示します。これらのプロパティを設定した場合、ライブデータのDataBindingオブジェクトは、startIndexからendIndexまでの要素を含むサブ配列に初期化されます。

この範囲は、両端のstartIndexとendIndexの要素を含みます。

dataTypeがOBJECTの場合、startIndexプロパティとendIndexプロパティは無視されます。

UpdateArrayBindingRangeコマンドを使用すると、DataBindingオブジェクトに読み込まれた要素の範囲を変更できます。

例： dataBindingsを設定してデータにアクセスする

以下の例では、データストアに格納されているコンテンツ、dataBindingsの設定、ドキュメント内のデータバインディング式の関係を示します。ここでは、スキルに割り当てられたリージョン内のデータストアの次の場所に、スキルからデータを書き込むものと想定します。

  • 名前空間： LocationWeather
  • キー：weather

スキルはデータストアREST APIを使用して、次のコンテンツをデバイス上のデータストアに追加します。

{
  "location": "Seattle, WA",
  "details": {
    "temperature": "5 °C",
    "precipitation": "20%",
    "humidity": "70%",
    "wind": "4 km/h"
  }
}

ドキュメントでは、dataBindingsに次の項目を含めてデータストア拡張機能を設定します。

{
  "settings": {
    "DataStore": {
      "dataBindings": [
        {
          "namespace": "LocationWeather",
          "key": "weather",
          "dataBindingName": "DS_Weather"
        }
      ]
    }
  }
}

この設定により、${DS_Weather.location}という式で文字列「Seattle, WA」が返されます。

以下は、この設定を使用して、データストアに格納されている天気データを表示するウィジェットのAPLドキュメントの例です。

後からスキルでデータストアREST APIを使用して、新しい天気情報でデータストアを更新すると、ウィジェットが更新され、新しいデータが表示されます。コードサンドボックスでデータストアの更新をシミュレートするには、次の手順を実行します。

  1. Data Storeタブをクリックします。
  2. Edit Data Storeをクリックします。
  3. Commandsペインにデータストアコマンドを入力します。この例では、temperature、precipitation、humidityの値を変更するサンプルのPUT_OBJECTコマンドがデフォルトで入力されています。
  4. Execute Commandsをクリックしてコマンドを送信します。

環境プロパティ（静的）

データストア拡張機能により、次の静的環境プロパティが追加されます。

名前 型 説明

version

文字列

データストア拡張機能のバージョンです。

環境プロパティにアクセスするには、データバインディングコンテキストのenvironment.extension.AssignedNameを使用します。AssignedNameは、extensionsプロパティで拡張機能に割り当てた名前です。

たとえば、拡張機能にDataStoreという名前を割り当てたとすると、${environment.extension.DataStore.version}によって拡張機能のバージョンが返されます。

データバインディングコンテキストのenvironment.extensionプロパティの詳細については、extensionを参照してください。

ライブデータプロパティ

データストア拡張機能は、データバインディングコンテキストにライブデータプロパティを追加します。ライブデータプロパティは、APLドキュメントのライフサイクル中に変更される可能性のあるデータオブジェクトです。

ライブデータの詳細については、拡張機能のライブデータを参照してください。

DataBinding

データストアのDataBindingライブデータオブジェクトは、スキルに割り当てられたリージョン内のデータストアに格納されている、特定のnamespaceとkeyを持つオブジェクトまたは配列を表します。

DataBindingのプロパティは、データストア内のオブジェクトまたは配列の構造によって異なります。データにアクセスするには、拡張機能のsettingsでオブジェクトに設定したdataBindingNameを使用します。

例については、例： dataBindingsを設定してデータにアクセスするを参照してください。

コマンド

データストア拡張機能により、新しい拡張機能コマンドが追加されます。

データストアのコマンドを実行するには、コマンドのtypeプロパティをAssignedName:CommandNameに設定します。AssignedNameは、extensionsプロパティで拡張機能に割り当てた名前です。たとえば、拡張機能にDataStoreという名前を割り当てたとすると、WatchObjectコマンドはDataStore:WatchObjectとして実行できます。

GetObject

GetObjectコマンドは、データストアオブジェクトを取得します。このコマンドは非同期です。リクエストしたオブジェクトは、このコマンドの実行後にOnObjectReceivedハンドラーによって返されます。

次の表は、このコマンドのプロパティの一覧です。

プロパティ 型 デフォルト 説明

namespace

文字列

必須

スキルのリージョン内のnamespaceの名前です。

key

文字列

必須

指定したnamespace内のkeyの名前です。

token

文字列

""

（任意）開発者が指定できるトークンです。OnObjectReceivedイベントハンドラーは、リクエストされたオブジェクトを返すときにこのトークンを含めます。

次の例では、ウィジェットが最初にインフレートされたときにGetObjectコマンドを実行します。次に、OnObjectReceivedハンドラーでSetValueコマンドを使用して、locationバインド変数の値を設定します。この値がTextコンポーネントに表示されます。この例では、ライブデータのDataBindingプロパティは使用されていないため、PUT_OBJECTなどのデータストアコマンドを実行してデータストアを更新しても、ウィジェットに表示された値は変わりません。

WatchObject

WatchObjectコマンドは、指定されたデータストアオブジェクトの変更を監視するようにドキュメントを設定します。オブジェクトが変更されると、OnObjectChangedイベントハンドラーが実行されます。このコマンドとハンドラーを使用すれば、データストアの変更に応答してほかのAPLコマンドを実行できます。

WatchObjectを実行すると、このコマンドはOnObjectChangedハンドラーを呼び出し、データストアオブジェクトの変更を監視するようにドキュメントを設定します。それ以降、データストアオブジェクトが変更されたときにOnObjectChangedが呼び出されます。

次の表は、このコマンドのプロパティの一覧です。

プロパティ 型 デフォルト 説明

namespace

文字列

必須

スキルのリージョン内のnamespaceの名前です。

key

文字列

必須

指定した名前空間内のkeyの名前です。

指定されたオブジェクトが存在しないか削除されている場合、OnObjectChangedのdataプロパティはnullを返します。

次の例は、ドキュメントが表示されたときに実行されるWatchObjectコマンドを示しています。OnObjectChangedハンドラーは、SetValueコマンドを実行します。

後からスキルでデータストアREST APIを使用して、名前空間がLocationWeatherでキーがweatherのデータストアオブジェクトを更新すると、OnObjectChangedハンドラーが再度実行されます。これにより、SetValueコマンドがトリガーされ、temperatureバインド変数が更新されます。

UnwatchObject

UnwatchObjectは、WatchObjectのターゲットとして指定されていたデータストアオブジェクトの監視を停止するようにドキュメントを設定します。UnwatchObjectの実行後は、データストアオブジェクトが変更されてもOnObjectChangedハンドラーは実行されません。

UnwatchObjectコマンドは結果を返しません。

次の表は、このコマンドのプロパティの一覧です。

プロパティ 型 デフォルト 説明

namespace

文字列

必須

スキルのリージョン内のnamespaceの名前です。

key

文字列

必須

指定した名前空間内のkeyの名前です。

以下は、ユーザーがボタンをタップしたときにUnwatchObjectコマンドを実行するTouchWrapperの例です。

{
  "type": "APL",
  "version": "2024.3",
  "extensions": [
    {
      "name": "DataStore",
      "uri": "alexaext:datastore:10"
    }
  ],
  "settings": {
    "DataStore": {
      "dataBindings": [
        {
          "namespace": "LocationWeather",
          "key": "weather",
          "dataBindingName": "DS_Weather"
        }
      ]
    }
  },
  "mainTemplate": {
    "item": {
      "type": "TouchWrapper",
      "item": {
        "type": "Text",
        "text": "DataStoreからのオブジェクトの監視を停止"
      },
      "onPress": {
        "type": "DataStore:UnwatchObject",
        "namespace": "LocationWeather",
        "key": "weather"
      }
    }
  }
}

UpdateArrayBindingRange

UpdateArrayBindingRangeコマンドは、ライブデータのDataBinding配列に読み込む要素の範囲を変更します。

次の表は、このコマンドのプロパティの一覧です。

プロパティ 型 デフォルト 説明

dataBindingName

文字列

必須

DataBinding配列の名前です。拡張機能のsettingsを使用して、dataTypeがARRAYのDataBindingを設定します。

startIndex

数値

必須

データストア配列の項目の範囲を表す開始インデックスを指定します。dataBindingNameで識別されるライブデータ配列は、データストア配列の指定したインデックスから始まる範囲にある要素のサブ配列で更新されます。

endIndex

数値

必須

データストア配列の項目の範囲を表す終了インデックスを指定します。dataBindingNameで識別されるライブデータ配列は、データストア配列の指定したインデックスで終わる範囲にある要素のサブ配列で更新されます。

UpdateArrayBindingRangeは、dataBindingNameがARRAYを参照している場合に適用されます。dataBindingNameがOBJECTを参照している場合、このコマンドは実行されません。

イベントハンドラー

データストア拡張機能により、新しい拡張機能イベントハンドラーが追加されます。データストア拡張機能で生成されるイベントに応答するには、APLドキュメントのトップレベルのプロパティにハンドラーを追加します。ハンドラー名にはAssignedName:EventHandlerNameという形式を使用します。AssignedNameはextensionsプロパティで拡張機能に割り当てた名前、EventHandlerNameはハンドラーの名前です。

たとえば、拡張機能にDataStoreという名前を指定した場合、OnObjectChangedハンドラーでイベントに応答するには、DataStore:OnObjectChangedを使用します。

OnObjectChanged

次の状況で呼び出されます。

  • WatchObjectが実行されたとき。
  • WatchObjectコマンドで設定されたデータストアオブジェクトが変更されたとき。

次の表は、OnObjectChangedハンドラーでイベントコンテキストに追加されるプロパティの一覧です。

名前 型 デフォルト 説明

namespace

文字列

必須

変更されたデータストアオブジェクトのnamespaceです。

key

文字列

必須

変更されたデータストアオブジェクトのkeyです。

data

オブジェクト

必須

変更されたデータストアオブジェクトで更新された値です。次の状況ではnullが返されます。

  • WatchObjectコマンドで指定されたオブジェクトが存在しない場合。
  • WatchObjectコマンドで指定されたオブジェクトがデータストアから削除されている場合。

OnObjectChangedハンドラーは、次の形式のイベントを生成します。

{
  "namespace": "LocationWeather",
  "key": "weather",
  "data": {
    "location": "Pune, MH",
    "details": {
      "temperature": "27 °C",
      "precipitation": "7%",
      "humidity": "51%",
      "wind": "5 km/h"
    }
  },
  "event": {
    "source": {
      "type": "Document",
      "handler": "DataStore:OnObjectChanged",
      "id": null,
      "uid": null,
      "value": null
    }
  }
}

以下は、監視しているオブジェクトが更新されたときにSetValueコマンドを実行するAPLドキュメントの例です。

{
  "type": "APL",
  "version": "2024.3",
  "extensions": [
    {
      "name": "DataStore",
      "uri": "alexaext:datastore:10"
    }
  ],
  "settings": {
    "DataStore": {
      "dataBindings": [
        {
          "namespace": "LocationWeather",
          "key": "weather",
          "dataBindingName": "DS_Weather"
        }
      ]
    }
  },
  "DataStore:OnObjectChanged": [
    {
      "type": "SetValue",
      "componentId": "txtTemperature",
      "property": "temperature",
      "value": "${event.data.details.temperature}"
    }
  ],
  "mainTemplate": {
    "item": {
      "type": "Text",
      "id": "txtTemperature",
      "bind": [
        {
          "name": "temperature",
          "value": "30 °C"
        }
      ],
      "text": "${DS_Weather.location}の気温：${temperature}"
    }
  }
}

OnObjectReceived

GetObjectコマンドへの応答として呼び出されます。イベントコンテキストは、リクエストされたオブジェクトを提供します。

次の表は、OnObjectReceivedハンドラーでイベントコンテキストに追加されるプロパティの一覧です。

名前 型 デフォルト 説明

namespace

文字列

必須

リクエストされたデータストアオブジェクトのnamespaceです。

key

文字列

必須

リクエストされたデータストアオブジェクトのkeyです。

data

オブジェクト

必須

リクエストされたデータストアオブジェクトの値です。リクエストされたオブジェクトが存在しない場合はnullを返します。

token

文字列

""

GetObjectコマンドに渡されたオプションのトークンです。

OnObjectReceivedハンドラーは、次の形式のイベントを生成します。

{
  "namespace": "LocationWeather",
  "key": "weather",
  "data": {
    "location": "Pune, MH",
    "details": {
      "temperature": "27 °C",
      "precipitation": "7%",
      "humidity": "51%",
      "wind": "5 km/h"
    }
  },
  "token": "thisIsADummyToken",
  "event": {
    "source": {
      "type": "Document",
      "handler": "DataStore:OnObjectReceived",
      "id": null,
      "uid": null,
      "value": null
    }
  }
}

次の例は、GetObjectを使用してオブジェクトを取得し、取得したオブジェクトのデータを使用してSetValueコマンドを実行するAPLドキュメントです。

{
  "type": "APL",
  "version": "2024.3",
  "extensions": [
    {
      "name": "DataStore",
      "uri": "alexaext:datastore:10"
    }
  ],
  "settings": {
    "DataStore": {
      "dataBindings": []
    }
  },
  "onMount": {
    "type": "DataStore:GetObject",
    "namespace": "LocationWeather",
    "key": "weather",
    "token": "thisIsADummyToken"
  },
  "DataStore:OnObjectReceived": [
    {
      "type": "SetValue",
      "when": "${event.token == 'thisIsADummyToken'}"
      "componentId": "txtContent",
      "property": "text",
      "value": "${event.data.location}の気温：${event.data.details.temperature}"
    }
  ],
  "mainTemplate": {
    "items": [{
      "type": "Text",
      "id": "txtContent",
      "bind": [
        {
          "name": "dsContent",
          "value": "dummyValue"
        }
      ],
      "text": "DataStoreからのコンテンツを待っています"
    }]
  }
}

データストアを使用したデータバインディングのルール

APLドキュメント内のプロパティをデータストア内のオブジェクトにバインドするときは、以下のルールに従うようにしてください。

動的でないプロパティをデータストアにバインドしない

APLコンポーネントのすべてのプロパティが動的であるわけではありません。APLコンポーネントの動的プロパティは、APLドキュメントのライフサイクル中に再評価できます。動的でないプロパティは、ドキュメントが最初にインフレートされたときに1回だけ評価されます。

データストアプロパティを動的でないプロパティにバインドし、その後でデータストアのコンテンツを更新しても、動的でないプロパティには変更は反映されません。

基本コンポーネントのプロパティのうち、どれが動的であるかの詳細については、APL基本コンポーネントのプロパティのプロパティの表を参照してください。「動的」列にプロパティが動的かどうか示されています。コンポーネント固有のプロパティが動的かどうかの詳細については、そのコンポーネントのトピックを参照してください。各コンポーネントのトピックにあるプロパティの表にも、「動的」列が含まれています。

「when」プロパティをデータストアにバインドしない

コンポーネントをインフレートして表示するかどうかを決定するには、コンポーネントでwhenプロパティを使用します。ただし、whenプロパティは動的ではありません。ランタイムがwhenを評価するのは、ドキュメントが最初にインフレートされるときの1回だけです。したがって、後でデータストアを更新しても、whenの式は更新されません。

データストア内のプロパティに基づいてコンポーネントの表示と非表示を切り替えるには、代わりにコンポーネントのdisplayプロパティを使用します。

以下の例では、データストアのdataBindingNameがMyDataStoreという名前に設定されているとします。ここに格納されているオブジェクトにshouldDisplayTextというプロパティがあり、trueまたはfalseに設定できます。

次の例では、Textコンポーネントでwhenを使用して、データストア内のshouldDisplayTextプロパティを参照しようとしています。ドキュメントのインフレート時には、${MyDataStore.shouldDisplayText}がfalseに評価されるため、コンポーネントは表示されません。後でデータストア内のこのオブジェクトを更新し、shouldDisplayTextプロパティをtrueに設定したとします。しかし、whenは動的でないため、コンポーネントは表示されないままです。

誤った例： 「when」を使用して、データストアプロパティに基づいてコンポーネントを表示または非表示にする

{
  "when": "${MyDataStore.shouldDisplayText}",
  "type": "Text",
  "text": "これはサンプルテキストです。"
}

次の例は、displayプロパティを使用してこの問題を修正しています。ドキュメントが最初にインフレートされるとき、${MyDataStore.shouldDisplayText}はfalseです。コンポーネントのdisplayはnoneに設定され、コンポーネントは表示されません。後でデータストア内のオブジェクトを更新し、shouldDisplayTextプロパティをtrueに変更したとします。displayプロパティは動的であるため、再評価されてnormalに更新されます。これにより、コンポーネントが表示されます。

正しい例： 動的プロパティを使用して、データストアプロパティに基づいてコンポーネントを表示または非表示にする

{
  "type": "Text",
  "text": "これはサンプルテキストです。",
  "display": "${MyDataStore.shouldDisplayText ? 'normal' : 'none'}"
}

OBJECTに入れ子にされた配列をデータ配列のインフレートに使用しない

Sequenceなどの複数子コンポーネントのdataプロパティには、配列を割り当てることができます。この場合、コンポーネントはデータ配列のインフレートを使用します。つまり、items内のコンポーネントは、配列の値ごとに1回ずつインフレートされます。

データストアを操作する場合、OBJECT内に入れ子にされた配列をデータ配列のインフレートに使用することはできません。代わりに、dataTypeプロパティをARRAYに設定したDataBindingオブジェクトを用意し、そのデータバインディングオブジェクトにコンポーネントのdataプロパティをバインドする必要があります。

誤った例： 「data」プロパティをOBJECT内のプロパティにバインドする

次の例は、テキストフィールド（headerTitle）と、配列を含むプロパティ（arrayOfItems）を持つオブジェクトを示しています。

{
  "headerTitle": "これはタイトルです",
  "arrayOfItems": [
    {
      "displayName": "項目1"
    },
    {
      "displayName": "項目2"
    },
    {
      "displayName": "項目3"
    }
  ]
}

このオブジェクトに対して、次のようにOBJECTデータバインディングを設定したとします。

{
  "settings": {
    "DataStore": {
      "dataBindings": [
        {
          "namespace": "ObjectAndArrayExample",
          "key": "mainWidgetData",
          "dataBindingName": "dsWidgetData",
          "dataType": "OBJECT"
        }
      ]
    }
  }
}

この例の場合、コンポーネントのプロパティをオブジェクトの${dsWidgetData.headerTitle}プロパティにバインドすることは可能です。ただし、dataを${dsWidgetData.arrayOfItems}にバインドしても機能しません。

この問題を修正し、データストアでデータ配列のインフレートを使用するには、DataBindingオブジェクトのdataTypeプロパティをARRAYに設定し、そのデータバインディングオブジェクトにコンポーネントのdataプロパティをバインドします。データストアも更新して、該当する名前空間とキーを持つオブジェクトに、表示するデータの配列を設定します。

正しい例： 「data」プロパティをARRAYにバインドする

次の例は、arrayOfItems配列を示しています。これは配列として格納され、OBJECT内に入れ子になっていません。

[
  {
    "displayName": "項目1"
  },
  {
    "displayName": "項目2"
  },
  {
    "displayName": "項目3"
  }
]

DataBindingオブジェクトを配列として設定します。

{
  "settings": {
    "DataStore": {
      "dataBindings": [
        {
          "namespace": "ObjectAndArrayExample",
          "key": "arrayOfItems",
          "dataBindingName": "dsArrayOfItems",
          "dataType": "ARRAY"
        }
      ]
    }
  }
}

Sequenceで、dataプロパティをdsArrayOfItemsにバインドします。Sequence内で配列にアクセスするには、dataを使用します。

{
  "type": "Sequence",
  "height": "100%",
  "width": "100%",
  "padding": "@spacingSmall",
  "data": "${dsArrayOfItems}",
  "items": [
    {
      "type": "Text",
      "text": "${data.displayName}"
    }
  ]
}

配列とオブジェクトの両方にプロパティをバインドするには、複数のDataBindingオブジェクトを定義します。次の例では、2つのDataBindingオブジェクトを定義します。1つはOBJECTとして、もう1つはARRAYとして設定されます。

{
  "settings": {
    "DataStore": {
      "dataBindings": [
        {
          "namespace": "ObjectAndArrayExample",
          "key": "mainWidgetData",
          "dataBindingName": "dsWidgetData",
          "dataType": "OBJECT"
        },
        {
          "namespace": "ObjectAndArrayExample",
          "key": "arrayOfItems",
          "dataBindingName": "dsArrayOfItems",
          "dataType": "ARRAY"
        }
      ]
    }
  }
}

以下は、データストア内のOBJECTとARRAYの両方を使用するAPLドキュメントの例です。

次の2つのPUT_OBJECTコマンドは、データストア内のオブジェクトと配列の両方を更新します。

[
  {
    "type": "PUT_OBJECT",
    "namespace": "ObjectAndArrayExample",
    "key": "mainWidgetData",
    "content": {
      "headerTitle": "これはヘッダータイトルです"
    }
  },
  {
    "type": "PUT_OBJECT",
    "namespace": "ObjectAndArrayExample",
    "key": "arrayOfItems",
    "content": [
      {
        "displayName": "項目1"
      },
      {
        "displayName": "項目2"
      },
      {
        "displayName": "項目3"
      }
    ]
  }
]
このページは役に立ちましたか？

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