APLデータソース(1.0)
(これはAPLの最新バージョンではありません。APLの最新バージョンの資料を参照するには、その他のバージョンオプションをクリックしてください)
データソースとは、APLドキュメントにバインドできるデータのソースを定義するJSON構造のことです。APLドキュメントをAlexaに送信するときに、1つ以上のデータソースを含めることができます。データソースとは、APLドキュメントのパラメーターに名前でバインドされます。ドキュメント内のAPLコンポーネントでは、${..}
スタイルのAPLデータバインディングの式を使用して、該当するデータソースを参照できます。
スキル応答の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": {},
"datasources": {
"myDocumentData": {
"title": "これはとても単純な例です"
}
}
}
]
}
}
ドキュメントのデータソースにアクセスする
データソースにアクセスするには、APLドキュメントのmainTemplate
で、payload
というパラメーターを宣言します。このパラメーターは、応答の中でdatasources
オブジェクトのルートに割り当てられます。したがって、ドキュメント内から、構文${payload.dataSourceName.propertyName}
を使用して、ドキュメント内のプロパティをデータソース内のプロパティにバインドできます。
次の応答ではmyDocumentData
という1つのデータソースにバインドするAPLドキュメントを示しています。この場合、Text
コンポーネントのtext
プロパティは、myDocumentData
データソースのtitle
プロパティにバインドされています。スキルがこの応答をAlexaに送信すると、デバイスでは「これはとても単純な例です」というテキストが表示されます。
{
"version": "1.0",
"sessionAttributes": {},
"response": {
"outputSpeech": {
"type": "SSML",
"ssml": "<speak>これは例です</speak>"
},
"directives": [
{
"type": "Alexa.Presentation.APL.RenderDocument",
"token": "[SkillProvidedToken]",
"document": {
"type": "APL",
"version": "1.0",
"theme": "auto",
"import": [
{
"name": "alexa-layouts",
"version": "1.0.0"
}
],
"resources": [],
"styles": {},
"layouts": {},
"mainTemplate": {
"parameters": [
"payload"
],
"items": [
{
"type": "Container",
"width": "100vw",
"height": "100vh",
"items": [
{
"type": "Text",
"text": "${payload.myDocumentData.title}"
}
]
}
]
}
},
"datasources": {
"myDocumentData": {
"title": "これはとても単純な例です"
}
}
}
]
}
}
オブジェクト型のデータソース
上記の単純なデータソースは、一連のプロパティを定義する、型付けされていないデータソースの例です。APLでは、定義された構造に従った型付けされたデータソースもサポートしています。これにより、トランスフォーマーを使用してデータを操作するなど、追加機能を利用できるようになります。
型付けされたデータソースには、以下のプロパティがあります。
[SpeakItemコマンド]を使用して音声を読み上げるための式です。トランスフォーマーを参照してください。
プロパティ | 型 | 必須 | 説明 |
---|---|---|---|
type | オブジェクト | ◯ | 「オブジェクト」である必要があります。 |
properties | オブジェクト | ✕ | トランスフォーマーで使用できるバインド可能なプロパティを含むオブジェクトです。 |
objectID | 文字列 | ✕ | オブジェクトデータソースの任意の識別子です。 |
description | 文字列 | ✕ | データソースの任意の説明です。 |
transformers | 配列 | ✕ | プロパティオブジェクトの値に適用されるトランスフォーマーの配列です。 |
この例は、ssmlToSpeech
トランスフォーマーを使用したオブジェクトデータソースを示しています。トランスフォーマーはproperties
オブジェクト内のデータを参照します。トランスフォーマーの使用方法について詳しくは、後述のトランスフォーマーをご覧ください。
{
"myDocumentData": {
"type": "object",
"properties": {
"title": "これはとても単純な例です"
},
"transformers": [
{
"inputPath": "title",
"outputName": "titleSpeech",
"transformer": "ssmlToSpeech"
}
]
}
}
トランスフォーマー
トランスフォーマーは、データソースのデータを別の表現に変換します。RenderDocument
ディレクティブは現在、次の3つのトランスフォーマーをサポートしています。
-
ssmlToSpeech
: プレーンテキストまたは音声合成マークアップ言語(SSML)を、APLコンポーネントのspeech
プロパティとのバインディングに適した音声に変換します。その後、SpeakItem
APLコマンドを使用して、コンポーネントに関連付けられた音声を読み上げることができます。audioタグをssmlToSpeech
トランスフォーマーと一緒に使うことはできません。 -
ssmlToText
: SSMLをプレーンテキストに変換するトランスフォーマーです。 -
textToHint
: Alexaヒント文字列に、ウェイクワード(アレクサ、コンピューター、エコー、アマゾンなど)をテキストに変換して追加するトランスフォーマーです。
トランスフォーマーのプロパティと変換規則
トランスフォーマーは、データソース内の名前付きプロパティのデータ変換を実行して、元のデータソースのプロパティにデータを書き込みます。outputName
が指定されていない場合、トランスフォーマーはinput
プロパティを上書きします。すべてのトランスフォーマーには、次の表に示す基本プロパティがあります。
プロパティ | 型 | 必須 | 説明 |
---|---|---|---|
transformer | 文字列 | ◯ | トランスフォーマーのタイプです。 |
inputPath | 文字列 | ◯ | オブジェクト内の、変換される部分へのパスです。 |
outputName | 文字列 | ✕ | オブジェクトに追加されるプロパティの名前です。outputName が指定されていない場合、inputPath は変換された出力で上書きされます。 |
inputPath
はソースオブジェクトの1つのエンティティを一義的に参照するか、ワイルドカードのプロパティまたは未解決配列を使ってエンティティセットを参照することができます。inputPath
と一致するプロパティが変換されます。inputPath
パターンはシンボルで、一定数のノードまたはワイルドカード参照が後に続きます。
次のルールが適用されます。
-
シンボル名または配列インデックスは、プロパティブロック内の既存のオブジェクトプロパティまたは配列インデックスと一致する必要があります。一致しない場合、変換は破棄されます。
-
出力が保存されている場所は、ワイルドカード以外の最後のノードをoutputNameで置き換えることで見つけられます。ワイルドカード以外のノードがない場合は、シンボルはoutputNameで置き換えられます。
-
最後のワイルドカード以外のノードが数値インデックスになることはありません。最後のワイルドカード以外のノードが数値の場合は、変換は破棄されます。
これらの例は、参照のしくみを示しています。次のサンプルデータを考えてみましょう。
{
"myDocumentData": {
"type": "object",
"properties": {
"name": "山田太郎",
"address": {
"street": "中央通り301番地",
"city": "目黒区"
},
"family": [
{
"name": "花子",
"relation": "妻"
},
{
"name": "桜子",
"relation": "娘"
}
],
"contacts": [
"鈴木一郎",
"鈴木梅子"
]
},
"transformers": [
{
"inputPath": [],
"outputName": [],
"transformer": "ssmlToSpeech"
}
]
}
}
inputPath | 変換される項目 | 結果の保存場所 |
name | "山田太郎" | outputName |
address.street | "中央通り301番地" | address.outputName |
contacts.* | ["鈴木一郎", "鈴木梅子"] | outputName[0], outputName[1] |
family[0].name | "花子" | family[0].outputName |
family[*].name | "花子", "桜子" | family[0].outputName, family[1].outputName |
address.* | "中央通り301番地", "目黒区" | outputName.street, outputName.city |
以下は機能しません。
-
family[3].name - 機能しません - ルール1を参照してください。
-
family[1].names - 機能しません - ルール1を参照してください。
-
family[0] { "name": "花子", "relation": "妻" } 機能しません - ルール3を参照してください。
ssmlToSpeechトランスフォーマー
SSMLから音声に変換するトランスフォーマーは、SSML文字列を音声に適したエンティティに変換します。SSMLから音声に変換するトランスフォーマーには、次の表に示すプロパティがあります。
プロパティ | 型 | 必須 | 説明 |
---|---|---|---|
transformer | ssmlToSpeech | ◯ | トランスフォーマーの名前です。 |
inputPath | 文字列 | ◯ | オブジェクト内から変換される部分へのパスです。 |
outputName | 文字列 | ◯ | オブジェクトに追加されるプロパティの名前です。 |
SSMLから音声に変換するトランスフォーマーからの出力は、コンポーネントのspeechプロパティに関連付けられている必要があります。下記のコードは、猫の秘密にバインドされたTextコンポーネントに音声を関連付けた「猫の秘密」スキルを示しています。
{
"type": "Container",
"item": {
"type": "Text",
"id": "catFactText",
"text": "${payload.catFactData.properties.catFact}",
"speech": "${payload.catFactData.properties.catFactSpeech}"
}
}
次に、下記のコードは、スキルリクエストの一部として送信する必要がある、対応するオブジェクトデータソースとトランスフォーマーを示しています。
{
"catFactData": {
"type": "object",
"properties": {
"backgroundImage": "https://.../catfacts.png",
"title": "猫の秘密 #9",
"logoUrl": "https://.../logo.png",
"image": "https://.../catfact9.png",
"catFactSsml": "<speak>すべての猫が<emphasis level='strong'>マタタビ</emphasis>を好むとは限りません。</speak>"
},
"transformers": [
{
"inputPath": "catFactSsml",
"outputName": "catFactSpeech",
"transformer": "ssmlToSpeech"
},
{
"inputPath": "catFactSsml",
"outputName": "catFact",
"transformer": "ssmlToText"
}
]
}
}
最後に、猫の秘密を読み上げるには、Alexa.Presentation.APL.ExecuteCommands
ディレクティブをSpeakItem
コマンドで使用する必要があります。下記のコードは、猫の秘密を読み上げるために使用できるAlexa.Presentation.APL.ExecuteCommands
ディレクティブを示します。ExecuteCommands
ディレクティブで渡しているトークンは必須です。このトークンは、APLドキュメントの表示に使用するRenderDocument
ディレクティブでスキルによって渡されるトークンと一致する必要があります。
{
"type": "Alexa.Presentation.APL.ExecuteCommands",
"token": "[SkillProvidedToken]",
"commands": [
{
"type": "SpeakItem",
"componentId": "catFactText",
"highlightMode": "line",
"align": "center"
}
]
}
ssmlToTextトランスフォーマー
SSMLからテキストに変換するトランスフォーマーは、SSMLマークアップを削除することで、すべてのSSMLテキスト文字列を人が読みやすいテキストに変換します。このプロパティは、トランスフォーマー値をssmlToTextに設定する必要がある点を除いて、ssmlToSpeech
トランスフォーマーと同じです。
textToHintトランスフォーマー
スキル開発者は、デバイスのウェイクワードを推測したり、「Alexa」をデフォルトにしたりしなくても、textToHint
トランスフォーマーを使用して、APLドキュメントに表示されるヒント文字列に正しいウェイクワードを自動で追加できます。textToHint
トランスフォーマーは、AlexaFooterレイアウトにバインドされたオブジェクトタイプのデータソースのプロパティに適用されます。次の表は、textToHint
トランスフォーマーに適用可能なプロパティを示しています。
プロパティ | 型 | 必須 | 説明 |
transformer | textToHint | ◯ | テキストをヒントに変換するトランスフォーマーを呼び出すには、このプロパティをtextToHint に設定する必要があります。 |
inputPath | 文字列 | ◯ | 変換が必要なデータソースの値のパスです。 |
outputName | 文字列 | ✕ | 変換された出力を格納するデータソースのプロパティ名です。この出力プロパティは、入力プロパティと常に兄弟関係にあります。このため、outputName を指定しないと、inputPath 内の値がトランスフォーマーの出力値で置き換えられます。 |
ヒントを表示するには、alexa-layouts
パッケージをAPLドキュメントに読み込み、このパッケージの一部であるAlexaFooter
をAPLドキュメントで使用します。以下のコードサンプルでは、AlexaFooter
レイアウトを使用してヒントを表示するAPLドキュメントを示しています。AlexaFooterのfooterHint
プロパティが、catFactData
データソースのプロパティにどのようにバインドされているかに注意してください。
{
"type": "APL",
"version": "1.0",
"import": [{
"name": "alexa-layouts",
"version": "1.0.0"
}],
"mainTemplate": {
"parameters": [
"payload"
],
"items": [
{
"type": "Container",
"items": [
{
"type": "AlexaHeader",
"title": "${payload.catFactData.properties.title}",
"attributionImage": "${payload.catFactData.properties.logoUrl}"
}
]
},
{
"type": "ScrollView",
"item": {
"type": "Text",
"id": "catFactText",
"text": "${payload.catFactData.properties.catFact}"
}
},
{
"type": "AlexaFooter",
"footerHint": "${payload.catFactData.properties.hintString}"
}
]
}
}
以下のコードは、スキル開発者がデータソースをAlexaFooterのfooterHint
にバインドする方法を示しています。例としてcatFactData
を取り上げると、catFactData
のデータソースには、データソースのhintString
プロパティに適用されるtextToHint
トランスフォーマーが含まれています。トランスフォーマーを使用するには、変換するプロパティをオブジェクトデータソース内のproperties
オブジェクトに配置する必要があります。このトランスフォーマーによって、hintString
がエンドユーザーに表示される「アレクサ、…と言ってみましょう」形式のヒントに変換されます。
{
"datasources": {
"catFactData": {
"type": "object",
"properties": {
"title": "猫の秘密 #9",
"logoUrl": "https://.../logo.png",
"catFact": "すべての猫がマタタビを好むとは限りません。",
"hintString": "ペルシャ猫の秘密を教えて"
},
"transformers": [
{
"inputPath": "hintString",
"transformer": "textToHint"
}
]
}
}
}