Создание приложений для собраний группCreate apps for Teams meetings

Необходимые условия и рекомендацииPrerequisites and considerations

  1. Приложения в собраниях требуют некоторых базовых знаний о разработке приложений Teams.Apps in meetings require some basic knowledge of Teams app development. Приложение на собрании может состоять из компонентов вкладок, Ботыи расширений обмена сообщениями и потребует обновления манифеста приложения Teams, чтобы указать, что приложение доступно для собраний.An app in a meeting can comprise of tabs, bots, and messaging extensions features and will require updates to the Teams app manifest to indicate that the app is available for meetings

  2. Чтобы ваше приложение функционировало в жизненном цикле собрания как вкладка, оно должно поддерживать настраиваемые вкладки в области groupchat.For your app to function in the meeting lifecycle as a tab, it must support configurable tabs in the groupchat scope. Ознакомьтесь со статьей расширение приложения Teams с помощью настраиваемой вкладки. Поддержка groupchat области позволит приложению в беседах, выполняемых перед собранием и после него.See Extend your Teams app with a custom tab. Supporting the groupchat scope will enable your app in pre-meeting and post-meeting chats.

  3. Параметры URL-адреса API собраний могут потребоваться meetingId , userId а значение tenantId — в составе клиента Teams SDK и действия Bot.Meeting API URL parameters may require meetingId, userId, and the tenantId These are available as part of the Teams Client SDK and bot activity. Кроме того, можно получить сведения о надежной информации для идентификатора пользователя и идентификатора клиента с помощью проверки подлинности на основе единого входа.Additionally, reliable information for user ID and tenant ID can be retrieved using Tab SSO authentication.

  4. Некоторые API собраний, например, GetParticipant требуют регистрации Bot и идентификатора приложения Bot для создания маркеров проверки подлинности.Some meeting APIs, such as GetParticipant will require a bot registration and bot app ID to generate auth tokens.

  5. Разработчикам следует соблюдать общие рекомендации по проектированию вкладок Teams для сценариев, выполняемых перед и после собраний, а также указания по диалоговому окну для собраний в диалоговом окне для собраний, инициированном во время собрания Teams.As a developer, you must adhere to general Teams tab design guidelines for pre- and post-meeting scenarios as well as the in-meeting dialog guidelines for in-meeting dialog triggered during a Teams meeting.

  6. Обратите внимание, что чтобы приложение обновлялось в режиме реального времени, оно должно быть актуальным в соответствии с действиями событий в собрании.Please note that in order for your app to be updated in real-time, it must be up-to-date based on event activities in the meeting. Эти события могут находиться в диалоговом окне собрания (обратитесь к bot Id параметру завершения в Notification Signal API ) и другим поверхностям во время жизненного цикла собрания.These events can be within the in-meeting dialog (refer to completion bot Id parameter in Notification Signal API) and other surfaces across the meeting lifecycle

Справочные материалы по API приложений для собранийMeeting apps API reference

APIAPI ОписаниеDescription ЗапросRequest SourceSource
жетусерконтекстGetUserContext Получение контекстной информации для отображения релевантного контента на вкладке "команды".Get contextual information to display relevant content in a Teams tab. **microsoftTeams. SPContext (() => {/...* / } )*microsoftTeams.getContext( ( ) => { /.../ } ) Пакет SDK для клиента Microsoft TeamsMicrosoft Teams client SDK
В качестве имени участникаGetParticipant Этот API позволяет интерфейсу Bot получать сведения об участниках по идентификатору собрания и идентификатору участника.This API allows a bot to fetch a participant information by meeting id and participant id. Получение /v1/meetings/{meetingId}/Participants/{participantId}? tenantId = {tenantId}GET /v1/meetings/{meetingId}/participants/{participantId}?tenantId={tenantId} Пакет SDK Microsoft Bot FrameworkMicrosoft Bot Framework SDK
нотификатионсигналNotificationSignal Сигналы собраний будут доставляться с помощью следующего существующего API уведомления о беседе (для разговора пользователя в Bot).Meeting signals will be delivered using the following existing conversation notification API (for user-bot chat). Этот API позволяет разработчикам сообщать на основании действий пользователя, чтобы показывать всплывающее диалоговое окно в собрании.This API allows developers to signal based on end-user action to show-case an in-meeting dialog bubble. POST /v3/conversations/{conversationId}/ActivitiesPOST /v3/conversations/{conversationId}/activities Пакет SDK Microsoft Bot FrameworkMicrosoft Bot Framework SDK

жетусерконтекстGetUserContext

Обратитесь к нашему контексту Get for Teams , чтобы узнать, как идентифицировать и получить контекстные сведения для содержимого вкладки.Please refer to our Get context for your Teams tab documentation for guidance on identifying and retrieving contextual information for your tab content. В рамках расширяемости собраний для полезных данных ответа было добавлено новое значение.As part of meetings extensibility, a new value has been added for the response payload:

meetingId: используется вкладкой при запуске в контексте собрания.meetingId: used by a tab when running in the meeting context.

API-интерфейс-участникGetParticipant API

Примечание

  • Не кэшировать роли участников, так как организатор собрания может изменить роль в любой момент времени.Do not cache participant roles since the meeting organizer can change a role at any point in time.

  • В настоящее время Teams не поддерживает большие списки рассылки или размеры списков, более 350 участников для GetParticipant API.Teams does not currently support large distribution lists or roster sizes of more than 350 participants for the GetParticipant API.

  • Поддержка пакет SDK для ленты скоро будет доступна.Support for the Bot Framework SDK is coming soon.

ЗапросRequest

GET /v3/meetings/{meetingId}/participants/{participantId}?tenantId={tenantId}

Ознакомьтесь со статьей Справочник по API-интерфейсу Bot Framework.See the Bot Framework API reference.

Пример на языке C#C# Example

string meetingId = "meetingid?";
string participantId = "participantidhere";
var connectorClient = turnContext.TurnState.Get<IConnectorClient>();
var creds = connectorClient.Credentials as AppCredentials;
var bearerToken = await creds.GetTokenAsync().ConfigureAwait(false);
var request = new HttpRequestMessage();
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", bearerToken);
request.Method = new HttpMethod("GET");
request.RequestUri = new System.Uri(Path.Combine(connectorClient.BaseUri.OriginalString, $"/meetings/{meetingId}/participants/{participantId}"));
HttpResponseMessage response = await (connectorClient as ServiceClient<ConnectorClient>).HttpClient.SendAsync(request, cancellationToken).ConfigureAwait(false);
if (response.StatusCode == System.Net.HttpStatusCode.OK)
{
    var content = await response.Content.ReadAsStringAsync().ConfigureAwait(false);
    var theObject = Rest.Serialization.SafeJsonConvert.DeserializeObject<WhateverObjectIsReturned>(content, connectorClient.DeserializationSettings);
}

Параметры запросаQuery parameters

ValueValue ТипType ОбязательныйRequired ОписаниеDescription
meetingIdmeetingId stringstring ДаYes Идентификатор собрания можно получить с помощью вызова Bot и клиента Teams SDK Teams.The meeting identifier is available via Bot Invoke and Teams Client SDK.
партиЦипантидparticipantId stringstring ДаYes Это поле является ИДЕНТИФИКАТОРом пользователя и доступно в разделе SSO, вызове Bot и пакете SDK Teams.This field is the User ID and it is available in Tab SSO, Bot Invoke, and Teams Client SDK. Настоятельно рекомендуется использовать единый вход.Tab SSO is highly recommended
tenantIdtenantId stringstring ДаYes Это необходимо для пользователей клиента.This required for tenant users. Он доступен при вводе-вызываемой клавишей TAB, с использованием ленты и клиента Teams SDK.It is available in Tab SSO, Bot Invoke, and Teams Client SDK. Настоятельно рекомендуется использовать единый вход.Tab SSO is highly recommended

Полезные данные ответаResponse Payload

роль в разделе "собрание" может быть организатором, докладчиком или участником.role under "meeting" can be Organizer, Presenter, or Attendee.

Пример 1Example 1

{
  "user":
  {
      "id": "29:1JKiJGPAX9TTxtGxhVo0wLx_zwzo-gG8Z-X03306vBwi9p-xMTEbDXsT6KH7-0kkTS8cD-2zkrsoV6f5WJ6_aYw",
      "aadObjectId": "6aebbad0-e5a5-424a-834a-20fb051f3c1a",
      "name": "Allan Deyoung",
      "givenName": "Allan",
      "surname": "Deyoung",
      "email": "Allan.Deyoung@microsoft.com",
      "userPrincipalName": "Allan.Deyoung@microsoft.com",
      "tenantId": "72f988bf-86f1-41af-91ab-2d7cd011db47",
      "userRole": "user"
  },
  "meeting":
  {
      "role ": "Presenter",
      "inMeeting":true
  },
  "conversation":
  {
      "id": "<conversation id>"
  }
}

Коды ответовResponse Codes

403: приложению не разрешено получать сведения об участнике.403: The app is not allowed to get participant information. Это наиболее распространенный ответ об ошибке, который активируется, когда приложение не установлено на собрании, например, когда оно отключено администратором клиента или блокируется во время миграции Live site.This will be the most common error response and is triggered when the app is not installed in the meeting such as when it is disabled by tenant admin or blocked during live site migration.
200: сведения о участниках успешно получены.200: Participant information successfully retrieved.
401: недопустимый маркер.401: Invalid token.
404: не удается найти участника.404: Participant cannot be found. 500: срок действия собрания истечет (более 60 дней с момента завершения собрания), или у участника нет разрешений на основе их роли.500: The meeting is either expired (more than 60 days since the meeting ended) or the participant does not have permissions based on their role.

Ожидается в ближайшее времяComing Soon

404: срок действия собрания истек или участник не может быть найден.404: the meeting has either expired or participant cannot be found.

API НотификатионсигналNotificationSignal API

Примечание

Когда вызывается диалоговое окно для собраний, то то же самое содержимое также будет представлено в виде сообщения чата.When an in-meeting dialog is invoked, the same content will also be presented as a chat message.

ЗапросRequest

POST /v3/conversations/{conversationId}/activities

Параметры запросаQuery parameters

ValueValue ТипType ОбязательныйRequired ОписаниеDescription
conversationIdconversationId stringstring ДаYes Идентификатор беседы доступен в составе вызова по методу BotThe conversation identifier is available as part of bot invoke

Полезные данные запросаRequest Payload

Примечание

  • В приведенных ниже полезных полезных данных completionBotId параметр externalResourceUrl является необязательным.In the requested payload below, the completionBotId parameter of the externalResourceUrlis an optional. Это то Bot ID , что объявлено в манифесте.It is the Bot ID that is declared in the manifest. Bot получит объект Result.The bot will receive a result object.
  • Параметры ширины и высоты Екстерналресаурцеурл должны находиться в точках.The externalResourceUrl width and height parameters must be in pixels. Ознакомьтесь с рекомендациями по проектированию , чтобы убедиться в том, что размеры находятся в пределах допустимых пределов.Refer to the design guidelines to ensure the dimensions are within the allowed limits.
  • URL-адрес — это страница, загруженная в <iframe> диалоговом окне для собраний.The URL is the page loaded as an <iframe> inside the in-meeting dialog. Домен URL-адреса должен находиться в validDomains массиве приложения в манифесте приложения.The URL's domain must be in the app's validDomains array in your app manifest.
{
    "type": "message",
    "text": "John Phillips assigned you a weekly todo",
    "summary": "Don't forget to meet with Marketing next week",
    "channelData": {
        "notification": {
            "alertInMeeting": true,
            "externalResourceUrl": "https://teams.microsoft.com/l/bubble/APP_ID?url=<url>&height=<height>&width=<width>&title=<title>&completionBotId=BOT_APP_ID"
        }
    },
    "replyToId": "1493070356924"
}

Важно!

URL-адрес в пузырьке содержимого (URL-адрес Таскинфо) должен быть включен в список допустимых доменов , включенный в манифест приложения Teams.The URL in the content bubble (taskInfo URL) must be included in the valid domains list included in the Teams app manifest.

Коды ответовResponse Codes

201: действие с сигналом успешно отправлено201: activity with signal is successfully sent
401: недопустимый маркер401: invalid token
403: приложению не разрешено отправлять сигнал.403: the app is not allowed to send the signal. В этом случае полезная нагрузка должна содержать более подробное сообщение об ошибке.In this case, the payload should contain more detail error message. Может быть несколько причин: приложение отключено администратором клиента, заблокировано во время снижения риска на сайте Live и т. д.There can be many reasons: app disabled by tenant admin, blocked during live site mitigation, etc.
404: чат для собрания не существует404: meeting chat doesn't exist

Включение собраний для приложений в TeamsEnable your app for Teams meetings

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

Возможности приложений для собраний объявляются в манифесте приложения с configurableTabs помощью -> областей конфигураблетабс и контекстных массивов.The meetings app capabilities are declared in your app manifest via the configurableTabs -> scopes and context arrays. Область определяет, для кого и контекст определяет, где будет доступно ваше приложение.Scope defines to whom and context defines where your app will be available.

Примечание

"configurableTabs": [
    {
      "configurationUrl": "https://contoso.com/teamstab/configure",
      "canUpdateConfiguration": true,
      "scopes": [
        "team",
        "groupchat"
      ],
      "context":[
        "channelTab",
        "privateChatTab",
        "meetingChatTab",
        "meetingDetailsTab",
        "meetingSidePanel"
     ]
    }
  ]

Свойство ContextContext property

Вкладка context и scopes свойства работают по гармонии, чтобы определить, где должно отображаться ваше приложение.The tab context and scopes properties work in harmony to allow you to determine where you want your app to appear. Вкладки в team groupchat области действия могут иметь более одного контекста.Tabs in the team or groupchat scope can have more than one context. Для свойства Context возможны следующие значения:The possible values for the context property are as follows:

  • чаннелтаб: вкладка в заголовке канала команды.channelTab: a tab in the header of a team channel.
  • приватечаттаб: вкладка в заголовке группового чата между набором пользователей, которых нет в контексте команды или собрания.privateChatTab: a tab in the header of a group chat between a set of users not in the context of a team or meeting.
  • митингчаттаб: вкладка в заголовке группового чата между набором пользователей в контексте запланированного собрания.meetingChatTab: a tab in the header of a group chat between a set of users in the context of a scheduled meeting.
  • митингдетаилстаб: вкладка в заголовке представления сведений о собрании календаря.meetingDetailsTab: a tab in the header of the meeting details view of the calendar.
  • митингсидепанел: панель для собраний, открытая с помощью унифицированной панели (u-борта).meetingSidePanel: an in-meeting panel opened via the unified bar (u-bar).

Примечание

В настоящее время свойство "Context" в настоящее время не поддерживается и поэтому будет игнорироваться на мобильных клиентах"Context" property is currently not supported and thus will be ignored on mobile clients

Настройка приложения для сценариев собранийConfigure your app for meeting scenarios

Примечание

  • Чтобы ваше приложение отображалось в коллекции вкладок, оно должно поддерживать настраиваемые вкладки и область применения группового чата.For your app to be visible in the tab gallery it needs to support configurable tabs and the group chat scope.

  • Мобильные клиенты поддерживают вкладки только на поверхностях предварительных и посылаемых собраний.Mobile clients support Tabs only in Pre and Post Meeting Surfaces. Скоро будет доступен интерфейс для собраний (диалоговое окно и панель на собрании) на мобильном устройстве.The In-meeting experiences (in-meeting dialog and panel) on mobile will be available soon. Следуйте указаниям по использованию вкладок на мобильном устройстве при создании вкладок для мобильного устройства.Follow the guidance for tabs on mobile when creating your tabs for mobile.

Предварительное собраниеPre-meeting

Пользователи с ролями органайзера и докладчика добавляют вкладки на собрание с помощью кнопки "плюс ➕" в разделе " беседы для собраний" и " сведения о собрании".Users with organizer and/or presenter roles add tabs to a meeting using the plus ➕ button in the meeting Chat and meeting details pages. Расширения обмена сообщениями добавляются в меню "многоточия/переполнение" ●●● , расположенного под областью создание сообщения в чате.Messaging extensions are added to via the ellipses/overflow menu ●●● located beneath the compose message area in the chat. Боты добавляются в чат для собрания с помощью @ ключа "" и выбора Get Боты.Bots are added to a meeting chat using the "@" key and selecting Get bots.

✔ Удостоверение пользователя должно быть подтверждено с помощью единого входа вкладок.✔ The user identity must be confirmed via Tabs SSO. После проверки подлинности приложение может получить роль пользователя через API-участник.Following this authentication, the app can retrieve the user role via the GetParticipant API.

✔ На основе роли пользователя, приложение теперь будет иметь возможность для отображения специальных интерфейсов для ролей.✔ Based on the user role, the app will now have the capability to present role specific experiences. Например, приложение опроса может разрешить только организаторов и докладчикам создавать новый опрос.For example, a polling app can allow only organizers and presenters to create a new poll.

Note: назначения ролей могут быть изменены во время собрания.NOTE: Role assignments can be changed while a meeting is in progress. Просмотр ролей в собрании Teams.See Roles in a Teams meeting.

На собранииIn-meeting

сидепанелsidePanel

✔ В манифесте приложения добавьте сидепанел в массив контекста , как описано выше.✔ In your app manifest add sidePanel to the context array as described above.

✔ На собрании, так же, как и во всех сценариях, приложение будет отображаться на вкладке, расположенной в собрании, 320 пикселей по ширине.✔ In the meeting as well as in all scenarios, the app will be rendered in an in-meeting tab that is 320px in width. Для этого необходимо оптимизировать вкладку.Your tab must be optimized for this. Просмотр, интерфейс фрамеконтекстSee, FrameContext interface

✔ Ссылаться на пакет SDK Teams , чтобы использовать API UserContext для соответствующей маршрутизации запросов.✔Refer to the Teams SDK to use the userContext API to route requests accordingly.

✔ Ссылаться на процесс проверки подлинности Teams для вкладок.✔ Refer to the Teams authentication flow for tabs. Процесс проверки подлинности для вкладок очень похож на процесс проверки подлинности для веб-сайтов.Authentication flow for tabs is very similar to the auth flow for websites. Таким образом, вкладки могут напрямую использовать OAuth 2,0.Thus, tabs can use OAuth 2.0 directly. Кроме того, можно просмотреть потоки кода авторизации для платформы Microsoft identity и OAuth 2,0.See also, Microsoft identity platform and OAuth 2.0 authorization code flow.

Расширение сообщения ✔ должно работать должным образом, если пользователь находится в представлении собраний, и должен иметь возможность отправлять карточки расширения сообщения.✔ Message extension should work as expected when a user is in an in-meeting view and should be able to post compose message extension cards.

✔ AppName in to Meeting — всплывающая подсказка должна указать имя приложения в панели U для собраний.✔ AppName in-meeting - Tooltip should state the app name in-meeting U-bar.

диалоговое окно "в собрании"in-meeting dialog

✔ Необходимо следовать рекомендациям по разработке диалоговых окон для собраний.✔ You must adhere to the in-meeting dialog design guidelines.

✔ Ссылаться на процесс проверки подлинности Teams для вкладок.✔ Refer to the Teams authentication flow for tabs.

✔ Использовать API уведомлений для сигнализации о необходимости запуска пузырькового уведомления.✔ Use the notification API to signal that a bubble notification needs to be triggered.

✔ Как часть полезных данных запроса уведомления, укажите URL-адрес, по которому размещается контент, предназначенный для демонстрации.✔ As part of the notification request payload, include the URL where the content to be showcased is hosted.

✔ Диалоговое окно для собраний не должно использовать модуль задач.✔ In-meeting dialog must not use task module.

Примечание

  • Эти уведомления постоянны.These notifications are persistent in nature. Необходимо вызвать функцию субмиттаск () для автоматического закрытия после того, как пользователь выполняет действие в веб-представлении.You must invoke the submitTask() function to auto-dismiss after a user takes an action in the web-view. Это требование для отправки приложения.This is a requirement for app submission. Раздел пакет SDK для teams: Task module.See also, Teams SDK: task module.

  • Если вы хотите, чтобы приложение поддерживало анонимных пользователей, полезные данные начального запроса вызова должны полагаться на from.id метаданные запроса (ID пользователя) в from объекте, а не на from.aadObjectId метаданные запроса (идентификатор Azure Active Directory для пользователя).If you want your app to support anonymous users, your initial invoke request payload must rely on the from.id (ID of the user) request metadata in the from object, not the from.aadObjectId (Azure Active Directory ID of the user) request metadata. Просмотрите раздел Использование модулей задач на вкладках и Создайте и отправьте модуль задач.See Using task modules in tabs and Create and send the task module.

Завершающее собраниеPost-meeting

Конфигурации после собрания и предварительного собрания эквивалентны.The post-meeting and pre-meeting configurations are equivalent.

Пример приложения для собранийMeeting app sample