構造化された応答テンプレート

[アーティクル]
03/08/2023

適用対象: SDK v4

構造化された応答テンプレートにより、開発者は、構造化された応答の解釈を LG ライブラリの呼び出し元に任せながら、テンプレート作成、コンポジションなどの言語の生成 (LG) の広範な機能をサポートする複雑な構造を定義できます。

ボットアプリケーションの場合は、次のサポートが提供されます。

アクティビティ定義
カード定義

Bot Framework アクティビティテンプレートには、カスタマイズ可能なフィールドがいくつか含まれています。次のプロパティは最もよく使用され、アクティビティテンプレート定義を使用して構成できます。

プロパティ	使用事例
Text	チャネルによって視覚的にレンダリングするために使用されるテキストを表示します
Speak	チャネルによって音声でレンダリングするために使用される音声テキスト
[Attachments]	添付ファイルとそれらの種類の一覧。チャネルによって UI カードまたはその他の汎用添付ファイルの種類としてレンダリングするために使用されます。
SuggestedActions	ユーザーへの提案としてレンダリングされるアクションの一覧。
InputHint	音声入力をサポートするデバイスでオーディオキャプチャストリームの状態を制御します。指定できる値は、`accepting`、`expecting`、または `ignoring` です。

テンプレートリゾルバーによって実装される既定のフォールバック動作はありません。プロパティが指定されていない場合は、未指定のままです。たとえば、Text プロパティのみが指定されている場合、Text プロパティとして Speak プロパティが自動的に割り当てられません。

定義

構造化されたテンプレートの定義を次に示します。

# TemplateName
> this is a comment
[Structure-name
    Property1 = <plain text> .or. <plain text with template reference> .or. <expression>
    Property2 = list of values are denoted via '|'. e.g. a | b
> this is a comment about this specific property
    Property3 = Nested structures are achieved through composition
]

基本的なテキストテンプレートの例を次に示します。

# AskForAge.prompt
[Activity
    Text = ${GetAge()}
    Speak = ${GetAge()}
]

# GetAge
- how old are you?
- what is your age?

推奨されるアクションを含むテキストの例を次に示します。リストを示すには、 | を使用します。

> With '|' you are making attachments a list.
# AskForAge.prompt
[Activity
    Text = ${GetAge()}
    SuggestedActions = 10 | 20 | 30
]

ヒーローカード定義の例を次に示します。

# HeroCard
[Herocard
    title = Hero Card Example
    subtitle = Microsoft Bot Framework
    text = Build and connect intelligent bots to interact with your users naturally wherever they are, from text/sms to Skype, Slack, Office 365 mail and other popular services.
    images = https://sec.ch9.ms/ch9/7ff5/e07cfef0-aa3b-40bb-9baa-7c9ef8ff7ff5/buildreactionbotframework_960.jpg
    buttons = Option 1| Option 2| Option 3
]

注意

LG は、SDK カード定義に合わせて変換されるカード定義に可変性を提供します。たとえば、と images の両方imageのフィールドは、SDK カード定義でのみサポートされている場合imagesでも、LG のすべてのカード定義でサポートされています。

HeroCard またはサムネイルカード内のすべての image フィールドと images フィールドで定義された値が結合され、生成されたカードの画像リストに変換されます。他の種類のカードの場合、テンプレートで最後に定義された値がフィールドに image 割り当てられます。フィールドに image/images 割り当てる値には、を使用した文字列、アダプティブ式、または形式の配列を指定 |できます。

前のテンプレートの組み合わせを次に示します。

# AskForAge.prompt
[Activity
    Text = ${GetAge()}
    Speak = ${GetAge()}
    Attachments = ${HeroCard()}
    SuggestedActions = 10 | 20 | 30
    InputHint = expecting
]

# GetAge
- how old are you?
- what is your age?

# HeroCard
[Herocard
    title = Hero Card Example
    subtitle = Microsoft Bot Framework
    text = Build and connect intelligent bots to interact with your users naturally wherever they are, from text/sms to Skype, Slack, Office 365 mail and other popular services.
    images = https://sec.ch9.ms/ch9/7ff5/e07cfef0-aa3b-40bb-9baa-7c9ef8ff7ff5/buildreactionbotframework_960.jpg
    buttons = Option 1| Option 2| Option 3
]

既定で、すべてのテンプレート参照は、構造化されたテンプレートの評価時に 1 回評価されます。

たとえば、# AskForAge.prompt では、Speak と Text の両方のプロパティに対して、同じ解決テキストを返します。

# AskForAge.prompt
[Activity
    Text = ${GetAge()}
    Speak = ${GetAge()}
]

# GetAge
- how old are you?
- what is your age?

<TemplateName>!() を使用して、構造化されたテンプレート内の各参照に対して新しい評価を要求できます。

次の例では、各インスタンスで GetAge が再評価されるため、Speak と Text の解決テキストが異なる可能性があります。

[Activity
    Text = ${GetAge()}
    Speak = ${GetAge!()}
]

# GetAge
- how old are you?
- what is your age?

カードのカルーセルを表示する方法を次に示します。

# AskForAge.prompt
[Activity
> Defaults to carousel layout in case of list of cards
    Attachments = ${foreach($cardValues, item, HeroCard(item)}
]

# AskForAge.prompt_2
[Activity
> Explicitly specify an attachment layout
    Attachments = ${foreach($cardValues, item, HeroCard(item)}
    AttachmentLayout = list
]

# HeroCard (title, subtitle, text)
[Herocard
    title = ${title}
    subtitle = ${subtitle}
    text = ${text}
    images = https://sec.ch9.ms/ch9/7ff5/e07cfef0-aa3b-40bb-9baa-7c9ef8ff7ff5/buildreactionbotframework_960.jpg
    buttons = Option 1| Option 2| Option 3
]

\ をエスケープ文字として使用します。

> You can use '\' as an escape character
> \${GetAge()} would not be evaluated as expression, would be parsed as '${getAge()}' string
# AskForAge.prompt
[Activity
        Text = \${GetAge()}
        SuggestedActions = 10 \| cards | 20 \| cards
]

構造化されたテンプレートのコンポジション

構造化されたテンプレートでは、次のコンポジション動作がサポートされています。

コンポジションは構造コンテキストに対応しています。参照されているターゲットテンプレートも構造化されたテンプレートである場合は、構造の型が一致している必要があります。たとえば、ActivityTemplate は別の ActivityTemplate で参照できます。
シンプルな応答テンプレートまたは条件付き応答テンプレートへの参照は、構造化されたテンプレート内のどこでも存在できます。

次のテンプレートがあるとします。

# T1
[Activity
    Text = ${T2()}
    Speak = foo bar ${T3().speak}
]

# T2
- This is awesome

# T3
[Activity
    Speak = I can also speak!
]

evaluateTemplate('T1') を呼び出すと、次の内部構造になります。

[Activity
    Text = This is awesome
    Speak = I can also speak!
]

別の構造化されたテンプレートへの完全な参照

別の構造化テンプレートへの参照を、別の構造化テンプレートのプロパティとして、または別の単純または条件付き応答テンプレートの参照として含めることができます。

別の構造化されたテンプレートへの完全な参照の例を次に示します。

# ST1
[MyStruct
    Text = foo
    ${ST2()}
]
# ST2
[MyStruct
    Speak = bar
]

このコンテンツでは、evaluateTemplate('ST1') を呼び出すと、次の内部構造になります。

[MyStruct
    Text = foo
    Speak = bar
]

呼び出し元のテンプレートと呼び出し先のテンプレートの両方に同じプロパティが存在する場合、呼び出し元のコンテンツによって、呼び出し先のテンプレートのすべてのコンテンツが上書きされます。

次に例を示します。

# ST1
[MyStruct
    Text = foo
    ${ST2()}
]
# ST2
[MyStruct
    Speak = bar
    Text = zoo
]

このコンテキストでは、evaluateTemplate('ST1') を呼び出すと、次の内部構造になります。

[MyStruct
    Text = foo
    Speak = bar
]

この構成スタイルはルートレベルでのみ存在できることに注意してください。プロパティ内に別の構造化されたテンプレートへの参照がある場合、解決はそのプロパティのコンテキストに従います。

構造化された添付ファイルの外部ファイル参照

外部でファイルを参照するために使用する 2 つの事前構築された関数があります

fromFile(fileAbsoluteOrRelativePath) は指定されたファイルを読み込みます。この関数によって返されるコンテンツは、コンテンツの評価をサポートします。テンプレート参照、プロパティ、および式が評価されます。
ActivityAttachment(content, contentType) は、コンテンツで contentType まだ指定されていない場合はを設定します。

これらの 2 つの事前構築済み関数を使用すると、すべてのカードの種類を含む、外部で定義された任意のコンテンツをプルできます。アクティビティを構成するには、次の構造化 LG を使用します。

# AdaptiveCard
[Activity
                Attachments = ${ActivityAttachment(json(fromFile('../../card.json')), 'adaptiveCard')}
]

# HeroCard
[Activity
                Attachments = ${ActivityAttachment(json(fromFile('../../card.json')), 'heroCard')}
]

次に示すように、添付ファイルを使用することもできます。

# AdaptiveCard
[Attachment
    contenttype = adaptivecard
    content = ${json(fromFile('../../card.json'))}
]

# HeroCard
[Attachment
    contenttype = herocard
    content = ${json(fromFile('../../card.json'))}
]

追加情報

C# API リファレンス
JavaScript API リファレンス
テンプレートを分析およびデバッグする方法については、「アダプティブツールを使用したデバッグ」を参照してください。