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


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

Вызов диалогов (называемых модулями задач в 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:

  1. Обновите библиотеку TeamsJS до версии 2.19.0 или более поздней. Чтобы избежать появления предупреждения в новом домене, необходимо вызвать вызов microsoftTeams.app.initialize() . Дополнительные сведения о последнем выпуске 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 вызывают сообщения в .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
{
"type": "invoke",
"title": "Купить",
"value": {
"type": "task/fetch",
<...>
}
}
{
"type": "Action.Submit",
"id": "btnBuy",
"title": "Купить",
"data": {
<...>,
"msteams": {
"type": "task/fetch"
}
}
}

Пример кода

Название примера Описание .NET Node.js Манифест
Примеры диалоговых ботов версии 4 В этом примере приложения показано, как использовать диалоги (называемые модулями задач в TeamsJS версии 1.x) с помощью Bot Framework версии 4. Просмотр Просмотр Просмотр

См. также