Примечание
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Вызов диалогов (называемых модулями задач в TeamsJS версии 1.x) из ботов Microsoft Teams с помощью кнопок на адаптивных карточках и карточках Bot Framework, которые являются героем, эскизом и соединителем для Группы Microsoft 365. Диалоги часто лучше, чем несколько шагов диалога. Отслеживайте состояние бота и разрешайте пользователю прерывать или отменять последовательность.
Существует два способа вызова диалоговых окон:
- Новое сообщение
task/fetch
вызова. Использованиеinvoke
действия карта для карточек Bot Framework илиAction.Submit
действия карта для адаптивных карточек сtask/fetch
диалоговым окном на основе HTML или адаптивной карточки извлекается из бота динамически. - URL-адреса прямой ссылки. Используя синтаксис прямой ссылки для диалоговых окон, можно использовать
openUrl
действие карта для карточек Bot Framework илиAction.OpenUrl
действие карта для адаптивных карточек соответственно. При использовании URL-адресов прямой ссылки URL-адрес диалогового окна или текст адаптивной карточки уже известен, чтобы избежать кругового пути сервера относительноtask/fetch
.
Важно!
Каждый url
и fallbackUrl
должен реализовать протокол шифрования HTTPS.
Вызов диалогового окна с помощью task/fetch
Когда value
объект действия карточки invoke
или Action.Submit
инициализируется и когда пользователь выбирает кнопку, боту отправляется сообщение invoke
. В HTTP-ответе invoke
на сообщение есть объект TaskInfo , внедренный в объект-оболочку, который Teams использует для отображения диалогового окна (в TeamsJS версии 1.x называется модулем задач).
Предупреждение
Облачные службы Майкрософт, включая веб-версии доменов Teams, Outlook и Microsoft 365, переносятся в *.cloud.microsoft
домен. Как можно скорее выполните следующие действия, чтобы обеспечить отрисовку приложения на поддерживаемых узлах веб-клиента Microsoft 365:
Обновите библиотеку TeamsJS до версии 2.19.0 или более поздней. Чтобы избежать появления предупреждения в новом домене, необходимо вызвать вызов
microsoftTeams.app.initialize()
. Дополнительные сведения о последнем выпуске TeamsJS см. в статье Клиентская библиотека JavaScript для Microsoft Teams.Если вы определили заголовки политики безопасности содержимого (CSP) для приложения, обновите директиву frame-ancestors , чтобы включить
*.cloud.microsoft
домен. Чтобы обеспечить обратную совместимость во время миграции, сохраните существующиеframe-ancestors
значения в заголовках CSP. Такой подход гарантирует, что ваше приложение будет продолжать работать как в существующих, так и в будущих ведущих приложениях Microsoft 365 и свести к минимуму потребность в последующих изменениях.
Обновите следующий домен в директиве frame-ancestors
заголовков CSP приложения:
https://*.cloud.microsoft
Ниже приведены инструкции по вызову диалогового окна (называемого модулем задач в TeamsJS версии 1.x) с помощью task/fetch
:
На этом рисунке показан герой Bot Framework карта с действиемКупить
invoke
карта. Значение свойстваtype
являетсяtask/fetch
и остальная часть объектаvalue
может быть на ваш выбор.Бот получает сообщение
invoke
HTTP POST.Бот создает объект отклика и возвращает его в тексте отклика POST с кодом отклика HTTP 200. Дополнительные сведения о схеме ответов см. в обсуждении задачи или отправки. Следующий код представляет собой пример текста отклика HTTP, который содержит объект TaskInfo, встроенный в объект-оболочку:
{ "task": { "type": "continue", "value": { "title": "Task module title", "height": 500, "width": "medium", "url": "https://contoso.com/msteams/taskmodules/newcustomer", "fallbackUrl": "https://contoso.com/msteams/taskmodules/newcustomer" } } }
Событие
task/fetch
и его ответ для ботов похожи на функцию в клиентскойmicrosoftTeams.tasks.startTask()
библиотеке JavaScript Microsoft Teams (TeamsJS).Microsoft Teams отображает диалоговое окно.
В следующем разделе содержатся сведения об отправке результата диалогового окна.
Отправка результата диалогового окна
Когда пользователь завершает работу с диалоговым окном, отправка результата боту аналогично тому, как он работает с вкладками. Дополнительные сведения см. в разделе Пример отправки результата диалогового окна. Есть несколько отличий:
- HTML или JavaScript.
TaskInfo.url
После проверки введенных пользователем данных вызовите функциюmicrosoftTeams.tasks.submitTask()
, указанную ниже, какsubmitTask()
в целях удобочитаемости. Вы можете вызвать вызовsubmitTask()
без каких-либо параметров, если вы хотите, чтобы Teams закрыла диалоговое окно (в TeamsJS версии 1.x называется модулем задач), но необходимо передать объект или строку в .submitHandler
Передайте его как первый параметр,result
. Teams вызываетsubmitHandler
,err
являетсяnull
, иresult
— это объект или строка, переданные вsubmitTask()
. Если вызватьsubmitTask()
с параметромresult
, необходимо передатьappId
или массив строкappId
. Это действие позволяет Teams проверить, что приложение, отправляющее результат, совпадает с тем, что вызывает диалоговое окно. Бот получает сообщениеtask/submit
, включаяresult
. Подробнее см. полезные данныеtask/fetch
иtask/submit
сообщения. - Адаптивная карточка
TaskInfo.card
: текст адаптивной карточки, заполненный пользователем, отправляется боту черезtask/submit
сообщение при нажатии пользователем любой кнопкиAction.Submit
.
В следующем разделе содержатся сведения о том, как реагировать task/submit
на сообщения.
Отвечает task/submit
на сообщения
Когда пользователь завершает работу с диалоговым окном (который называется модулем задач в TeamsJS версии 1.x), вызванным из бота, бот всегда получает task/submit invoke
сообщение. У вас есть следующие варианты ответа на task/submit
:
Ответ в тексте HTTP | Сценарий |
---|---|
Нет игнорирует сообщение task/submit |
Самый простой отклик — это отсутствие отклика. Бот не обязан отвечать, когда пользователь завершит работу с диалоговым окном. |
{ |
Teams отображает значение value во всплывающем окне сообщения. |
{ |
Позволяет соединять последовательности адаптивных карточек в мастере или в многоэтапном действии. |
Примечание.
Объединение адаптивных карточек в последовательность — это расширенный сценарий. Образец приложения Node.js поддерживает его. Дополнительные сведения см. в разделе Диалоговое окно Microsoft Teams Node.js.
Следующий раздел содержит подробные сведения о полезных данных сообщений task/fetch
и task/submit
.
Полезные данные task/fetch
и task/submit
сообщения
В этом разделе определяется схема того, что ваш бот получает при получении объекта task/fetch
или task/submit
Bot Framework Activity
. В следующей таблице представлены свойства полезных данных task/fetch
и сообщений task/submit
:
Свойство | Описание |
---|---|
type |
Всегда invoke . |
name |
Возможные значения: task/fetch или task/submit . |
value |
Являются полезными данными определяемыми разработчиком. Структура объекта value такая же, как и отправляемая из Teams.. Однако в этом случае все по-другому. Для этого требуется поддержка динамической выборки, которая исходит как task/fetch от bot Framework, то естьvalue , так и от действий Adaptive CardAction.Submit , то есть data . Требуется способ связи Teams context с ботом в дополнение к тому, что включен в value или data .Объединение ''значений'' и ''данных'' в родительский объект: { |
В следующем разделе приведен пример получения и ответа на сообщения вызова task/fetch
и task/submit
в Node.js.
Следующие вкладки предоставляют task/fetch
и task/submit
вызывают сообщения в .NET, Node.js и Python:
protected override Task<TaskModuleResponse> OnTeamsTaskModuleFetchAsync(ITurnContext<IInvokeActivity> turnContext, TaskModuleRequest taskModuleRequest, CancellationToken cancellationToken)
{
var asJobject = JObject.FromObject(taskModuleRequest.Data);
var value = asJobject.ToObject<CardTaskFetchValue<string>>()?.Data;
var taskInfo = new TaskModuleTaskInfo();
switch (value)
{
case TaskModuleIds.YouTube:
taskInfo.Url = taskInfo.FallbackUrl = _baseUrl + "/" + TaskModuleIds.YouTube;
SetTaskInfo(taskInfo, TaskModuleUIConstants.YouTube);
break;
case TaskModuleIds.CustomForm:
taskInfo.Url = taskInfo.FallbackUrl = _baseUrl + "/" + TaskModuleIds.CustomForm;
SetTaskInfo(taskInfo, TaskModuleUIConstants.CustomForm);
break;
case TaskModuleIds.AdaptiveCard:
taskInfo.Card = CreateAdaptiveCardAttachment();
SetTaskInfo(taskInfo, TaskModuleUIConstants.AdaptiveCard);
break;
default:
break;
}
return Task.FromResult(taskInfo.ToTaskModuleResponse());
}
protected override async Task<TaskModuleResponse> OnTeamsTaskModuleSubmitAsync(ITurnContext<IInvokeActivity> turnContext, TaskModuleRequest taskModuleRequest, CancellationToken cancellationToken)
{
var reply = MessageFactory.Text("OnTeamsTaskModuleSubmitAsync Value: " + JsonConvert.SerializeObject(taskModuleRequest));
await turnContext.SendActivityAsync(reply, cancellationToken);
return TaskModuleResponseFactory.CreateResponse("Thanks!");
}
private static void SetTaskInfo(TaskModuleTaskInfo taskInfo, UISettings uIConstants)
{
taskInfo.Height = uIConstants.Height;
taskInfo.Width = uIConstants.Width;
taskInfo.Title = uIConstants.Title.ToString();
}
Действия карточки Bot Framework и действие адаптивной карточки Action.Submit
Схема действий Bot Framework карта отличается от действий адаптивной карточкиAction.Submit
, и способ вызова диалогов также отличается. Объект data
в Action.Submit
содержит объект , msteams
чтобы он не влиял на другие свойства в карта. В следующей таблице показан пример каждого действия карточки:
Действие карточки Bot Framework | Действие адаптивной карточки Submit action |
---|---|
{ |
{ |
Пример кода
Название примера | Описание | .NET | Node.js | Манифест |
---|---|---|---|---|
Примеры диалоговых ботов версии 4 | В этом примере приложения показано, как использовать диалоги (называемые модулями задач в TeamsJS версии 1.x) с помощью Bot Framework версии 4. | Просмотр | Просмотр | Просмотр |
См. также
Platform Docs