Структурированный шаблон ответа
ОБЛАСТЬ ПРИМЕНЕНИЯ: ПАКЕТ SDK версии 4
Структурированный шаблон ответа позволяет разработчикам определять сложную структуру с поддержкой большого набора функций компонента Создание текста, таких как работа с шаблонами и композиция. При этом за интерпретацию структурированного ответа отвечает объект, вызывающий библиотеку Создателя текста.
Для приложений ботов предоставляется следующая поддержка:
- Определение действия
- определение карта
Шаблон действия Bot Framework включает несколько настраиваемых полей. Следующие свойства наиболее часто используются и настраиваются с помощью определения шаблона действия:
Свойство | Вариант использования |
---|---|
Текст | Отображаемый текст, на основе которого канал создает визуальное представление. |
Говорите | Произносимый текст, на основе которого канал создает звуковое представление. |
Вложения | Список вложений с указанием типов. Используется каналами для отображения в виде карточек пользовательского интерфейса или других универсальных типов вложенных файлов. |
SuggestedActions | Список действий, отображаемых в качестве предложений для пользователя. |
InputHint | Управляет состоянием потока записи звука на устройствах, поддерживающих речевой ввод. Возможные значения: accepting , expecting или ignoring . |
По умолчанию сопоставитель шаблонов не реализует резервное поведение. Если свойство не указано, оно остается неопределенным. Например, значение свойства Speak
не передается автоматически в свойство Text
, если задано только свойство Text
.
Определение
Пример определения структурированного шаблона:
# 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 карта. Например, оба image
images
поля поддерживаются во всех определениях карта в LG, хотя только images
поддерживаются в определении пакета SDK карта.
Значения, определенные во всех полях image
images
в карта heroCard или эскизов, объединяются и преобразуются в список изображений в созданном карта. Для других типов карта для поля будет назначено последнее определенное значение в шаблоне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
]
По умолчанию любая ссылка на шаблон вычисляется один раз во время вычисления структурированного шаблона.
Например, # AskForAge.prompt
возвращает один и тот же текст разрешения для обоих свойств Speak
и Text
.
# AskForAge.prompt
[Activity
Text = ${GetAge()}
Speak = ${GetAge()}
]
# GetAge
- how old are you?
- what is your age?
Вы можете применить <TemplateName>!()
, чтобы запросить новую оценку каждой ссылки в структурированном шаблоне.
В приведенном ниже примере Speak
и Text
могут иметь разные текстовые разрешения, так как GetAge
заново оценивается для каждого экземпляра.
[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
]
Используйте \ в качестве escape-символа.
> 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
]
Обратите внимание, что этот стиль композиции может существовать только на корневом уровне. Если в свойстве есть ссылка на другой структурированный шаблон, при разрешении учитывается контекст этого свойства.
Ссылка на внешний файл в структурированном вложении
Есть две встроенные функции для создания ссылок на внешние файлы.
fromFile(fileAbsoluteOrRelativePath)
загружает указанный файл. Содержимое, возвращаемое этой функцией, будет поддерживать оценку содержимого. Вычисляются ссылки на шаблон, свойства и выражения.ActivityAttachment(content, contentType)
задает значение,contentType
если оно еще не указано в содержимом.
Эти две встроенные функция позволяют получить любое внешнее содержимое, в том числе любые типы карточек. Используйте следующие структурированные шаблоны создания текста, чтобы определить действие:
# 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'))}
]
Дополнительная информация
- Справочник по API C#
- Справочник по JavaScript API
- Чтение отладки с помощью адаптивных инструментов , чтобы узнать, как анализировать и отлаживать шаблоны.