Интерфейс настройки бота

Статья
04/13/2024

Интерфейс настройки бота позволяет пользователям настраивать и перенастраивать параметры ботов непосредственно в канале или групповом чате после установки, повышая эффективность работы с самого начала. Эта функция устраняет необходимость в многократном вмешательстве пользователей, которые ранее препятствовали своевременной реализации преимуществ от приложений. Теперь пользователи могут адаптировать бота к конкретным рабочим процессам и предпочтениям во время установки и перенастройки параметров по мере необходимости, чтобы адаптироваться к изменяющимся требованиям, обеспечивая актуальность и ценность бота.

Например, рассмотрим бота, который отслеживает темы новостей и предоставляет общий доступ к ней или отслеживает репозитории GitHub. Изначально настроенные для согласования с рабочими процессами пользователей, эти боты могут быть легко перенастроены для реагирования на новые темы или репозитории непосредственно из группового чата, упрощая управление содержимым и взаимодействие, не выходя из среды Teams. Такая гибкая конфигурация значительно улучшает взаимодействие с пользователем и повышает производительность за счет простой интеграции ботов в повседневные операции.

Ниже приведен пример, когда пользователь добавляет бота в групповой чат, а затем настраивает его в соответствии с конкретными требованиями. Затем пользователь перенастраивает бота, чтобы изменить состояние.

Настройка

На рисунке показан процесс настройки бота в канале Teams.

Перенастроить

Снимок экрана: параметр конфигурации для бота в области создания сообщений.

Создание конфигурации бота

Примечание.

Настройка бота поддерживается только в канале или групповом чате.

При создании интерфейса настройки бота необходимо убедиться, что пользователь должен иметь возможность настроить бот при первой установке и перенастроить его в любое время.

Чтобы создать интерфейс настройки бота, выполните следующие действия.

Обновление манифеста приложения
Настройка бота

Обновление манифеста приложения

В файле манифеста приложения (ранее называемого манифестом приложения Teams) обновите fetchTask свойство в объекте bots.configuration следующим образом:

"bots": [
    {
      "botId": "${{AAD_APP_CLIENT_ID}}",
     "needsChannelSelector": false,
      "scopes": [
        "personal",
        "team",
        "groupChat"
      ],
      "configuration":{
        "groupChat":{
          "fetchTask": true
        },
        "team":{
          "fetchTask": true
        }
      },
      "isNotificationOnly": false
    }
  ],

Дополнительные сведения см. в разделе Схема манифеста приложения.

Настройка бота

Когда пользователь устанавливает бот в канале или групповом чате fetchTask , свойство в файле манифеста приложения инициирует или config/fetchconfig/submit , как определено в teamsBot.js файле.

Если для свойства в манифесте приложения задано fetchTask значение:

false: бот не получает диалоговое окно или адаптивную карточку. Вместо этого бот должен предоставить статический диалог или карта, который используется при вызове бота. Дополнительные сведения см. в разделе Диалоговые окна.
True: бот инициирует или config/fetchconfig/submit , как определено. При вызове бота можно вернуть адаптивную карточку или диалоговое окно в зависимости от контекста, предоставленного в channelData и userdata.

В следующей таблице приведен тип ответа, связанный с запросами вызова:

Вызов запроса	Тип ответа
`config/fetch`	`Type: "continue"` или `Type = "auth"`
`config/submit`	`Type: "continue"` или `Type: "message"`

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

— adaptiveCardForContinue это пользовательская функция, которая возвращает JSON для адаптивной карточки, которая будет использоваться на разных этапах рабочего процесса бота. Эти функции используются для возврата адаптивных карточек для различных сценариев на основе взаимодействия пользователя с ботом.

Когда пользователь отправляет конфигурацию, config/submit активируется вызов. Он считывает входные данные пользователя и возвращает другую адаптивную карточку. Вы также можете обновить конфигурацию бота, чтобы вернуть диалоговое окно.
- C#
- JavaScript
Пример справочника по коду
```
protected override Task<ConfigResponseBase>OnTeamsConfigFetchAsync(ITurnContext<IInvokeActivity> turnContext, JObject configData, CancellationToken cancellationToken)
{
    ConfigResponseBase response = adaptiveCardForContinue();
    return Task.FromResult(response);
}
```
Пример справочника по коду
```
async handleTeamsConfigFetch(_context, _configData) {
    let response = {};
    const adaptiveCard = CardFactory.adaptiveCard(this.adaptiveCardForContinue());
    response = {
       config: {
          value: {
             card: adaptiveCard,
             height: 500,
             width: 600,
             title: 'test card',
          },
          type: 'continue',
       },
    };
    return response;
}
```

type: "auth": вы также можете запросить проверку подлинности пользователя в качестве ответа на config/fetch запрос. Конфигурация type: "auth" предлагает пользователю войти по указанному URL-адресу, который должен быть связан с допустимой страницей проверки подлинности, которую можно открыть в браузере. Проверка подлинности необходима для сценариев, в которых бот требует проверки подлинности пользователя. Это гарантирует, что удостоверение пользователя проверяется, поддерживается безопасность и персонализированное взаимодействие в функциональных возможностях бота.

Примечание.

Поддерживается type: "auth" только проверка подлинности сторонних производителей. Единый вход (SSO) не поддерживается. Дополнительные сведения о сторонней проверке подлинности см. в статье Добавление проверки подлинности.
- C#
- JavaScript
Пример справочника по коду
```
protected override Task<ConfigResponseBase>OnTeamsConfigFetchAsync(ITurnContext<IInvokeActivity> turnContext, JObject configData, CancellationToken cancellationToken)
{
    ConfigResponseBase response = new ConfigResponse<BotConfigAuth> {
       Config = new BotConfigAuth {
          SuggestedActions = new SuggestedActions {
             Actions = new List<CardAction> {
                new CardAction {
                   type: "openUrl",
                   value: "https://example.com/auth",
                   title: "Sign in to this app"
                }
             }
          },
       Type = "auth"
    }
};
```
Пример справочника по коду
```
async handleTeamsConfigFetch(_context, _configData) {
    let response = {};
    response = {
       config: {
          type: "auth",
          suggestedActions: {
             actions: [{
                type: "openUrl",
                value: "https://example.com/auth",
                title: "Sign in to this app"
             }]
          },
      },
    };
    return response;
}
```

type="message": если для типа задано значение message, это означает, что бот отправляет пользователю простое сообщение, указывая на окончание взаимодействия или предоставляя сведения без дополнительных входных данных.

C#
JavaScript

Пример справочника по коду

protected override Task<ConfigResponseBase> OnTeamsConfigSubmitAsync(ITurnContext<IInvokeActivity> turnContext, JObject configData, CancellationToken cancellationToken)
{
    ConfigResponseBase response = new ConfigResponse<TaskModuleResponseBase>
    {
       Config = new TaskModuleMessageResponse
       {
          Type = "message",
          Value = "You have chosen to finish setting up bot"
       }
    };
    return Task.FromResult(response);
}

Пример справочника по коду

async handleTeamsConfigSubmit(context, _configData) {
    let response = {};
    response = {
       config: {
          type: 'message',
          value: 'You have chosen to finish setting up bot',
       },
    }
    return response;
}

Когда пользователь перенастраивает бот, fetchTask свойство в файле манифеста приложения инициируется config/fetch в логике бота. Пользователь может перенастроить параметры бота после установки двумя способами:

@mention бот в области создания сообщения. Выберите параметр Параметры , который отображается над областью создания сообщения. Появится диалоговое окно, изменится или изменится параметры конфигурации бота в диалоговом окне.
Наведите указатель мыши на бота, появится профиль бота, карта. Чтобы обновить или изменить параметры конфигурации бота, щелкните значок параметров в профиле бота карта.

Лучшие методики

Если вы хотите иметь отдельную конфигурацию на уровне канала бота, убедитесь, что вы отслеживаете конфигурацию согласно каналу. Данные конфигурации не хранятся, а полезные данные вызова включают достаточный объем channelData.
Предоставьте понятное и понятное диалоговое окно с предложением ввести необходимые сведения для правильной работы бота, например URL-адрес, путь к области или ссылку на панель мониторинга.
Избегайте отправки нескольких уведомлений или запросов на настройку после установки, так как это может сбить с толку пользователей.

Пример кода

Название примера	Описание	.NET	Node.js	Манифест
Приложение для настройки бота	В этом примере кода описывается конфигурация и перенастройка для ботов в командном и групповом чате с типами `continue` ответов и `message` .	Просмотр	Просмотр	Просмотр
Приложение для настройки бота с проверкой подлинности	В этом примере кода описывается конфигурация и перенастройка для ботов в командном и групповом чате с типами `auth` ответов и `message` .	Просмотр	Просмотр	View

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

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