Запуск действий с расширениями обмена сообщениямиInitiate actions with messaging extensions

Важно!

Статьи, приведенные в этом разделе, основаны на пакете SDK "V3 Bot Framework".The articles in this section are based on the v3 Bot Framework SDK. Если вы ищете текущую документацию (версия 4,6 или более поздняя версия пакета SDK), ознакомьтесь со статьей " взаимодействия, ориентированные на задачи с расширениями обмена сообщениями ".If you're looking for current documentation (version 4.6 or later version of the SDK) see the Task-oriented interactions with Messaging Extensions section.

Расширения обмена сообщениями на основе действий позволяют пользователям активировать действия во внешних службах в Teams.Action-based messaging extensions allow your users to trigger actions in external services while inside of Teams.

Пример карточки расширения обмена сообщениями

В следующих разделах описано, как это сделать.The following sections describe how to do this.

Добавление расширения обмена сообщениями в приложениеAdd a messaging extension to your app

Расширение системы обмена сообщениями — это размещенная в облаке служба, которая прослушивает запросы пользователей и отвечает на структурированные данные, такие как карточка.A messaging extension is a cloud-hosted service that listens to user requests and responds with structured data, such as a card. Вы интегрируете службу с Microsoft Teams с помощью Activity объектов Bot Framework.You integrate your service with Microsoft Teams via Bot Framework Activity objects. Наши расширения .NET и Node. js для пакета SDK построителя построителя могут помочь добавить функциональность расширения обмена сообщениями в приложение.Our .NET and Node.js extensions for the Bot Builder SDK can help you add messaging extension functionality to your app.

Схема процесса обработки сообщений для расширений обмена сообщениями

Регистрация в Bot FrameworkRegister in the Bot Framework

Если вы еще не сделали этого, сначала необходимо зарегистрировать Bot с помощью Microsoft Bot Framework.If you haven’t done so already, you must first register a bot with the Microsoft Bot Framework. Идентификатор приложения Microsoft и конечные точки обратного вызова для ленты, как определено, будут использоваться в вашем расширении обмена сообщениями для получения запросов пользователей и реагирования на них.The Microsoft app ID and callback endpoints for your bot, as defined there, will be used in your messaging extension to receive and respond to user requests. Не забудьте включить канал Microsoft Teams для ленты.Remember to enable the Microsoft Teams channel for your bot.

Запишите идентификатор приложения Bot и пароль приложения, вам потребуется указать идентификатор приложения в манифесте приложения.Record your bot app ID and app password, you will need to supply the app ID in your app manifest.

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

Как и в случае с Боты и вкладками, Манифест приложения можно изменить, добавив в него свойства расширения Messaging.As with bots and tabs, you update the manifest of your app to include the messaging extension properties. Эти свойства определяют, как ваше расширение обмена сообщениями отображается и работает в клиенте Microsoft Teams.These properties govern how your messaging extension appears and behaves in the Microsoft Teams client. Расширения обмена сообщениями поддерживаются начиная с версии 1.0 манифеста.Messaging extensions are supported beginning with v1.0 of the manifest.

Объявление расширения обмена сообщениямиDeclare your messaging extension

Чтобы добавить расширение обмена сообщениями, включите новую структуру JSON верхнего уровня в манифест со composeExtensions свойством.To add a messaging extension, include a new top-level JSON structure in your manifest with the composeExtensions property. В настоящее время вы можете создать только один добавочный номер для обмена сообщениями для вашего приложения.Currently, you are limited to creating a single messaging extension for your app.

Примечание

Манифест содержит ссылки на расширения обмена сообщениями composeExtensions.The manifest refers to messaging extensions as composeExtensions. Это необходимо для обеспечения обратной совместимости.This is to maintain backward compatibility.

Определение расширения — это объект, имеющий следующую структуру:The extension definition is an object that has the following structure:

Имя свойстваProperty name НазначениеPurpose Обязательный?Required?
botId Уникальный идентификатор приложения для ленты, зарегистрированный с помощью Bot Framework.The unique Microsoft app ID for the bot as registered with the Bot Framework. Как правило, это должен быть тот же идентификатор, что и для всего приложения Teams.This should typically be the same as the ID for your overall Teams app. ДаYes
scopes Массив, объявляющий, можно ли добавлять это расширение personal в team области или в области (или и то, и другое).Array declaring whether this extension can be added to personal or team scopes (or both). ДаYes
canUpdateConfiguration Включает пункт меню параметров .Enables Settings menu item. НетNo
commands Массив команд, поддерживаемых этим расширением обмена сообщениями.Array of commands that this messaging extension supports. Можно выполнить не более 10 команд.You are limited to 10 commands. ДаYes

Определение командDefine commands

Ваш модуль обмена сообщениями должен объявить одну команду, которая появляется, когда пользователь выбирает приложение из кнопки Дополнительные параметры () в поле Создать.Your messaging extension should declare one command, which appears when the user selects your app from the More options () button in the compose box.

Снимок экрана: список расширений обмена сообщениями в Teams

В манифесте приложения командный элемент представляет собой объект со следующей структурой:In the app manifest, your command item is an object with the following structure:

Имя свойства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
description Текст справки, указывающий, что делает эта команда.Help text indicating what this command does. Это значение отображается в пользовательском интерфейсе.This value appears in the UI. ДаYes 1.01.0
type Задайте тип команды.Set the type of command. Возможные значения: query и action.Possible values include query and action. Если не указано, по умолчанию установлено значениеqueryIf not present the default value is set to query НетNo 1.41.4
initialRun Необязательный параметр, query используемый с командами.Optional parameter, used with query commands. Если задано значение true, то эта команда должна выполняться сразу после того, как пользователь выберет эту команду в пользовательском интерфейсе.If set to true, indicates this command should be executed as soon as the user chooses this command in the UI. НетNo 1.01.0
fetchTask Необязательный параметр, action используемый с командами.Optional parameter, used with action commands. Установите значение true для получения URL-адреса адаптивной карты или веб-сайта для отображения в модуле задачи.Set to true to fetch the adaptive card or web url to display within the task module. Используется, когда входные данные action команды динамически, а не статический набор параметров.This is used when the inputs to the action command is dynamic as opposed to a static set of parameters. Обратите внимание, что если задано значение true , то список статических параметров для команды игнорируетсяNote that the if set to true the static parameter list for the command is ignored НетNo 1.41.4
parameters Статический список параметров для команды.Static list of parameters for the command. ДаYes 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
context Необязательный массив значений, определяющий контекст, в котором доступно действие с сообщением.Optional array of values that defines the context the message action is available in. Возможные значения: message, compose, или commandBox.Possible values are message, compose, or commandBox. Значение по умолчанию: ["compose", "commandBox"].Default is ["compose", "commandBox"]. НетNo 1.51.5

Расширения сообщений для типов действийAction type message extensions

Чтобы инициировать действия из расширения обмена сообщениями, задайте type для параметра значение action .To initiate actions from a messaging extension set the type parameter to action. Ниже приведен пример манифеста с командой поиска и созданием.Below is an example of a manifest with a search and a create command. Одно расширение системы обмена сообщениями может содержать до 10 разных команд.A single messaging extension can have up to 10 different commands. Сюда могут входить как несколько команд поиска, так и несколько команд, основанных на действиях.This can include both multiple search and multiple action-based commands.

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

{
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.8/MicrosoftTeams.schema.json",
  "manifestVersion": "1.5",
  "version": "1.0",
  "id": "57a3c29f-1fc5-4d97-a142-35bb662b7b23",
  "packageName": "com.microsoft.teams.samples.Todo",
  "developer": {
    "name": "John Developer",
    "websiteUrl": "http://todobotservice.azurewebsites.net/",
    "privacyUrl": "http://todobotservice.azurewebsites.net/privacy",
    "termsOfUseUrl": "http://todobotservice.azurewebsites.net/termsofuse"
  },
  "name": {
    "short": "To Do",
    "full": "To Do"
  },
  "description": {
    "short": "Find or create a new task in To Do",
    "full": "Find or create a new task in To Do"
  },
  "icons": {
    "outline": "todo-outline.jpg",
    "color": "todo-color.jpg"
  },
  "accentColor": "#ff6a00",
  "composeExtensions": [
    {
      "botId": "57a3c29f-1fc5-4d97-a142-35bb662b7b23",
      "canUpdateConfiguration": true,
      "commands": [
        {
          "id": "searchCmd",
          "description": "Search you Todo's",
          "title": "Search",
          "initialRun": true,
          "context": ["commandBox", "compose"],
          "parameters": [
            {
              "name": "searchKeyword",
              "description": "Enter your search keywords",
              "title": "Keywords"
            }
          ]
        },
        {
          "id": "addTodo",
          "description": "Create a To Do item",
          "title": "Create To Do",
          "type": "action",
          "context": ["commandBox", "message", "compose"],
          "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,
          "parameters": [
            {
              "name": "Name",
              "title": "Title"
            }
          ]
        }
      ]
    }
  ],
  "permissions": [
    "identity",
    "messageTeamMembers"
  ],
  "validDomains": [
    "todobotservice.azurewebsites.net",
    "*.todobotservice.azurewebsites.net"
  ]
}

Инициация действий из сообщенийInitiate actions from messages

Кроме запуска действий из области создание сообщения, можно также использовать расширение системы обмена сообщениями, чтобы инициировать действие из сообщения.In addition to initiating actions from the compose message area, you can also use your messaging extension to initiate an action from a message. Это позволит отправить содержимое сообщения в Bot для обработки и при необходимости ответить на это сообщение с помощью метода, описанного при ответе на отправку.This will allow you to send the contents of the message to your bot for processing, and optionally reply to that message with a response using the method described in Responding to submit. Ответ будет вставлен в ответ на сообщение, которое пользователи могут изменить перед отправкой.The response will be inserted as a reply to the message that your users can edit before submitting. Пользователи могут получить доступ к своему расширению обмена сообщениями из меню переполнения ... , а затем выбрать Take action , как показано на рисунке ниже.Your users can access your messaging extension from the overflow ... menu and then selecting Take action as in the image below.

Пример инициирования действия из сообщения

Чтобы ваше расширение обмена сообщениями работало из сообщения, необходимо добавить context параметр в объект расширения обмена сообщениями commands в манифесте приложения, как показано в примере ниже.To enable your messaging extension to work from a message you'll need to add the context parameter to your messaging extension's commands object in your app manifest as in the example below. Допустимые строки для context массива: "message" , "commandBox" и "compose" .Valid strings for the context array are "message", "commandBox", and "compose". Значение по умолчанию — ["compose", "commandBox"].The default value is ["compose", "commandBox"]. Для получения подробных сведений о параметре обратитесь к разделу define Commands context .See the define commands section for complete details on the context parameter.

"composeExtensions": [
  {
    "botId": "57a3c29f-1fc5-4d97-a142-35bb662b7b23",
    "canUpdateConfiguration": true,
    "commands": [
      {
        "id": "reassignTodo",
        "description": "Reassign a todo item",
        "title": "Create To Do",
        "type": "Action",
        "context": ["message"],
        "fetchTask": true
    }]
    ...

Ниже приведен пример value объекта, содержащего сведения о сообщении, которое будет отправлено в качестве части запроса, composeExtension отправляемого на сервер робота.Below is an example of the value object containing the message details that will be sent as part of the composeExtension request be sent to your bot.

{
  "name": "composeExtension/submitAction",
  "type": "invoke",
...
  "value": {
    "commandId": "setReminder",
    "commandContext": "message",
    "messagePayload": {
      "id": "1111111111",
      "replyToId": null,
      "createdDateTime": "2019-02-25T21:29:36.065Z",
      "lastModifiedDateTime": null,
      "deleted": false,
      "subject": "Message subject",
      "summary": null,
      "importance": "normal",
      "locale": "en-us",
      "body": {
        "contentType": "html",
        "content": "this is the message"
    },
      "from": {
        "device": null,
        "conversation": null,
        "user": {
          "userIdentityType": "aadUser",
          "id": "wxyz12ab8-ab12-cd34-ef56-098abc123876",
          "displayName": "Jamie Smythe"
        },
        "application": null
      },
      "reactions": [
        {
          "reactionType": "like",
          "createdDateTime": "2019-02-25T22:40:40.806Z",
          "user": {
            "device": null,
            "conversation": null,
            "user": {
              "userIdentityType": "aadUser",
              "id": "qrst12346-ab12-cd34-ef56-098abc123876",
              "displayName": "Jim Brown"
            },
            "application": null
          }
        }
      ],
      "mentions": [
        {
          "id": 0,
          "mentionText": "Sarah",
          "mentioned": {
            "device": null,
            "conversation": null,
            "user": {
              "userIdentityType": "aadUser",
              "id": "ab12345678-ab12-cd34-ef56-098abc123876",
              "displayName": "Sarah"
            },
            "application": null
          }
        }
      ]
    }
  ...

Тестирование через отправкуTest via uploading

Вы можете проверить расширение системы обмена сообщениями, отправив свое приложение.You can test your messaging extension by uploading your app. Сведения о том, как загрузить ваше приложение в группу, можно найти в разделе.See Uploading your app in a team for details.

Чтобы открыть расширение системы обмена сообщениями, перейдите к любому из бесед или каналов.To open your messaging extension, navigate to any of your chats or channels. Нажмите кнопку Дополнительные параметры ( ) в поле создать и выберите ваш добавочный номер для обмена сообщениями.Choose the More options ( ) button in the compose box, and choose your messaging extension.

Сбор данных, вводимых пользователямиCollecting input from users

Существует три способа сбора информации от конечного пользователя в Teams.There are three ways to collect information from an end user in Teams.

Список статических параметровStatic parameter list

В этом методе необходимо только определить статический список параметров в манифесте, как показано выше в команде "создать".In this method, all you need to do is define a static list of parameters in the manifest as shown above in the "Create To Do" command. Чтобы использовать этот метод, убедитесь, fetchTask false что в манифесте заданы и определены параметры.To use this method ensure fetchTask is set to false and that you define your parameters in the manifest.

Когда пользователь выбирает команду с помощью статических параметров, Teams создаст форму в модуле задач с параметрами, определенными в манифесте.When a user chooses a command with static parameters, Teams will generate a form in a Task Module with the parameters defined in the manifest. При нажатии на команду Отправить composeExtension/submitAction сообщение a отправляется в Bot.On hitting Submit a composeExtension/submitAction is sent to the bot. В разделе ответ на отправляются дополнительные сведения о ожидаемом наборе ответов.See the topic Responding to submit for more information on the expected set of responses.

Динамическое входное значение с использованием адаптивной карточкиDynamic input using an adaptive card

В этом методе служба может определить настраиваемую адаптивную карточку для сбора данных, вводимых пользователем.In this method, your service can define a custom adaptive card to collect the end user input. Для этого подхода задайте fetchTask для параметра значение true в манифесте.For this approach, set the fetchTask parameter to true in the manifest. Обратите внимание, что если вы задаете fetchTask true любые статические параметры, определенные для команды, будут игнорироваться.Note that if you set fetchTask to true any static parameters defined for the command will be ignored.

В этом методе служба будет получать composeExtension/fetchTask событие и реагировать на откликиот функции адаптивного модуля задач на основе карты.In this method your service will receive a composeExtension/fetchTask event and needs to respond with an adaptive card based task module response. Ниже приведен пример ответа с помощью адаптивной карточки:Below is an sample response with an adaptive card:

{
    "task": {
        "type": "continue",
        "value": {
            "card": {
                "contentType": "application/vnd.microsoft.card.adaptive",
                "content": {
                    "body": [
                        {
                            "type": "TextBlock",
                            "text": "Please enter the following information:"
                        },
                        {
                            "type": "TextBlock",
                            "text": "Name"
                        },
                        {
                            "type": "Input.Text",
                            "spacing": "None",
                            "title": "New Input.Toggle",
                            "placeholder": "Placeholder text"
                        },
                        {
                            "type": "TextBlock",
                            "text": "Date of birth"
                        },
                        {
                            "type": "Input.Date",
                            "spacing": "None",
                            "title": "New Input.Toggle"
                        }
                    ],
                    "type": "AdaptiveCard",
                    "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
                    "version": "1.0"
                }
            }
        }
    }
}

Bot также может отвечать с ответом на запрос проверки подлинности и конфигурации, если пользователю необходимо проверить подлинность или настроить расширение перед тем, как получить входные данные пользователя.The bot can also respond with an auth/config response if the user needs to authenticate or configure the extension before getting the user input.

Динамическое входное значение с использованием веб-представленияDynamic input using a web view

В этом методе служба может показать мини-приложение <iframe> для отображения любого настраиваемого пользовательского интерфейса и сбора вводимых пользователем данных.In this method your service can show an <iframe> based widget to show any custom UI and collect user input. Для этого подхода задайте fetchTask для параметра значение true в манифесте.For this approach, set the fetchTask parameter to true in the manifest.

Как и в случае с адаптивным продвижением карт, ваша служба отправляет fetchTask событие и требует ответа на модуль задачина основе URL-адреса.Just like in the adaptive card flow your service will be send a fetchTask event and needs to respond with a URL based task module response. Ниже приведен пример ответа с помощью адаптивной карточки:Below is an sample response with an Adaptive card:

{
    "task": {
        "value": {
            "url": "http://mywebapp.com/input"
        },
        "type": "continue"
    }
}

Запрос на установку программы "bot" для беседыRequest to install your conversational bot

Если ваше приложение также содержит объект Bot для общения, возможно, перед загрузкой модуля задачи необходимо убедиться, что в беседе установлен почтовый робот.If your app also contains a conversational bot, it may be necessary to ensure that your bot is installed in the conversation before loading your task module. Это может быть удобно в тех случаях, когда требуется получить дополнительный контекст для модуля задач.This can be useful in situations where you need to get additional context for you task module. Например, может потребоваться получить список для заполнения элемента управления "Выбор людей" или список каналов в команде.For example, you may need to fetch the roster to populate a people picker control, or the list of channels in a team.

Для упрощения этого процесса, когда расширение системы обмена сообщениями сначала получает composeExtension/fetchTask запрос на вызов, чтобы проверить, установлен ли ваш Bot в текущем контексте (например, вы можете сделать это с помощью попытки получения списка, например).To facilitate this flow, when your messaging extension first receives the composeExtension/fetchTask invoke check to see if your bot is installed in the current context (you could accomplish this by attempting the get roster call, for example). Если сервер-робот не установлен, вы возвращаете адаптивную карту с действием, которое запрашивает у пользователя установку ленты, в примере ниже.If your bot is not installed, you return an Adaptive Card with an action that requests the user to install your bot See the example below. Обратите внимание, что для этого необходимо, чтобы у пользователя было разрешение на установку приложений в этом расположении; Если они не смогут получить сообщение, попросите их обратиться к администратору.Note that this requires the user to have permission to install apps in that location; if they cannot they will be presented with a message asking them to contact their administrator.

Ниже приведен пример ответа.Here's an example of the response:

{
  "type": "AdaptiveCard",
  "body": [
    {
      "type": "TextBlock",
      "text": "Looks like you haven't used Disco in this team/chat"
    }
  ],
  "actions": [
    {
      "type": "Action.Submit",
      "title": "Continue",
      "data": {
        "msteams": {
          "justInTimeInstall": true
        }
      }
    }
  ],
  "version": "1.0"
}

Когда пользователь завершит установку, ваш робот получит еще одно сообщение Invoke с name = composeExtension/submitAction , и value.data.msteams.justInTimeInstall = true .Once the user completes the installation, your bot will receive another invoke message with name = composeExtension/submitAction, and value.data.msteams.justInTimeInstall = true.

Ниже приведен пример вызова:Here's an example of the invoke:

{
  "value": {
    "commandId": "giveKudos",
    "commandContext": "compose",
    "context": {
      "theme": "default"
    },
    "data": {
      "msteams": {
        "justInTimeInstall": true
      }
    }
  },
  "conversation": {
    "id": "19:7705841b240044b297123ad7f9c99217@thread.skype"
  },
  "name": "composeExtension/submitAction",
  "imdisplayname": "Bob Smith"
}

Вы должны ответить на этот вызов с тем же ответом задачи, на который вы ответили, если он уже установлен.You should respond to this invoke with the same task response you would have responded with if the bot was already installed.

Ответ на отправляютResponding to submit

После того как пользователь завершит ввод данных, пользователь Bot получит composeExtension/submitAction событие с идентификатором команды и значением параметра.Once a user completes entering their input your bot will receive a composeExtension/submitAction event with the command id and parameter values set.

Это различные ожидаемые ответы на submitAction .These are the different expected responses to a submitAction.

Отклик модуля задачиTask Module response

Он используется, когда расширение должно повязать диалоговые окна для получения дополнительных сведений.This is used when your extension needs to chain dialogs together to get more information. Ответ точно такой же, как и fetchTask упоминалось ранее.The response is exactly the same as fetchTask mentioned earlier.

Ответ на запрос проверки подлинности и настройки расширенияCompose extension auth/config response

Этот параметр используется, если для продолжения расширения требуется проверка подлинности или Настройка.This is used when your extension needs to either authenticate or configure in order to continue. Дополнительные сведения см. в разделе "Проверка подлинности " в разделе "Поиск".See authentication section in the search section for more details.

Ответ на результат расширения созданияCompose extension result response

Используется для вставки карточки в поле создание в результате выполнения команды.This used to insert a card into the compose box as a result of a the command. Это тот же ответ, который используется в команде поиска, но он ограничен одной картой или одним результатом в массиве.It's the same response that's used in the search command, but it's limited to one card or one result in the array.

{
  "composeExtension": {
    "type": "result",
    "attachmentLayout": "list",
    "preview": {
          "contentType": "application/vnd.microsoft.card.thumbnail",
          "content": {
            "title": "85069: Create a cool app",
            "images": [
              {
                "url": "https://placekitten.com/200/200"
              }
            ]
          }
        },
    "attachments": [
      {  
        "contentType": "application/vnd.microsoft.teams.card.o365connector",
        "content": {
          "sections": [
            {
              "activityTitle": "[85069]: Create a cool app",
              "activityImage": "https://placekitten.com/200/200"
            },
            {
              "title": "Details",
              "facts": [
                {
                  "name": "Assigned to:",
                  "value": "[Larry Brown](mailto:larryb@example.com)"
                },
                {
                  "name": "State:",
                  "value": "Active"
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Ответ с сообщением адаптивной карточки, отправленной с лентыRespond with an adaptive card message sent from a bot

Вы также можете ответить на действие Отправить, вставив сообщение с адаптивной картой в канал с помощью ленты.You can also respond to the submit action by inserting a message with an Adaptive Card into the channel with a bot. Пользователь сможет просмотреть сообщение перед его отправкой и потенциально редактировать/взаимодействовать с ним.Your user will be able to preview the message before submitting it, and potentially edit/interact with it as well. Это может быть очень удобно в сценариях, в которых необходимо собрать информацию от пользователей, прежде чем создавать адаптивный ответ карты.This can be very useful in scenarios where you need to gather information from your users before creating an adaptive card response. В приведенном ниже сценарии показано, как можно использовать этот процесс для настройки опроса без включения действий по настройке в сообщение канала.The following scenario shows how you can use this flow to configure a poll without including the configuration steps in the channel message.

  1. Пользователь выбирает расширение системы обмена сообщениями для запуска модуля задачи.The user clicks the messaging extension to trigger the task module.
  2. Пользователь использует модуль задач для настройки опроса.The user uses the task module to configure the poll.
  3. После отправки модуля задач конфигурации приложение использует сведения, представленные в модуле задачи, для создания адаптивной карточки и отправки ее в качестве botMessagePreview ответа клиенту.After submitting the configuration task module the app uses the information provided in the task module to craft an adaptive card and sends it as a botMessagePreview response to the client.
  4. После этого пользователь может просмотреть сообщение адаптивной карточки, прежде чем Bot вставит его в канал.The user can then preview the adaptive card message before the bot will inserts it into the channel. Если Bot еще не является участником канала, щелчок добавит Send элемент Bot.If the bot is not already a member of the channel, clicking Send will add the bot.
  5. При взаимодействии с адаптивной картой изменится сообщение перед его отправкой.Interacting with the adaptive card will change the message before sending it.
  6. После того, как пользователь нажмет Send на Bot, в канал будет отправлено сообщение.Once the user clicks Send the bot will post the message to the channel.

Чтобы включить этот рабочий процесс, модуль задачи должен отвечать, как показано в примере ниже, который будет предоставлять пользователю сообщение о предварительном просмотре.To enable this flow your task module should respond as in the example below, which will present the preview message to the user.

Примечание

activityPreviewДолжен содержать message действие с ровно 1 вложенной картой.The activityPreview must contain a message activity with exactly 1 adaptive card attachment.

{
  "composeExtension": {
    "type": "botMessagePreview",
    "activityPreview": {
      "type": "message",
      "attachments":  [
        {
          "contentType": "application/vnd.microsoft.card.adaptive",
          "content": << Card Payload >>
        }
      ]
    }
  }
}

Теперь для расширения сообщения необходимо ответить на два новых типа взаимодействия value.botMessagePreviewAction = "send" и value.botMessagePreviewAction = "edit" .Your message extension will now need to respond to two new types of interactions, value.botMessagePreviewAction = "send" and value.botMessagePreviewAction = "edit". Ниже приведен пример value объекта, который необходимо обработать:Below is an example of the value object you will need to process:

{
  "name": "composeExtension/submitAction",
  "type": "invoke",
  "conversation": { "id": "19:c366b75791784100b6e8b515fd55b063@thread.skype" },
  "imdisplayname": "Pranav Smith",
  ...
  "value": {
    "botMessagePreviewAction": "send" | "edit",
    "botActivityPreview": [
      {
        "type": "message/card",
        "attachments": [
          {
            "content":
              {
                "type": "AdaptiveCard",
                "body": [{<<card payload>>}]
              },
            "contentType" : "application/vnd.microsoft.card.adaptive"
          }
        ],
        "context": { "theme": "default" }
      }
    ],
  }
}

При ответе на edit запрос необходимо ответить на task отклик со значениями, заполненными данными, которые уже были отправлены пользователем.When responding to the edit request you should respond with a task response with the values populated with the information the user has already submitted. При ответе на send запрос необходимо отправить сообщение каналу, содержащему завершенную адаптивную карту.When responding to the send request you should send a message to the channel containing the finalized adaptive card.

teamChatConnector.onComposeExtensionSubmitAction((
    event: builder.IEvent,
    request: teamBuilder.IComposeExtensionActionCommandRequest,
    callback: (err: Error, result: any, statusCode: number) => void) => {
        let invokeValue = (<any> event).value;

        if (invokeValue.botMessagePreviewAction ) {
            let attachment = invokeValue.botActivityPreview[0].attachments[0];

            if (invokeValue.botMessagePreviewAction === 'send') {
                let msg = new builder.Message()
                    .address(event.address)
                    .addAttachment(attachment);
                teamChatConnector.send([msg.toMessage()],
                    (error) => {
                        if(error){
                            //TODO: Handle error and callback
                        }
                        else {
                            callback(null, null, 200);
                        }
                    }
                );
            }

            else if (invokeValue.botMessagePreviewAction === 'edit') {
              // Create the card and populate with user-inputted information
              let card = { ... }

              let taskResponse = {
                task: {
                  type: "continue",
                  value: {
                    title: "Card Preview",
                    card: {
                      contentType: 'application/vnd.microsoft.card.adaptive',
                      content: card
                    }
                  }
                }
              }
              callback(null, taskResponse, 200);
            }

        else {
            let attachment = {
                  //create adaptive card
                };
            let activity = new builder.Message().addAttachment(attachment).toMessage();
            let response = teamBuilder.ComposeExtensionResponse.messagePreview()
                .preview(activity)
                .toResponse();
            callback(null, response, 200);
        }
    });

В этой статье также приведены примеры кода Bot Framework.See also Bot Framework samples.