データバインディングの評価（APL for Audio）

Note: Sign in to the developer console to build or publish your skill.

APL for Audioは、データバインディングを使用してユーザーから提供されたデータを組み込み、オーディオリソースを取り込んで、データに基づく条件に応じてコンポーネントをインフレートします。ドキュメントでデータバインディングを使用するには、データバインディング式を記述します。これは、${..}という形式の部分文字列が埋め込まれたJSON文字列です。このドキュメントでは、これらの式がAlexaによってどのように評価されるかを説明します。

データバインディング式の構文の詳細については、データバインディングの構文を参照してください。

データソースの定義方法の詳細については、データソースを参照してください。

データバインディングアルゴリズム

次のAPLドキュメントについて考えてみましょう。

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

{
  "type": "APLA",
  "version": "0.91",
  "mainTemplate": {
    "parameters": [
      "data"
    ],
    "item": {
      "type": "Speech",
      "content": "さやには豆が${payload.data.value}粒あります"
    }
  }
}

この例では、Speechコンポーネントがデータソースのdata.valueプロパティの値を使用しています。この値は、より長い式に挿入されます。

以降のセクションでは、${payload.data.value}式の結果を使ってこの文字列を作成する際に使用するアルゴリズムについて説明します。

ステップ1：式の評価

右側（RHS）が文字列の場合、文字列をスキャンしてデータバインディング式（埋め込みの'${}'）を探します。スキャナーが1つ以上の埋め込み式を見つけると、文字列が抽象構文木（AST）に変換されます。たとえば、上記のtextの例では、次のような木構造に変換されます。

Concatenate
  String("さやには豆が")
  AttributeLookup
    Symbol("data")
    String("value")
  String("粒あります")

ASTは、現在のデータバインディングコンテキストを使用して評価されます。データバインディングコンテキストは、キーと値のペアからなるJSONディクショナリーで、値は数値、ブール値、オブジェクト、配列、文字列のいずれかです。「+」などの演算子により、必要に応じて暗黙的な型変換が行われます。たとえば、データバインディングコンテキストに以下が含まれているとします。

{
  "data": {
    "value": 5
  }
}

dataシンボルは、オブジェクト{value: 5}を返し、valueアトリビュートアクセサーは数値5を返します。この3つの要素からなる連結演算には2つの文字列と1つの数値があるため、数値が文字列としてキャストされ、「さやには豆が5粒あります」という文字列値が返されます。

ステップ2：型の強制

最終ステップでは、設定された値が正しい型であることを確認します。型変換の例は、truthyと強制の表を参照してください。

初期状態のデータバインディングコンテキスト

AlexaがAPLドキュメントをインフレートすると、Alexaはドキュメントを、定義済みのオブジェクトを含む新しいデータバインディングコンテキストに割り当てます。

名前	説明
`environment`	現在のランタイム環境に関する情報です。
`Math`	ビルトインの数学関数です（データバインディングの構文を参照）。
`String`	ビルトインの文字列関数です（データバインディングの構文を参照）。

environment

environmentオブジェクトには、動作しているAPL環境に関するランタイム情報が含まれます。これには次のプロパティが含まれます。

名前	型	説明
`alexaLocale`	文字列	リクエストの現在のロケールです。
`agentName`	文字列	ランタイム環境の名前です。
`agentVersion`	文字列	ランタイム環境のバージョンです。
`aplaVersion`	文字列	サポートされているAPL for Audioのバージョンです（現在は0.91）。
`aplVersion`	文字列	サポートされているAPLのバージョンです（ない場合はnull）。
`apltVersion`	文字列	文字表示でサポートされるAPLのバージョンです（ない場合はnull）。

たとえば、environment.aplaVersionが0.91でaplVersionとapltVersionの両方がnullの場合、デバイスはAPL for Audioをサポートしますが、画面は付いていません。

データバインディングコンテキストを展開する

合成の展開

APL for Audioの合成にはパラメーターがあります。合成をインフレートすると、名前付きのパラメーターがデータバインディングコンテキストに追加されます。

以下は、SSMLを使って「Joey」の音声を適用する単純な合成の例です。

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

{
  "compositions": {
    "JoeyVoice": {
      "description": "常にJoeyの音声を適用するspeechコンポーネントの基本的なラッパーです",
      "parameters": [
        {
          "name": "speechContent",
          "type": "string"
        }
      ],
      "item": {
        "type": "Speech",
        "contentType": "SSML",
        "content": "<speak><voice name='Joey'><lang xml:lang='ja-JP'>${speechContent}</lang></voice></speak>"
      }
    }
  }
}

ドキュメントのmainTemplateを使ってカスタム合成を参照します。

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

{
  "type": "JoeyVoice",
  "when": "${environment.alexaLocale == 'ja-JP'}",
  "speechContent": "こんにちは"
}

この例では、speechContentは、カスタム合成JoeyVoiceのパラメーターです。ドキュメントでJoeyVoiceを使うと、Alexaは、speechContentパラメーターとその値をデータバインディングコンテキストに追加します。これにより、合成は${speechContent}のような式を使ってパラメーターの値を参照します。

speechContentに値を指定しない場合、Alexaは、パラメーターにデフォルト値を設定してデータバインディングコンテキストに追加します。合成を定義する際、パラメーターのデフォルト値を指定できます。上の例では、speechContentのデフォルト値を定義していないため、この例のデフォルト値はnullとなります。

この追加されたデータバインディングコンテキストは、カスタム合成とその子コンポーネントをインフレートする際に有効です。

コンポーネントの子要素の展開

Sequencerなど、一部のコンポーネントは複数の子を持ちます。複数の子を持つコンポーネントでは、データバインディングコンテキストに次のグローバル名が追加されます。

名前	説明
`data`	コンポーネントのインフレート中に`data`プロパティから割り当てられるデータです。`data`の詳細については、データ配列のインフレートを参照してください。
`index`	現在の子コンポーネントの0から始まるインデックスです。
`length`	現在のコンポーネントに含まれている子コンポーネントの合計数です。

dataは、複数子コンポーネントのdataプロパティを設定した場合に設定されます。

配列を使ったデータバインディング

多くのAPL式には配列の評価が含まれます。APLは、配列型の強制、暗黙的な配列化、データバインディング式の配列への補間をサポートしています。

配列型の強制

プロパティ定義で既知の型の配列が指定されている場合、配列の各要素には、プロパティの割り当て時にその型が強制されます。たとえば、数値の配列が想定された合成であれば、割り当て時にその配列の各要素に数値が強制されます。

暗黙的な配列化

便宜上、値の配列をとるすべてのAPLプロパティには、配列の角かっこを持たない単一のプロパティを使用することもできます。たとえば、Sequencerのitemsプロパティはコンポーネントの配列をとります。itemsに渡される項目が1つだけの場合は、次のアプローチは同じ意味を持ちます。

"item": {<<項目>>}
"item": [ {<<項目>>} ]

APLランタイムは、どちらも長さ1の配列に展開します。

配列を想定するプロパティには複数形のエイリアスがあります。したがって、itemとitemsは同じプロパティを表します。これにより、コードが読みやすくなります。

データバインディング式の配列への補間

配列の展開では、配列から配列への補間がサポートされます。次に例を示します。

// コンテキスト
{
  "a": "apple",
  "b": [ "alpha", "bravo" ]
}

"values": "${a}" -> values = [ "apple" ] // 暗黙的な配列化
"values": [ "${a}" ] -> values = [ "apple" ]
"values": "${b}" -> values = [ "alpha", "bravo" ]
"values": [ "x", "${b}", "${a}" ] -> values = [ "x", "alpha", "bravo", "apple" ]

配列化のルールは次のとおりです。

値が文字列の場合は、データバインディングを使用して評価し、正しい型を強制します（そのうえで配列化を適用します）。
値が配列の場合は、次のようになります。
- 配列の各要素が文字列である場合、データバインディングを使用してその要素を評価します。結果が単一の項目の場合は、それを配列に挿入します。
- 配列の各要素が項目の配列である場合、すべての項目を配列に挿入します。

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

フィードバックを送信

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

データバインディングの評価（APL for Audio）

データバインディングアルゴリズム

ステップ1： 式の評価

ステップ2： 型の強制

初期状態のデータバインディングコンテキスト

environment

データバインディングコンテキストを展開する

合成の展開

コンポーネントの子要素の展開

配列を使ったデータバインディング

配列型の強制

暗黙的な配列化

データバインディング式の配列への補間

ステップ1：式の評価

ステップ2：型の強制