Создание расширения для сообщений с помощью App StudioCreate a messaging extension using App Studio

Совет

Ищете быстрый способ приступить к работе?Looking for a faster way to get started? Создайте расширение системы обмена сообщениями с помощью набора инструментов Microsoft Teams.Create a messaging extension using the Microsoft Teams Toolkit.

На высоком уровне необходимо выполнить следующие действия, чтобы создать расширение системы обмена сообщениями.At a high level, you'll need to complete the following steps to create a messaging extension.

  1. Подготовка среды разработкиPrepare your development environment
  2. Создание и развертывание веб-службы (при разработке используйте службу туннелирования, например ngrok, чтобы запускать ее локально)Create and deploy your web service (while developing use a tunneling service like ngrok to run it locally)
  3. Регистрация веб-службы в Bot FrameworkRegister your web service with the Bot Framework
  4. Создайте свой пакет приложенийCreate your app package
  5. Отправка пакета в Microsoft TeamsUpload your package to Microsoft Teams

Создание веб-службы, создание пакета приложения и регистрация веб-службы с помощью Bot Framework можно выполнять в любом порядке.Creating your web service, creating your app package, and registering your web service with the Bot Framework can be done in any order. Так как эти три части так интертвинед, вам потребуется вернуться, чтобы обновить другие.Because those three pieces are so intertwined, no matter which order you do them in you'll need return to update the others. Для регистрации требуется конечная точка обмена сообщениями из развернутой веб-службы, а веб-службе требуется идентификатор и пароль, созданные при регистрации.Your registration needs the messaging endpoint from your deployed web service, and your web service needs the Id and password created from your registration. Манифест приложения также должен использовать этот идентификатор для подключения Teams к вашей веб-службе.Your app manifest also needs that Id to connect Teams to your web service.

Когда вы создаете расширение системы обмена сообщениями, регулярно перемещайтесь между изменением манифеста приложения и развертыванием кода в веб-службе.As you're building your messaging extension, you'll regularly be moving between changing your app manifest, and deploying code to your web service. При работе с манифестом приложения помните, что вы можете вручную управлять файлом JSON или вносить изменения через приложение App Studio.When working with the app manifest, keep in mind that you can either manually manipulate the JSON file, or make changes through App Studio. В любом случае вам потребуется повторно развернуть (отправить) ваше приложение в Teams, если вы вносите изменения в манифест, но это не нужно делать при развертывании изменений в веб-службе.Either way, you'll need to re-deploy (upload) your app in Teams when you make a change to the manifest, but there's no need to do so when you deploy changes to your web service.

Подготовка среды разработкиPrepare your development environment

Первое, что нужно сделать, — подготовить среду разработки.The first thing you'll need to do is prepare your development environment. Необходимо убедиться в том, что для организации Office 365, в которой вы хотите создать приложение, включена специальная передача приложений.You'll need to make sure custom app uploading is enabled for the Office 365 organization you want to build your app in. Если вам нужен выделенный клиент разработки, вы можете зарегистрироваться в программе для разработчиков Office 365.If you need a dedicated development tenant, you can sign up for the Office 365 developer program. Дополнительные сведения см. в статье Настройка среды разработки.For additional information see Setup your development environment.

Создание веб-службыCreate your web service

Сердце расширения системы обмена сообщениями — это веб-служба.The heart of your messaging extension is your web service. Он будет определять один маршрут, как правило, /api/messages для получения всех запросов.It will define a single route, typically /api/messages, to receive all requests on. Если вы приступите к работе с нуля, вы можете выбрать один из вариантов.If you're getting started from scratch, you have a few options to choose from.

  • Воспользуйтесь одним из учебных руководств, посвященных созданию веб-службы.Use one of our quickstarts tutorials that will guide you through the creation of your web service.
  • Выберите один из примеров расширения обмена сообщениями, доступных в репозитории примера ленты Bot , чтобы начать с.Choose one of the messaging extension samples available in the Bot Framework sample repository to start from.
  • Если вы используете JavaScript, используйте генератор Yeoman для Microsoft Teams , чтобы сформировать шаблон приложения Teams, в том числе веб-службу.If you're using JavaScript, use the Yeoman generator for Microsoft Teams to scaffold your Teams app, including your web service.
  • Создайте веб-службу с нуля.Create your web service from scratch. Вы можете добавить пакет SDK Bot Framework для своего языка или работать непосредственно с полезными данными JSON.You can choose to add the Bot Framework SDK for your language, or you can work directly with the JSON payloads.

Регистрация веб-службы в Bot FrameworkRegister your web service with the Bot Framework

Расширения обмена сообщениями используют схему обмена сообщениями и протокол безопасного обмена сообщениями в среде Bot. Если вы еще не сделали это, вам потребуется зарегистрировать веб-службу в Bot Framework.Messaging extensions take advantage of the Bot Framework's messaging schema and secure communication protocol; if you don't already have one you'll need to register your web service on the Bot Framework. Идентификатор приложения Microsoft (мы будем называть его идентификатором ленты в Teams, чтобы определить его с помощью идентификатора другого приложения, с которым вы можете работать), а конечная точка обмена сообщениями будет использоваться в вашем расширении обмена сообщениями для получения и ответа на запросы.The Microsoft App Id (we'll refer to this as your Bot Id from inside of Teams, to identify it from other App Id's you might be working with) and the messaging endpoint your register with the Bot Framework will be used in your messaging extension to receive and respond to requests. Если вы используете существующую регистрацию, убедитесь, что вы включили канал Microsoft Teams.If you're using an existing registration, make sure you enable the Microsoft Teams channel.

Если вы выберете один из примеров или начните с одного из доступных примеров, вы будете участником регистрации веб-службы.If you follow one of the quickstarts or start from one of the available samples you'll be guided through registering your web service. Если вы хотите зарегистрировать службу вручную, у вас есть три варианта.If you want to manually register your service you have three options to do so. Если вы решите зарегистрировать, не используя подписку на Azure, вы не сможете использовать упрощенный процесс проверки подлинности OAuth, предоставленный в интерфейсе Bot.If you choose to register without using an Azure subscription you will not be able to take advantage of the simplified OAuth authentication flow provided by the Bot Framework. Вы сможете перенести регистрацию в Azure после создания.You will be able to migrate your registration to Azure after creation.

  • Если у вас есть подписка на Azure (или вы хотите создать новую), вы можете зарегистрировать веб-службу вручную с помощью портала Azure.If you have an Azure subscription (or want to create a new one), you can register your web service manually using the Azure Portal. Создайте ресурс "регистрация каналов ленты".Create a "Bot Channels Registration" resource. Вы можете выбрать бесплатную ценовую категорию, поскольку сообщения от Microsoft Teams не будут подсчитывать общее количество разрешенных сообщений в месяц.You can choose the free pricing tier, as messages from Microsoft Teams do not count towards your total allowable messages per month.
  • Если вы не хотите использовать подписку на Azure, вы можете использовать устаревший портал регистрации.If you do not wish to use an Azure subscription, you can use the legacy registration portal.
  • Кроме того, с помощью App Studio можно зарегистрировать веб-службу (Bot).App Studio can also help you register your web service (bot). Веб-службы, зарегистрированные с помощью App Studio, не зарегистрированы в Azure.Web services registered through App Studio are not registered in Azure. Портал прежних версий можно использовать для просмотра и переноса регистраций, управления ими и их переноса.You can use the legacy portal to view, manage, and migrate your registrations.

Создание манифеста приложенияCreate your app manifest

Вы можете использовать App Studio для создания манифеста приложения или создать его вручную.You can either use App Studio to help you create your app manifest, or create it manually.

Создание манифеста приложения с помощью App StudioCreate your app manifest using App Studio

Вы можете использовать приложение App Studio в клиенте Microsoft Teams, чтобы помочь создать манифест приложения.You can use the App Studio app from within the Microsoft Teams client to help create your app manifest.

  1. В клиенте Teams откройте App Studio из меню переполнения ... на панели навигации слева.In the Teams client, open App Studio from the ... overflow menu on the left navigation rail. Если он еще не установлен, можно сделать это, выполнив поиск.If it isn't already installed, you can do so by searching for it.
  2. На вкладке редактор манифеста выберите создать новое приложение (или, если вы добавляете расширение для обмена сообщениями в существующее приложение, вы можете импортировать пакет приложения)On the Manifest editor tab select Create a new app (or if you're adding a messaging extension to an existing app, you can import your app package)
  3. Добавьте сведения о приложении (см. определение схемы манифеста с полным описанием каждого поля).Add your app details (see manifest schema definition for full descriptions of each field).
  4. На вкладке расширения обмена сообщениями нажмите кнопку установить .On the Messaging extensions tab click the Setup button.
  5. Вы можете создать новую веб-службу (Bot) для используемого расширения обмена сообщениями, или если вы уже зарегистрировали одну из них, а затем добавить ее здесь.You can either create a new web service (bot) for your messaging extension to use, or if you've already registered one select/add it here.
  6. При необходимости обновите адрес конечной точки бота, чтобы он указывал на вашего бота.If necessary, update your bot endpoint address to point to your bot. Он должен выглядеть примерно следующим образом: https://someplace.com/api/messages.It should look something like https://someplace.com/api/messages.
  7. Кнопка Добавить в разделе команда поможет добавить команды к своему расширению обмена сообщениями.The Add button in the Command section will guide you through adding commands to your messaging extension. В разделе Дополнительные сведения приведены ссылки на дополнительные сведения о добавлении команд.See the Learn more section for links to more information on adding commands. Помните, что вы можете определить до 10 команд для своего расширения обмена сообщениями.Remember you can define up to 10 commands for your messaging extension.
  8. Раздел обработчики сообщений позволяет добавить домен, на котором будет запускаться обмен сообщениями.The Message Handlers section allows you to add a domain that your messaging will trigger on. Для получения дополнительных сведений обратитесь к разделу Link унфурлинг .See link unfurling for more information.

На вкладке Готово => тест и распределить можно скачать пакет приложения (включая манифест приложения, а также значки приложений) или установить пакет.From the Finish => Test and distribute tab you can Download your app package (which includes your app manifest as well as your app icons), or Install the package.

Создание манифеста приложения вручнуюCreate your app manifest manually

Как и в случае с Боты и вкладками, вы обновляете Манифест приложения, чтобы включить свойства расширения обмена сообщениями.As with bots and tabs, you update the app 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 app manifest with the composeExtensions property. Вы можете создать одно расширение обмена сообщениями для своего приложения, используя до 10 команд.You create a single messaging extension for your app, with up to 10 commands.

Примечание

Манифест содержит ссылки на расширения обмена сообщениями 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
canUpdateConfiguration Включает пункт меню параметров .Enables Settings menu item. НетNo
commands Массив команд, поддерживаемых этим расширением обмена сообщениями.Array of commands that this messaging extension supports. Можно выполнить не более 10 команд.You are limited to 10 commands. ДаYes

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

Ваш модуль обмена сообщениями должен объявить одну или несколько команд, определяющих, где пользователи могут активировать ваш модуль обмена сообщениями, и тип взаимодействия.Your messaging extension should declare one or more commands, which define where your users can trigger your messaging extension, and the type of interaction. Дополнительные сведения о командах расширения системы обмена сообщениями приведены в статье дополнительные сведения.See learn more for more information on messaging extension commands.

Пример простого манифестаSimple manifest example

В приведенном ниже примере показан объект простого расширения обмена сообщениями в манифесте приложения с помощью команды поиска.The example below is a simple messaging extension object in the app manifest with a search command. Это не весь файл манифеста приложения, а только часть, относящаяся к расширениям для обмена сообщениями.This is not the entire app manifest file, just the part specific to messaging extensions. Полный пример приведен в статье схема манифеста приложения .See app manifest schema for a complete example.

...
"composeExtensions": [
  {
    "botId": "abcd1234-1fc5-4d97-a142-35bb662b7b23",
    "canUpdateConfiguration": true,
    "commands": [
      {
        "id": "searchCmd",
        "description": "Search you ToDo's",
        "title": "Search",
        "initialRun": true,
        "parameters": [
          {
            "name": "searchKeyword",
            "description": "Enter your search keywords",
            "title": "Keywords"
          }
        ]
      }
    ]
  }
]
...

Добавление обработчиков сообщений о вызовахAdd your invoke message handlers

Когда ваши пользователи запускают расширение системы обмена сообщениями, необходимо обработать исходное сообщение о вызове, собрать некоторую информацию от пользователя, затем обработать эту информацию и ответить соответствующим образом.When your users trigger your messaging extension you'll need to handle the initial invoke message, collect some information from the user, then process that information and respond appropriately. Для этого сначала необходимо решить, какие команды вы хотите добавить в расширение системы обмена сообщениями, и либо добавить команды действий , либо добавить команды поиска.To do that, you'll first need to decide what kind of commands you want to add to your messaging extension and either add an action commands or add a search commands.

Расширения обмена сообщениями в собраниях TeamsMessaging extensions in Teams meetings

Примечание

Если в списке собраний или группового чата есть Федеративные пользователи, Teams подавляет доступ к расширениям обмена сообщениями для всех пользователей, в том числе организатора.If a meeting or group chat has federated users in the roster, Teams suppresses access to messaging extensions for all users, including the organizer.

После начала собрания участники Teams могут напрямую взаимодействовать с расширением обмена сообщениями во время интерактивного звонка.Once a meeting begins, Teams participants can interact directly with your messaging extension during a live call. При создании расширения обмена сообщениями для собраний учитывайте следующее:Consider the following when building your in-meeting messaging extension:

  1. Location.Location. Ваш модуль обмена сообщениями можно вызвать из области создание сообщения, команды или @mentioned в чате для собрания.Your messaging extension can be invoked from the compose message area, the command box, or @mentioned in the meeting chat.

  2. Metadata (метаданные).Metadata. При вызове расширения обмена сообщениями он может идентифицировать пользователя и клиента из userId и tenantId .When your messaging extension is invoked it can identify the user and tenant from userId and tenantId. meetingId может быть частью объекта channelData.The meetingId can be found as part of the channelData object. Приложение может использовать userId meetingId GetParticipant запрос API и для получения ролей пользователей.Your app can use the userId and meetingId for the GetParticipant API request to retrieve user roles.

  3. Тип команды.Command type. Если расширение сообщения использует команды на основе действий, оно должно соответствовать вкладкам проверки подлинности с единым входом .If your message extension uses action-based commands, it should follow tabs single sign-on authentication.

  4. Взаимодействие с пользователем.User experience. Расширение системы обмена сообщениями должно выглядеть и работать так же, как и за пресроком собрания.You messaging extension should look and behave the same as it would outside a meeting.

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

ПодробнееLearn more

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

Узнайте больше о концепциях разработки teams:Learn more about Teams development concepts: