Использование модулей задач из ботов

Модули задач можно вызывать из ботов Microsoft Teams с помощью кнопок на адаптивных карточках и карточках Bot Framework, которые являются имиджевыми, эскизами и Office 365 Connector. Модули задач часто обеспечивают лучший пользовательский интерфейс, чем несколько шагов диалога. Отслеживайте состояние бота и разрешайте пользователю прерывать или отменять последовательность.

Существует два способа вызова модулей задач:

  • Новое сообщение об вызове: invoke использование действия карточки для карт Bot Framework task/fetch``Action.Submit или действия карточки для адаптивных карточек с URL-адресом или адаптивной карточкой из модуля задач извлекается динамически из бота.task/fetch
  • URL-адреса глубинных ссылок: используя синтаксис глубоких ссылок для модулей задач, вы можете использовать openUrl действие карточкидля карточек Bot Framework илиAction.OpenUrl действие карточки для адаптивных карточек соответственно. При использовании URL-адресов глубинных ссылок URL-адрес модуля задачи или текст адаптивной карточки уже известны, чтобы избежать кругового пути сервера относительно task/fetch.

Важно!

Каждый url и fallbackUrl должен реализовать протокол шифрования HTTPS.

В следующем разделе приведены сведения о вызове модуля задач с помощью task/fetch.

Вызвать модуль задач с помощью task/fetch

Когда value объект действия карточки invoke или Action.Submit инициализируется и когда пользователь выбирает кнопку, боту отправляется сообщение invoke. В http-ответе invoke на сообщение есть объект TaskInfo, внедренный в объект-оболочку, который Teams для отображения модуля задачи.

запрос или ответ task/fetch

Следующие шаги предоставляют модуль задачи вызова с помощью задачи или выборки:

  1. На этом изображении показана карточка главного имиджевого баннера Bot Framework с действием Купить invoke карточку. Значение свойства type является task/fetch и остальная часть объекта value может быть на ваш выбор.

  2. Бот получает сообщение invoke HTTP POST.

  3. Бот создает объект отклика и возвращает его в тексте отклика POST с кодом отклика HTTP 200. Подробнее о схеме для откликов в Обсуждении task/submit. Следующий код представляет собой пример текста отклика 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() в клиентском SDK.

  4. Microsoft Teams отображает модуль задач.

В следующем разделе приведены сведения об отправке результатов модуля задачи.

Отправить результат модуля задачи

Когда пользователь завершает работу с модулем задачи, отправка результата обратно боту аналогична отправке с вкладками. Подробнее в примере отправки результата модуля задачи. Есть несколько отличий:

  • HTML или JavaScriptTaskInfo.url: после проверки введенных пользователем данных вы вызываете функцию пакета SDKsubmitTask(), microsoftTeams.tasks.submitTask() которую далее называют функцией для удобочитаемости. Вы можете вызвать submitTask() без параметров, если хотите, чтобы Teams закрыла модуль задачи, но вы должны передать объект или строку в ваш 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

Когда пользователь завершает работу с модулем задачи, вызванным из бота, бот всегда получает сообщение task/submit invoke. У вас есть следующие варианты ответа на task/submit:

Ответ в тексте HTTP Сценарий
Нет игнорирует сообщение task/submit Самый простой отклик — это отсутствие отклика. Бот не должен отвечать, когда пользователь завершает работу с модулем задачи.
{
"task": {
"type": "message",
"value": "Message text"
}
}
Teams отображает значение value во всплывающем окне сообщения.
{
"task": {
"type": "continue",
"value": <TaskInfo object>
}
}
Позволяет соединять последовательности адаптивных карточек в мастере или в многоэтапном действии.

Примечание

Объединение адаптивных карточек в последовательность — это расширенный сценарий. Образец приложения Node.js поддерживает его. Подробнее в разделе Модуль задач Microsoft Teams Node.js.

Следующий раздел содержит подробные сведения о полезных данных сообщений task/fetch и task/submit.

Полезные данные task/fetch и сообщения task/fetch

В этом разделе определяется схема того, что ваш бот получает при получении объекта 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.

Объединение ''значений'' и ''данных'' в родительский объект:

{
"context": {
"theme": "default" | "dark" | "contrast",
},
"data": [value field from Bot Framework card] | [data field from Adaptive Card]
}

В следующем разделе приведен пример получения и ответа на сообщения вызова task/fetch и task/submit в Node.js.

Пример сообщений вызова task/fetch и task/submit в Node.js и C#

handleTeamsTaskModuleFetch(context, taskModuleRequest) {
    // Called when the user selects an options from the displayed HeroCard or
    // AdaptiveCard.  The result is the action to perform.

    const cardTaskFetchValue = taskModuleRequest.data.data;
    var taskInfo = {}; // TaskModuleTaskInfo

    if (cardTaskFetchValue === TaskModuleIds.YouTube) {
        // Display the YouTube.html page
        taskInfo.url = taskInfo.fallbackUrl = this.baseUrl + '/' + TaskModuleIds.YouTube + '.html';
        this.setTaskInfo(taskInfo, TaskModuleUIConstants.YouTube);
    } else if (cardTaskFetchValue === TaskModuleIds.CustomForm) {
        // Display the CustomForm.html page, and post the form data back via
        // handleTeamsTaskModuleSubmit.
        taskInfo.url = taskInfo.fallbackUrl = this.baseUrl + '/' + TaskModuleIds.CustomForm + '.html';
        this.setTaskInfo(taskInfo, TaskModuleUIConstants.CustomForm);
    } else if (cardTaskFetchValue === TaskModuleIds.AdaptiveCard) {
        // Display an AdaptiveCard to prompt user for text, and post it back via
        // handleTeamsTaskModuleSubmit.
        taskInfo.card = this.createAdaptiveCardAttachment();
        this.setTaskInfo(taskInfo, TaskModuleUIConstants.AdaptiveCard);
    }

    return TaskModuleResponseFactory.toTaskModuleResponse(taskInfo);
}

async handleTeamsTaskModuleSubmit(context, taskModuleRequest) {
    // Called when data is being returned from the selected option (see `handleTeamsTaskModuleFetch').

    // Echo the users input back.  In a production bot, this is where you'd add behavior in
    // response to the input.
    await context.sendActivity(MessageFactory.text('handleTeamsTaskModuleSubmit: ' + JSON.stringify(taskModuleRequest.data)));

    // Return TaskModuleResponse
    return {
        // TaskModuleMessageResponse
        task: {
            type: 'message',
            value: 'Thanks!'
        }
    };
}

setTaskInfo(taskInfo, uiSettings) {
    taskInfo.height = uiSettings.height;
    taskInfo.width = uiSettings.width;
    taskInfo.title = uiSettings.title;
}

Действия карточки Bot Framework и действие адаптивной карточки Action.Submit

Схема действий карточки Bot Framework отличается от действий адаптивной карточки Action.Submit и способ вызова модулей задач также отличается. В data объекте Action.Submit содержится объект msteams , поэтому он не мешает другим свойствам в карточке. В следующей таблице показан пример каждого действия карточки:

Действие карточки Bot Framework Действие адаптивной карточки Submit action
{
"type": "invoke",
"title": "Buy",
"value": {
"type": "task/fetch",
<...>
}
}
{
"type": "Action.Submit",
"id": "btnBuy",
"title": "Buy",
"data": {
<...>,
"msteams": {
"type": "task/fetch"
}
}
}

Пример кода

Название примера Описание .NET Node.js
Примеры ботов модуля задач-V4 Примеры для создания модулей задач. Просмотр View

Пошаговые инструкции

Следуйте пошаговым инструкциям, чтобы создать и получить бот модуля задач в Teams

Дополнительные ресурсы