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

適用対象: SDK v4APPLIES TO: SDK v4

構造化された応答テンプレートにより、開発者は、構造化された応答の解釈を LG ライブラリの呼び出し元に任せながら、テンプレート作成、コンポジションなどの言語の生成 (LG) の広範な機能をサポートする複雑な構造を定義できます。Structured response templates let developers define a complex structure that supports the extensive functionality of Language generation (LG), like templating, composition, while leaving the interpretation of the structured response up to the caller of the LG library.

Bot アプリケーションでは、次のサポートが提供されます。For bot applications, the following support is provided:

Bot Framework アクティビティテンプレートには、カスタマイズ可能なフィールドがいくつか含まれています。The Bot Framework activity template includes several customizable fields. 次のプロパティは最も一般的に使用され、アクティビティテンプレート定義を使用して構成できます。The following properties are the most commonly used and are configurable via an activity template definition:

プロパティProperty 使用事例Use case
TextText チャネルによって視覚的にレンダリングするために使用されるテキストを表示しますDisplay text used by the channel to render visually
SpeakSpeak チャネルによって音声でレンダリングするために使用される音声テキストSpoken text used by the channel to render audibly
[Attachments]Attachments 添付ファイルとそれらの種類の一覧。List of attachments with their type. チャネルによって UI カードまたはその他の汎用添付ファイルの種類としてレンダリングするために使用されます。Used by channels to render as UI cards or other generic file attachment types.
SuggestedActionsSuggestedActions ユーザーへの提案としてレンダリングされるアクションの一覧。List of actions rendered as suggestions to user.
InputHintInputHint 音声入力をサポートするデバイスでオーディオ キャプチャ ストリームの状態を制御します。Controls audio capture stream state on devices that support spoken input. 指定できる値は、acceptingexpecting、または ignoring です。Possible values include accepting, expecting, or ignoring.

テンプレート リゾルバーによって実装される既定のフォールバック動作はありません。There is no default fallback behavior implemented by the template resolver. プロパティが指定されていない場合、未指定のままになります。If a property is not specified, then it remains unspecified. たとえば、Text プロパティのみが指定されている場合、Text プロパティとして Speak プロパティが自動的に割り当てられません。For example, the Speak property isn't automatically assigned to be the Text property if only the Text property is specified.

定義Definition

構造化されたテンプレートの定義を次に示します。Here's the definition of a structured template:

# 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
]

基本的なテキスト テンプレートの例を次に示します。Here's an example of a basic text template:

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

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

推奨されるアクションを含むテキストの例を次に示します。Here's an example of text with a suggested action. リストを示すには、 | を使用します。Use | to denote a list.

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

ヒーロー カード定義の例を次に示します。Here's an example of a Hero card definition:

# 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 カード定義に合わせて変換されます。LG provides some variability in card definition, which is converted to align with the SDK card definition. たとえば、との両方の image images フィールドは、 images SDK カード定義でのみサポートされていますが、LG のすべてのカード定義でサポートされています。For example, both image and images fields are supported in all the card definitions in LG even though only images are supported in the SDK card definition.

imageHeroCard またはサムネイルカード内のフィールドとフィールドのすべてに定義されている値が組み合わされ、生成された images カードの画像リストに変換されます。The values defined in all of the image and images fields in a HeroCard or thumbnail card are combined and converted to an images list in the generated card. その他の種類のカードでは、テンプレートに定義されている最後の値がフィールドに割り当てられ image ます。For the other types of cards, the last defined value in the template will be assigned to the image field. フィールドに割り当てる値は、 image/images 文字列、 正規表現、またはを使用した形式の配列にすることができ | ます。The values you assign to the image/images field can be a string, adaptive expression, or array in the format using |.

前のテンプレートの組み合わせを次に示します。Below is the combination of the previous templates:

# 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 回評価されます。By default any template reference is evaluated once during evaluation of a structured template.

たとえば、# AskForAge.prompt では、SpeakText の両方のプロパティに対して、同じ解決テキストを返します。For example, # AskForAge.prompt returns the same resolution text for both the Speak and Text properties.

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

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

<TemplateName>!() を使用して、構造化されたテンプレート内の各参照に対して新しい評価を要求できます。You can use <TemplateName>!() to request a new evaluation on each reference within a structured template.

次の例では、各インスタンスで GetAge が再評価されるため、SpeakText の解決テキストが異なる可能性があります。In the example below, Speak and Text may have different resolution text because GetAge is re-evaluated on each instance.

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

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

カードのカルーセルを表示する方法を次に示します。Here's how to display a carousel of cards:

# 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
]

\ エスケープ文字として使用します。Use \ as an escape character.

> 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
]

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

構造化されたテンプレートでは、次のコンポジション動作がサポートされています。The following composition behavior is supported with structured templates:

  • コンポジションは構造コンテキストに対応しています。Composition is structure context-aware. 参照されているターゲット テンプレートも構造化されたテンプレートである場合は、構造の型が一致している必要があります。If the target template being referred is also a structured template, then the structure type must match. たとえば、ActivityTemplate は別の ActivityTemplate で参照できます。For example, an ActivityTemplate can be referred to in another ActivityTemplate.
  • シンプルな応答テンプレートまたは条件付き応答テンプレートへの参照は、構造化されたテンプレート内のどこでも存在できます。References to simple or conditional response template can exist anywhere inside a structured template.

次のテンプレートがあるとします。Suppose you have the following template:

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

# T2
- This is awesome

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

evaluateTemplate('T1') を呼び出すと、次の内部構造になります。A call to evaluateTemplate('T1') would result in the following internal structure:

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

別の構造化されたテンプレートへの完全な参照Full reference to another structured template

別の構造化されたテンプレートへの参照を、別の構造化されたテンプレートにプロパティとして、または別のシンプルな応答テンプレートまたは条件付き応答テンプレートに参照として、含めることができますYou can include a reference to a another structured template as a property in another structured template, or as a reference in another simple or conditional response template

別の構造化されたテンプレートへの完全な参照の例を次に示します。Here's an example of full reference to another structured template:

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

このコンテンツでは、evaluateTemplate('ST1') を呼び出すと、次の内部構造になります。With this content, a call to evaluateTemplate('ST1') will result in the following internal structure:

[MyStruct
    Text = foo
    Speak = bar
]

呼び出し元のテンプレートと呼び出し先のテンプレートの両方に同じプロパティが存在する場合、呼び出し元のコンテンツによって、呼び出し先のテンプレートのすべてのコンテンツが上書きされます。When the same property exists in both the calling template as well as the called template, the content in the caller will overwrite any content in the called template.

次に例を示します。Here's an example:

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

このコンテキストでは、evaluateTemplate('ST1') を呼び出すと、次の内部構造になります。With this context, a call to evaluateTemplate('ST1') will result in the following internal structure:

[MyStruct
    Text = foo
    Speak = bar
]

このスタイルのコンポジションはルート レベルにのみ存在できることに注意してください。Note that this style of composition can only exists at the root level. プロパティ内に別の構造化されたテンプレートへの参照がある場合、解決はそのプロパティのコンテキストに従います。If there is a reference to another structured template within a property, then the resolution is contextual to that property.

構造化された添付ファイルの外部ファイル参照External file reference in attachment structured

外部でファイルを参照するために使用する 2 つの事前構築された関数がありますThere are two prebuilt functions used to externally reference files

  1. fromFile(fileAbsoluteOrRelativePath) は指定されたファイルを読み込みます。fromFile(fileAbsoluteOrRelativePath) loads a specified file. この関数によって返されるコンテンツは、content.Template 参照の評価をサポートし、プロパティ/式が評価されます。Content returned by this function will support evaluation of content.Template references and properties/ expressions are evaluated.
  2. ActivityAttachment(content, contentType) は、contentType がコンテンツにまだ指定されていない場合に、それを設定します。ActivityAttachment(content, contentType) sets the contentType if it is not already specified in the content.

これらの 2 つの事前構築済み関数を使用すると、すべてのカードの種類を含む、外部で定義された任意のコンテンツをプルできます。With these two prebuilt functions, you can pull in any externally defined content, including all card types. アクティビティを構成するには、次の構造化 LG を使用します。Use the following structured LG to compose an activity:

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

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

次に示すように、添付ファイルを使用することもできます。You can also use attachments, seen below:

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

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

追加情報Additional Information