Определение команд действий расширения обмена сообщениями

Важно!

Примеры кода в этом разделе основаны на 4.6 и более поздних версиях SDK Bot Framework. Если вы ищете документацию для более ранних версий, см. раздел Расширения обмена сообщениями — раздел v3 SDK в папке Ресурсы документации.

Команды действий позволяют представить пользователям модальный всплывающий модуль, называемый модулем задач в Teams. Модуль задач собирает или отображает сведения, обрабатывает взаимодействие и отправляет их в Teams. В этом документе приводятся инструкции по выбору расположения команд действий, созданию модуля задач, отправке окончательного сообщения или карточки, созданию команды действий с помощью студии приложения или созданию его вручную.

Перед созданием команды действий необходимо определиться со следующими факторами:

  1. Откуда можно запускать команду действий?
  2. Как будет создан модуль задач?
  3. Будет ли отправлено окончательное сообщение или карточка в канал от бота, или сообщение или карточка будут вставлены в область композитного сообщения для отправки пользователем?

Выберите расположения команд действий, вызываемой

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

  • Область составить сообщение. Кнопки в нижней части области составить сообщение.

    Контекст команды = составить

  • Командный окне. @mentioning приложение в командном окне.

    Контекст команд = commandBox

    Примечание

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

  • Сообщение. Непосредственно из существующего сообщения через меню ... переполнения сообщения.

    Контекст команд = сообщение

    Примечание

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

На следующем изображении отображаются расположения, из которых вызывается команда действий:

Команда действий вызывает расположения

Выберите, как создать модуль задач

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

  • Статический список параметров. Это самый простой метод. Вы можете определить список параметров в манифесте приложения, Teams отрисовки клиента, но не можете управлять форматированием в этом случае.
  • Адаптивная карта. Можно выбрать адаптивную карту, которая обеспечивает более полный контроль над пользовательским интерфейсом, но по-прежнему ограничивает доступные параметры управления и форматирования.
  • Встроенное представление веб-сайта. Вы можете встраить настраиваемый веб-просмотр в модуль задач, чтобы иметь полный контроль над пользовательским интерфейсом и средствами управления.

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

Выберите, как отправляется окончательное сообщение

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

Если расширение обмена сообщениями вызывается из окна составить или непосредственно из сообщения, веб-служба может вставить окончательный ответ непосредственно в канал или чат. В этом случае адаптивная карта поступает от бота, бот обновляет ее и при необходимости отвечает на поток беседы. Необходимо добавить объект в манифест приложения с помощью того же bot ID и определить соответствующие области.

Добавление команды действий в манифест приложения

Чтобы добавить команду действий в манифест приложения, необходимо добавить новый объект на верхний уровень composeExtension манифеста приложения JSON. Для этого можно использовать один из следующих способов:

Создание команды действий с помощью App Studio

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

Примечание

App Studio скоро будет обесценив. Настройка, распространение и управление Teams приложениями с помощью нового портала разработчиков.

Примечание

Обязательным условием для создания команды действий является то, что вы уже создали расширение обмена сообщениями. Сведения о создании расширения обмена сообщениями см. в сообщении о создании расширения обмена сообщениями.

Создание команды действий

  1. Откройте App Studio Microsoft Teams клиента и выберите вкладку Редактор Манифеста.

  2. Если вы уже создали пакет приложений в App Studio, выберите его из списка. Если вы не создали пакет приложений, импортировать существующий пакет.

  3. После импорта пакета приложений выберите расширения обмена сообщениями в статье Capabilities. Вы получите всплывающее окно, чтобы настроить расширение обмена сообщениями.

  4. Выберите Настройка в окне, чтобы включить расширение обмена сообщениями в приложение. На следующем изображении отображается окно расширения обмена сообщениями:

    messaging extension set up
  5. Для создания расширения обмена сообщениями необходим зарегистрированный бот Майкрософт. Можно использовать существующий бот или создать новый бот. Выберите создание нового варианта бота, назови имя нового бота и выберите Create. На следующем изображении отображается создание бота для расширения обмена сообщениями:

    create bot for messaging extension
  6. Выберите Добавить в разделе Команда страницы расширения обмена сообщениями, чтобы включить команды, которые решают поведение расширения обмена сообщениями.
    На следующем изображении отображается добавление команд для расширения обмена сообщениями:

    include command
  7. Выберите Разрешить пользователям запускать действия во внешних службах во время Teams. На следующем изображении отображается выбор команд действий:

    action command selection
  8. Чтобы использовать статический набор параметров для создания модуля задач, выберите Определение набора статических параметров для команды.

    На следующем изображении отображается выбор статических параметров команды действий:

    action command static parameter selection

    На следующем изображении отображается пример статического параметра:

    action command static parameter set-up

    На следующем изображении отображается пример тестирования статических параметров:

    action command static parameter testing
  9. Чтобы использовать динамические параметры, выберите для получения динамического набора параметров из бота. На следующем изображении отображается выбор параметров команды действий:

    action command dynamic parameter selection
  10. Добавление командного и заголовок.

  11. Выберите расположение, в котором необходимо вызвать команду действий. На следующем изображении отображается расположение вызова команды действий:

    action command invoke location
  12. Нажмите Сохранить.

  13. Чтобы добавить дополнительные параметры, выберите кнопку Добавить в разделе Параметры.

Создание команды действий вручную

Чтобы вручную добавить команду расширения обмена сообщениями на основе действий в манифест приложения, необходимо добавить в массив объектов следующие composeExtension.commands параметры:

Имя свойства Назначение Обязательный? Минимальная версия манифеста
id Это свойство — уникальный ID, который вы назначаете этой команде. Запрос пользователя включает этот ID. Да 1.0
title Это свойство — командное имя. Это значение отображается в пользовательском интерфейсе. Да 1.0
type Это свойство должно быть action . Нет 1.4
fetchTask Это свойство предназначено для адаптивной карты или встроенного веб-представления для модуля задач, а также для статичного списка параметров или при загрузке true false веб-представления с помощью taskInfo . Нет 1.4
context Это свойство — необязательный массив значений, определяющий, откуда вызывается расширение обмена сообщениями. Возможные значения — message, compose и commandBox. Значение по умолчанию — ["compose", "commandBox"]. Нет 1.5

Если используется статический список параметров, необходимо также добавить следующие параметры:

Имя свойства Назначение Требуется? Минимальная версия манифеста
parameters Это свойство описывает статический список параметров для команды. Используйте только fetchTask false тогда, когда это . Нет 1.0
parameter.name Это свойство описывает имя параметра. Это отправляется в службу в запросе пользователя. Да 1.0
parameter.description Это свойство описывает цели параметра или пример значения, которое должно быть предоставлено. Это значение отображается в пользовательском интерфейсе. Да 1.0
parameter.title Это свойство — короткое удобное название параметра или метка. Да 1.0
parameter.inputType Это свойство задалось типу входных данных. Возможные значения включают text , , , , textarea number date time toggle . По умолчанию установлено text значение . Нет 1.4

Если вы используете встроенное веб-представление, можно дополнительно добавить объект для получения веб-представления без вызова taskInfo бота напрямую. При выборе этого параметра поведение аналогично использованию статического списка параметров. В том, что первое взаимодействие с ботом отвечает на действие отправки модуля задач. Если вы используете taskInfo объект, необходимо установить fetchTask параметр false .

Имя свойства Назначение Требуется? Минимальная версия манифеста
taskInfo Укажите модуль задач для предварительной загрузки при использовании команды расширения обмена сообщениями. Нет 1.4
taskInfo.title Начальное название модуля задач. Нет 1.4
taskInfo.width Ширина модуля задач, число пикселей или макет по умолчанию, например large medium , или small . Нет 1.4
taskInfo.height Высота модуля задач, число пикселей или макет по умолчанию, например large medium , или small . Нет 1.4
taskInfo.url Начальный URL-адрес веб-просмотра. Нет 1.4

Пример манифеста приложения

В следующем разделе приводится пример объекта, composeExtensions определяющий две команды действий. Это не пример полного манифеста. Полную схему манифеста приложения см. в схеме манифеста приложения:

...
"composeExtensions": [
  {
    "botId": "12a3c29f-1fc5-4d97-a142-12bb662b7b23",
    "canUpdateConfiguration": true,
    "commands": [
      {
        "id": "addTodo",
        "description": "Create a To Do item",
        "title": "Create To Do",
        "type": "action",
        "context": ["commandBox", "message", "compose"],
        "fetchTask": true,
        "parameters": [
          {
            "name": "Name",
            "description": "To Do Title",
            "title": "Title",
            "inputType": "text"
          },
          {
            "name": "Description",
            "description": "Description of the task",
            "title": "Description",
            "inputType": "textarea"
          },
          {
            "name": "Date",
            "description": "Due date for the task",
            "title": "Date",
            "inputType": "date"
          }
        ]
      },
      {
        "id": "reassignTodo",
        "description": "Reassign a todo item",
        "title": "Reassign a todo item",
        "type": "action",
        "fetchTask": true,
      }
    ]
  }
]
...

Пример кода

Имя образца Описание .NET Node.js
Teams расширения обмена сообщениями Описывает, как определить команды действий, создать модуль задач и реагировать на отправку действия модуля задач. View View
Teams расширения обмена сообщениями Описывает, как определить команды поиска и реагировать на поиски. View View

Следующее действие

Если вы используете адаптивную карту или встроенное веб-представление без объекта, следующий шаг: taskInfo

Если вы используете параметры или встроенное веб-представление с taskInfo объектом, следующим шагом будет следующее: