トランスフォーマー
トランスフォーマーは、データソースのデータを別の表現に変換します。オブジェクトデータソースのtransformers
プロパティにトランスフォーマーオブジェクトの配列を含めることができます。
- 利用可能なトランスフォーマー
- トランスフォーマーのプロパティと変換規則
- ssmlToSpeechトランスフォーマー
- ssmlToTextトランスフォーマー
- textToHintトランスフォーマー
- textToSpeechトランスフォーマー
- 関連トピック
利用可能なトランスフォーマー
利用可能なトランスフォーマーは4つあります。
ssmlToSpeech
: 音声合成マークアップ言語(SSML)の入力値を、APLコンポーネントのspeech
プロパティにバインドできる音声に変換します。その後、SpeakItem
APLコマンドを使用して、コンポーネントに関連付けられた音声を読み上げることができます。audioタグをssmlToSpeech
トランスフォーマーと一緒に使うことはできません。このトランスフォーマーに渡されるテキストは、<speak>
タグで囲まれた有効なSSMLである必要があります。ssmlToText
: 入力したSSMLをプレーンテキストに変換します。textToHint
: 入力された値を、デバイスに応じた正しいウェイクワードとヒント(「アレクサ、ヒントです」と言ってみて)に変換します。デバイスに応じたウェイクワードが選択されるので、ヒントに「アレクサ」という語をハードコーディングしないでください。textToSpeech
: 入力したプレーンテキストをAPLコンポーネントのspeech
プロパティにバインドできる音声に変換します。その後、SpeakItem
APLコマンドを使用して、コンポーネントに関連付けられた音声を読み上げることができます。
トランスフォーマーのプロパティと変換規則
トランスフォーマーは、データソース内の名前付きプロパティのデータ変換を実行して、元のデータソースのプロパティにデータを書き込みます。outputName
が指定されていない場合、トランスフォーマーはinput
プロパティを上書きします。すべてのトランスフォーマーには、次の表に示す基本プロパティがあります。
プロパティ | 型 | 必須 | 説明 |
---|---|---|---|
transformer | 文字列 | ◯ | トランスフォーマーのタイプです。 |
inputPath | 文字列 | ◯ | オブジェクト内の、変換するコンテンツへのパスです。データソースのproperties オブジェクト内のプロパティを参照する必要があります。 |
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": "textToSpeech"
}
]
}
}
次の表は、inputPath
とoutputName
のさまざまな値によって、上記のデータソースのデータがどのように変換されるかを示しています。
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 | 無効:family 配列にはインデックス3の値が指定されていません。 |
|
family[1].names | 無効:family[1] の値にはnames プロパティが指定されていません。 |
|
family[0] | { "name": "花子", "relation": "妻" } | 無効:最後のワイルドカード以外のノードが数値インデックスになることはありません。 |
ssmlToSpeechトランスフォーマー
ssmlToSpeech
トランスフォーマーは、SSML文字列を音声に適したエンティティに変換します。このトランスフォーマーに渡されるテキストは、<speak>
タグで囲まれた有効なSSMLである必要があります。プレーンテキストの場合は、代わりにtextToSpeech
トランスフォーマーを使用してください。
ドキュメントにおいて、ssmlToSpeech
トランスフォーマーの出力値をコンポーネントのspeech
プロパティにバインドします。下記のコードは、猫の秘密にバインドされたText
コンポーネントに音声を関連付けた「猫の秘密」スキルを示しています。
text
プロパティはcatFactData.properties.catFact
を指し、speech
コンポーネントはcatFactData.properties.catFactSpeech
を指します。
{
"type": "Container",
"item": {
"type": "Text",
"id": "catFactText",
"text": "${payload.catFactData.properties.catFact}",
"speech": "${payload.catFactData.properties.catFactSpeech}"
}
}
次の例は、対応するcatFactData
データソースを示しています。properties
オブジェクトには、コンポーネントで使用する実際のテキストを含むcatFactSsml
プロパティがあります。このプロパティは、ssmlToSpeech
およびssmlToText
トランスフォーマーの両方の入力値として使用されます。
ssmlToSpeech
トランスフォーマーは、catFactSsml
の値を音声に変換し、その出力値をcatFactSpeech
という新しいプロパティに格納します。catFactSpeech
プロパティは、前述のText
コンポーネントのspeech
プロパティにバインドされています。ssmlToText
トランスフォーマーは、catFactSsml
の値をプレーンテキストに変換し、出力値をcatFact
という新しいプロパティに配置します。catFact
プロパティは、前述のText
コンポーネントのtext
プロパティにバインドされています。
{
"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"
}
]
}
}
最後に、猫の秘密を読み上げるには、SpeakItem
コマンドで使用して、AlexaにAlexa.Presentation.APL.ExecuteCommands
ディレクティブを送信します。下記のコードは、猫の秘密を読み上げるために使用できる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テキスト文字列を人が読みやすいテキストに変換します。
textToHintトランスフォーマー
textToHint
トランスフォーマーは入力された値を、デバイスに応じた正しいウェイクワードとヒント(「アレクサ、ヒントです」と言ってみて)に変換します。デバイスに応じたウェイクワードが選択されるので、ヒントに「アレクサ」という語をハードコーディングしないでください。通常、このトランスフォーマーはAlexaFooter
レスポンシブ対応コンポーネントと共に使用します。
ヒントの表示例については、textToHintトランスフォーマーを使用するを参照してください。
textToSpeechトランスフォーマー
textToSpeech
トランスフォーマーは、プレーンテキストを音声に適したエンティティに変換します。このトランスフォーマーに渡されるテキストは、プレーンテキストでなければなりません。SSMLテキストの場合は、代わりにssmlToSpeech
トランスフォーマーを使用してください。
このトランスフォーマーは、ssmlToSpeech
トランスフォーマーと同じように機能します。textToSpeech
トランスフォーマーの出力値をコンポーネントのspeech
プロパティにバインドして、SpeakItem
コマンドを使用してテキストを読み上げます。
このデータソースの例では、前述のcatFactData
データソースを示していますが、catFactText
プロパティにはプレーンテキストを使用しています。この場合、catFactText
プロパティは既にプレーンテキストであるため、ssmlToText
トランスフォーマーは不要です。
{
"catFactData": {
"type": "object",
"properties": {
"backgroundImage": "https://.../catfacts.png",
"title": "猫の秘密 #9",
"logoUrl": "https://.../logo.png",
"image": "https://.../catfact9.png",
"catFactText": "すべての猫がマタタビを好むとは限りません。"
},
"transformers": [
{
"inputPath": "catFactText",
"outputName": "catFactSpeech",
"transformer": "textToSpeech"
}
]
}
}
Text
コンポーネントでは、このデータソースを次のように参照できます。
{
"type": "Container",
"item": {
"type": "Text",
"id": "catFactText",
"text": "${payload.catFactData.properties.catFactText}",
"speech": "${payload.catFactData.properties.catFactSpeech}"
}
}
text
プロパティは、変換されていないプレーンテキストのcatFactText
プロパティにバインドします。speech
プロパティはトランスフォーマーの出力値にバインドします。