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

Важно!

Примеры кода, приведенные в этом разделе, основаны на 4,6 и более поздних версиях пакета SDK Bot.The code samples in this section are based on 4.6 and later versions of the Bot Framework SDK. Если вы ищете документацию по более ранним версиям, ознакомьтесь с разделом Messaging Extensions – v3 SDK в папке resources этой документации.If you're looking for documentation for earlier versions, see the Messaging Extensions - v3 SDK section in the Resources folder of the documentation.

Команды действий позволяют предоставить пользователям модальное всплывающее окно (называемое модулем задач в Teams) для сбора и отображения информации, а затем обработки их взаимодействия и отправки информации обратно в Teams.Action commands allow you present your users with a modal popup (called a task module in Teams) to collect or display information, then process their interaction and send information back to Teams. Прежде чем приступать к созданию команды, необходимо принять решение:Before creating your command you'll need to decide:

  1. Откуда можно запустить команду действия?Where can the action command be triggered from?
  2. Как будет создаваться модуль задач?How will the task module be created?
  3. Будет ли Последнее сообщение или карточка отправляться каналу из ленты, или сообщение или карточка будут вставлены в область сообщений для отправки пользователю?Will the final message or card be sent to the channel from a bot, or will the message or card be inserted into the compose message area for the user to submit?

Выбор мест вызова команды действияChoose action command invoke locations

В первую очередь необходимо выбрать, где можно запустить команду действия (или более конкретную, вызватьее) из.The first thing you need to decide is where your action command can be triggered (or more specifically, invoked) from. Указав параметр context в манифесте приложения, вы можете вызвать команду из одного или нескольких из следующих расположений:By specifying the context in your app manifest, your command can be invoked from one or more of the following locations:

  • Кнопки в нижней части области "Создание сообщения".The buttons at the bottom of the compose message area.
  • @Mentioning ваше приложение в поле команда.By @mentioning your app in the command box. Note: невозможно ответить с сообщением Bot, вставленным непосредственно в беседу, если ваше расширение обмена сообщениями вызвано из командной поля.Note: You cannot respond with a bot message inserted directly into the conversation if your messaging extension is invoked from the command box.
  • Непосредственно из существующего сообщения с помощью... меню переполнения сообщения.Directly from an existing message via the ... overflow menu on a message. Note: начальный вызов почтового робота будет содержать объект JSON, содержащий сообщение, из которого оно было вызвано, которое можно обработать перед представлением в модуле задачи.Note: The initial invoke to your bot will include a JSON object containing the message from which it was invoked, which you can process before presenting them with a task module.

Выбор способа построения модуля задачChoose how to build your task module

В дополнение к выбору того, откуда может вызываться команда, необходимо также выбрать способ заполнения формы в модуле задач для пользователей.In addition to choosing where your command can be invoked from, you must also chose how to populate the form in the task module for your users. Существует три варианта создания формы, отображаемой в модуле задачи:You have three options for creating the form that is rendered inside the task module:

  • Статический список параметров — это самый простой вариант.Static list of parameters - This is the simplest option. Вы можете определить список параметров (полей ввода) в манифесте приложения, который будет отображаться клиентом Teams.You can define a list of parameters (input fields) in your app manifest the Teams client will render. Вы не можете управлять форматированием с помощью этого параметра.You cannot control the formatting with this option.
  • Адаптивная карта — вы можете выбрать использование адаптивной карточки, которая обеспечивает больший контроль над пользовательским интерфейсом, но по-прежнему ограничит доступ к доступным элементам управления и параметрам форматирования.Adaptive card - You can choose to use an adaptive card, which provides greater control over the UI, but still limits you on the available controls and formatting options.
  • Встроенное представление веб-сайта — если вам требуется полный контроль над пользовательским интерфейсом и элементами управления, можно выбрать внедрение настраиваемого веб-представления в модуль задачи.Embedded web view - If you need complete control over the UI and controls, you can choose to embed a custom web view in the task module.

Если вы решили создать модуль задач со статическим списком параметров, первый вызов расширения системы обмена сообщениями будет выполняться, когда пользователь отправит модуль задачи.If you choose to create your task module with a static list of parameters, the first call to your messaging extension will be when a user submits the task module. При использовании встроенного веб-представления или адаптивной карточки ваше расширение системы обмена сообщениями должно обрабатывать начальное событие Invoke от пользователя, создавать модуль задач и возвращать его обратно клиенту.When using an embedded web view or an adaptive card, your messaging extension will need to handle an initial invoke event from the user, create the task module, and return it back to the client.

Выбор способа отправки итогового сообщенияChoose how the final message will be sent

В большинстве случаев команда действия приведет к вставке карточки в окно сообщения создать.In most cases, your action command will result in a card inserted into the compose message box. Пользователь может принять решение отправить его в канал или чат.Your user can then decide to send it into the channel or chat. Сообщение в этом случае поступает от пользователя, и у вас не будет возможность изменить открытку или изменить ее.The message in this case comes from the user, and your bot will not be able to edit or update the card further.

Если расширение системы обмена сообщениями запускается из поля создать или напрямую из сообщения, веб-служба может вставить конечный ответ непосредственно в канал или чат.If your messaging extension is triggered from the compose box or directly from a message, your web service can insert the final response directly into the channel or chat. В этом случае Адаптивная карта поступает от Bot, а Bot может обновляться, а Bot также может отвечать на поток бесед, если это необходимо.In this case, the adaptive card comes from the bot, the bot will be able to update it, and the bot can also reply to the conversation thread if needed. Вам потребуется добавить bot объект в манифест приложения с помощью того же идентификатора и определить соответствующие области.You will need to add the bot object to your app manifest using the same Id and defining the appropriate scopes.

Добавление команды в манифест приложенияAdd the command to your app manifest

Теперь, когда вы решили, как пользователи будут взаимодействовать с командой действия, необходимо добавить его в манифест приложения.Now that you've decided how users will interact with your action command, it is time to add it to your app manifest. Чтобы сделать это, добавьте новый composeExtension объект на верхний уровень манифеста приложения JSON.To do this you'll add a new composeExtension object to the top level of your app manifest JSON. Это можно сделать с помощью App Studio или вручную.You can either do so with the help of App Studio, or manually.

Создание команды с помощью App StudioCreate a command using App Studio

В следующих действиях предполагается, что вы уже создали расширение системы обмена сообщениями.The following steps assume you've already created a messaging extension.

  1. В клиенте Microsoft Teams откройте app Studio и выберите вкладку редактор манифестов .From the Microsoft Teams client, open App Studio and select the Manifest Editor tab.
  2. Если вы уже создали пакет приложения в App Studio, выберите его из списка.If you've already created your app package in App Studio, chose it from the list. В противном случае вы можете импортировать существующий пакет приложения.If not, you can import an existing app package.
  3. Нажмите кнопку Add (добавить ) в разделе Command (Добавить).Click the Add button in the Command section.
  4. Выберите Разрешить пользователям активировать действия во внешних службах в Teams.Choose Allow users to trigger actions in external services while inside of Teams.
  5. Если вы хотите использовать статический набор параметров для создания модуля задачи, выберите этот параметр.If you want to use a static set of parameters to create your task module, select that option. В противном случае выберите вариант для выборки динамического набора параметров из ленты.Otherwise, choose to Fetch a dynamic set of parameters from your bot.
  6. Добавьте идентификатор команды и название.Add a Command Id and a Title.
  7. Выберите место, с которого будет запускаться команда действия.Select where you want your action command to be triggered from.
  8. Если вы используете параметры для модуля задачи, добавьте первый из них.If you're using parameters for your task module, add the first one.
  9. Нажмите кнопку Save (Сохранить)Click Save
  10. Если требуется добавить дополнительные параметры, нажмите кнопку Добавить в разделе Параметры , чтобы добавить их.If you need to add more parameters, click the Add button in the Parameters section to add them.

Создание команды вручнуюManually create a command

Чтобы вручную добавить команду расширения обмена сообщениями на основе действий в манифест приложения, необходимо добавить к composeExtension.commands массиву объектов следующие параметры.To manually add your action-based messaging extension command to your app manifest, you'll need to add the follow parameters to your composeExtension.commands array of objects.

Имя свойстваProperty name НазначениеPurpose Обязательный?Required? Минимальная версия манифестаMinimum manifest version
id Уникальный идентификатор, назначенный этой команде.Unique ID that you assign to this command. Запрос пользователя будет включать этот идентификатор.The user request will include this ID. ДаYes 1.01.0
title Имя команды.Command name. Это значение отображается в пользовательском интерфейсе.This value appears in the UI. ДаYes 1.01.0
type Необходимое значение — action.Must be action НетNo 1.41.4
fetchTask true для адаптивной карточки или встроенного веб-представления для модуля задач, false для статического списка параметров или при загрузке веб-представления с помощью taskInfotrue for an adaptive card or embedded web view for your task module, false for a static list of parameters or when loading the web view by a taskInfo НетNo 1.41.4
context Необязательный массив значений, определяющий расположение, из которого может вызываться расширение обмена сообщениями.Optional array of values that defines where the messaging extension can be invoked from. Возможные значения: message , compose , или commandBox .Possible values are message, compose, or commandBox. Значение по умолчанию: ["compose", "commandBox"].Default is ["compose", "commandBox"]. НетNo 1.51.5

Если вы используете статический список параметров, вы также добавите их.If you are using a static list of parameters, you'll add them as well.

Имя свойстваProperty name НазначениеPurpose Обязательный?Required? Минимальная версия манифестаMinimum manifest version
parameters Статический список параметров для команды.Static list of parameters for the command. Используйте, только когда fetchTaskfalseOnly use when fetchTask is false НетNo 1.01.0
parameter.name Имя параметра.The name of the parameter. Он отправляется службе по запросу пользователя.This is sent to your service in the user request. ДаYes 1.01.0
parameter.description Описывает назначение этого параметра или пример значения, которое следует предоставить.Describes this parameter’s purposes or example of the value that should be provided. Это значение отображается в пользовательском интерфейсе.This value appears in the UI. ДаYes 1.01.0
parameter.title Краткий заголовком или меткой с понятным пользователем параметром.Short user-friendly parameter title or label. ДаYes 1.01.0
parameter.inputType Укажите требуемый тип ввода.Set to the type of input required. Возможные значения: text , textarea , number , date , time , toggle .Possible values include text, textarea, number, date, time, toggle. Значение по умолчанию: textDefault is set to text НетNo 1.41.4

При использовании внедренного веб-представления можно дополнительно добавить taskInfo объект для извлечения веб-представления, не обращаясь непосредственно к объекту Bot.If you are using an embedded web view, you can optionally add the taskInfo object to fetch your web view without calling your bot directly. Если выбран этот параметр, поведение аналогично статическому списку параметров в том, что первое взаимодействие с роботом будет отвечать на действия по отсылке модуля задач.If you choose to use this option, the behavior is similar to using a static list of parameters in that the first interaction with your bot will be responding to the task module submit action. Если вы используете taskInfo объект, обязательно задайте fetchTask для параметра значение false .If you are using a taskInfo object, be sure to also set the fetchTask parameter to false.

Имя свойстваProperty name НазначениеPurpose Обязательный?Required? Минимальная версия манифестаMinimum manifest version
taskInfo Указание модуля задач для предварительной загрузки при использовании команды расширения системы обмена сообщениямиSpecify the task module to preload when using a messaging extension command НетNo 1.41.4
taskInfo.title Заголовок исходного модуля задачInitial task module title НетNo 1.41.4
taskInfo.width Ширина модуля задачи — число в пикселях или макет по умолчанию, например "крупный", "средний" или "Малый"Task module width - either a number in pixels or default layout such as 'large', 'medium', or 'small' НетNo 1.41.4
taskInfo.height Высота модуля задачи — число в пикселях или макет по умолчанию, например "крупный", "средний" или "Малый"Task module height - either a number in pixels or default layout such as 'large', 'medium', or 'small' НетNo 1.41.4
taskInfo.url URL-адрес начального представления в ИнтернетеInitial web view URL НетNo 1.41.4

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

Ниже приведен пример composeExtensions объекта, определяющего две команды действия.The below is an example of a composeExtensions object defining two action commands. Это не пример полного манифеста для полной схемы манифеста приложения: схема манифеста приложения.It is not an example of the complete manifest, for the full app manifest schema see: App manifest schema.

...
"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": false,
        "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,
      }
    ]
  }
]
...

Дальнейшие действияNext steps

Если вы используете адаптивную карту или встроенное веб-представление без taskInfo объекта, вам нужно выполнить следующие действия:If you are using either an adaptive card or an embedded web view without a taskInfo object, you'll want to:

Если вы используете параметры или внедренное веб-представление с taskInfo объектом, выполните следующие действия:If you are using parameters or an embedded web view with a taskInfo object, the next step for you is to:

Дополнительные сведенияLearn more

Попробуйте это в кратком руководстве:Try it out in a quickstart: