Поделиться через


Структурированный шаблон ответа

ОБЛАСТЬ ПРИМЕНЕНИЯ: ПАКЕТ 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
]

Обратите внимание, что этот стиль композиции может существовать только на корневом уровне. Если в свойстве есть ссылка на другой структурированный шаблон, при разрешении учитывается контекст этого свойства.

Ссылка на внешний файл в структурированном вложении

Есть две встроенные функции для создания ссылок на внешние файлы.

  1. fromFile(fileAbsoluteOrRelativePath) загружает указанный файл. Содержимое, возвращаемое этой функцией, будет поддерживать оценку содержимого. Вычисляются ссылки на шаблон, свойства и выражения.
  2. 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'))}
]

Дополнительная информация