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

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

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

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

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

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

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

• Командное поле: с помощью / в командном окне. Например, /your-app-name. Если вы используете классическую команду Teams, команда action вызывается в командном @mentioning окне. Например, @your-app-name.

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

  Примечание.

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

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

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

  Примечание.

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

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

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

Выбор способа создания диалогового окна

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

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

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

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

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

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

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

Вы можете создать команду действия с помощью microsoft 365 Agents Toolkit (ранее известного как Набор средств Teams) и портала разработчика для Teams.

Microsoft 365 Agents Toolkit

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

1. Откройте Visual Studio Code.
2. В левой области выберите Microsoft 365 Agents Toolkit(Набор средств агентов Microsoft 365).
3. Выберите Создать новый агент или приложение>Teams App.
4. Выберите Расширение сообщений.
5. Выберите Сбор из входных и обрабатываемых данных.
6. Выберите язык программирования.
7. Выберите Папка по умолчанию.
8. Введите имя приложения и нажмите клавишу ВВОД.

Набор средств агентов создает шаблон проекта и создает расширение сообщений о действиях.

Портал разработчика Teams

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

1. Перейдите на портал разработчика для Teams.

2. Перейдите в раздел Приложения.

3. Выберите Создать приложение.

4. В разделе Настройка выберите Функции приложений.

5. Выберите Расширение для обмена сообщениями.

   

6. В разделе Тип расширения сообщения выберите Бот.

   1. Если вы получаете заявление об отказе от ответственности, которое считывает расширение API Message, уже используется пользователями. Вы хотите изменить тип расширения сообщений на bot?. Выберите Да, изменить.

   

7. Если у вас нет бота, выберите Существующий бот или, если у вас есть идентификатор бота, выберите Ввести идентификатор бота.

   1. Если у вас нет идентификатора бота, выберите Создать бот, чтобы создать бот, и введите идентификатор созданного бота.

8. Выберите необходимые области.

9. В разделе Команда выберите + Добавить команду.

   Откроется страница сведений о команде.

10. На странице Сведения о команде выберите Действие , а затем выберите тип параметра.

11. Выберите Действие в качестве типа команды и обновите следующие поля:

    • Идентификатор команды
    • Заголовок команды
    • Описание команды
    • Контекст, в котором работает команда
    • Имя параметра
    • Заголовок параметра
    • Описание параметра
    • Тип описания параметра

12. Выберите Добавить домен в разделе Ссылки предварительного просмотра.

13. Введите допустимый домен и нажмите кнопку Добавить.

    

14. Выберите Сохранить.

    

Добавление дополнительных параметров

1. В команде щелкните значок с многоточием (...) и выберите Изменить параметр.

   

2. Выберите Добавить параметр и обновите сведения о параметре.

   

3. Нажмите кнопку Сохранить.

Создается расширение сообщений о действиях на основе бота.

Фрагменты кода

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

C#

• Справочные материалы для SDK
• Пример справочника по коду

protected override Task<MessagingExtensionActionResponse> OnTeamsMessagingExtensionFetchTaskAsync(ITurnContext<IInvokeActivity> turnContext, MessagingExtensionAction action, CancellationToken cancellationToken)
        {
            // Handle different actions using switch.
            switch (action.CommandId)
            {
                case "HTML":
                    return new MessagingExtensionActionResponse
                    {
                        Task = new TaskModuleContinueResponse
                        {
                            Value = new TaskModuleTaskInfo
                            {
                                Height = 200,
                                Width = 400,
                                Title = "Task Module HTML Page",
                                Url = baseUrl + "/htmlpage.html",
                            },
                        },
                    };
                default:
                    string memberName = "";
                    var member = await TeamsInfo.GetMemberAsync(turnContext, turnContext.Activity.From.Id, cancellationToken);
                    memberName = member.Name;
                    return new MessagingExtensionActionResponse
                    {
                        Task = new TaskModuleContinueResponse
                        {
                            Value = new TaskModuleTaskInfo
                            {
                                Card = <<AdaptiveAction card json>>,
                                Height = 200,
                                Width = 400,
                                Title = $"Welcome {memberName}",
                            },
                        },
                    };
            }
        }

Node.js

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

// Invoked when a Messaging Extension Fetch activity is received from the connector.
    async handleTeamsMessagingExtensionFetchTask(context, action) {
        switch (action.commandId) {
            case 'Static HTML':
                return staticHtmlPage();
        }
    }

    staticHtmlPage(){
        return {
            task: {
                type: 'continue',
                value: {
                    width: 450,
                    height: 125,
                    title: 'Dialog Static HTML',
                    url: `${baseurl}/StaticPage.html`
                }
            }
        };
    }

Пример кода

Название примера	Описание	.NET	Node.js	Манифест
Действие расширения для сообщений Teams	В этом примере показано, как создавать расширения сообщений на основе действий для Microsoft Teams, позволяя пользователям создавать содержимое в интерактивном режиме. Он предоставляет боты, расширения сообщений и удобную интеграцию с входными данными пользователя для повышения функциональности.	Просмотр	Просмотр	Просмотр
Предварительный просмотр действия расширения сообщений	В этом примере приложения показано, как использовать предварительные версии действий в расширениях сообщений Teams, позволяя пользователям создавать карточки на основе входных данных в диалоговом окне. В нем демонстрируются взаимодействия ботов, которые повышают вовлеченность пользователей, приписывая пользователям сообщения.	Просмотр	Просмотр	View

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

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

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

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

Диалоговое окно "Создание и отправка"

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

Ответ на действие отправки в диалоговом окне

См. также

• Портал разработчика Teams
• Расширения для сообщений