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

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

  • Статья

Вызов диалоговых окон (называемых модулями задач в 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 домен. Выполните следующие действия до сентября 2024 г., чтобы приложение продолжало отрисовывать на поддерживаемых узлах веб-клиента Microsoft 365:

  1. Обновите библиотеку TeamsJS до версии 2.19.0 или более поздней. Дополнительные сведения о последнем выпуске TeamsJS см. в статье Клиентская библиотека JavaScript для Microsoft Teams.

  2. Если вы определили заголовки политики безопасности содержимого (CSP) для приложения, обновите директиву frame-ancestors , чтобы включить *.cloud.microsoft домен. Чтобы обеспечить обратную совместимость во время миграции, сохраните существующие frame-ancestors значения в заголовках CSP. Такой подход гарантирует, что ваше приложение будет продолжать работать как в существующих, так и в будущих ведущих приложениях Microsoft 365 и свести к минимуму потребность в последующих изменениях.

Обновите следующий домен в директиве frame-ancestors заголовков CSP приложения:

https://*.cloud.microsoft

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

Ниже приведены инструкции по вызову диалогового окна (называемого модулем задач в TeamsJS версии 1.x) с помощью task/fetch:

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

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

  3. Бот создает объект отклика и возвращает его в тексте отклика 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).

  4. 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 Самый простой отклик — это отсутствие отклика. Бот не обязан отвечать, когда пользователь завершит работу с диалоговым окном. 
{
  "task": {
    "type": "message",
    "value": "текст сообщения"
  }
}
 Teams отображает значение value во всплывающем окне сообщения. 
{
  "task": {
    "type": "continue",
    "value": <объект TaskInfo>
  }
}
 Позволяет соединять последовательности адаптивных карточек в мастере или в многоэтапном действии.

Примечание.

Объединение адаптивных карточек в последовательность — это расширенный сценарий. Образец приложения 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.

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

{
  "context": {
    "theme": "default" | "dark" | "контраст",
  },
  "data": [поле значения из карточки Bot Framework] | [поле данных из адаптивной карточки]
}

В следующем разделе приведен пример получения и ответа на сообщения вызова 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": "Купить",
  "value": {
    "type": "task/fetch",
    
              <...>
  }
}
 
{
  "type": "Action.Submit",
  "id": "btnBuy",
  "title": "Купить",
  "data": {
    
              <...>,
    "msteams": {
      "type": "task/fetch"
    }
  }
}

Пример кода

Название примера Описание .NET Node.js Манифест
Примеры диалоговых ботов версии 4 В этом примере показано, как создавать диалоги с помощью Bot Framework версии 4 и вкладки Teams. Просмотр Просмотр View

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

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

См. также