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

Extensibilities собрания предоставляют API для преобразования опыта собраний:

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

В следующей таблице приводится список API:

API Описание Запрос Source
GetUserContext Позволяет получать контекстную информацию для отображения соответствующего контента на вкладке Teams. microsoftTeams.getContext() => { /... / } ) Microsoft Teams клиента SDK
GetParticipant Позволяет боту получать сведения о участниках путем собрания ИД и ИД участника. GET /v1/meetings/{meetingId}/participants/{participantsId}?tenantId={tenantId} Microsoft Bot Framework SDK
NotificationSignal Позволяет предоставлять сигналы собрания, которые доставляются с помощью существующего API уведомлений о беседе для чата пользователя-бота. Он позволяет сигнализировать на основе действий пользователя, отображает диалоговое окно на собрании. POST /v3/conversations/{conversationId}/activities Microsoft Bot Framework SDK
Сведения о собрании Позволяет получать статические метаданные собраний. GET /v1/meetings/{meetingId} Bot SDK
shareAppContentToStage Позволяет делиться определенными частями приложения с этапом собрания с боковой панели приложения на собрании. microsoftTeams.meeting.shareAppContentToStage ((err, result) => {} , appContentUrl) Microsoft Teams клиента SDK
getAppContentStageSharingState Позволяет получать сведения о состоянии общего доступа к приложениям на стадии собрания. microsoftTeams.meeting.getAppContentStageSharingState ((err, result)) => {} Microsoft Teams клиента SDK
getAppContentStageSharingCapabilities Позволяет использовать возможности приложений для совместного использования на стадии собрания. microsoftTeams.meeting.getAppContentStageSharingCapabilities ((err, result)) => {} Microsoft Teams клиента SDK

В следующей таблице ниже приводится метод bot Framework SDK для API:

API Метод Bot Framework SDK
GetParticipant GetMeetingParticipantAsync (Microsoft.Bot.Builder.ITurnContext turnContext, string meetingId = default, string participantId = default, string tenantId = default, System.Threading.CancellationToken cancellationToken = default);
NotificationSignal activity.TeamsNotifyUser(true, "https://teams.microsoft.com/l/bubble/APP_ID?url=&height=&width=&title=<title>&completionBotId=BOT_APP_ID");
Сведения о собрании TeamsMeetingInfo (string id = default);

GetUserContext API

Чтобы определить и получить контекстную информацию для содержимого вкладки, см. в тексте получить контекст для вкладки Teams.Используется вкладками при работе в контексте собрания и добавляется для полезной нагрузки meetingId ответа.

GetParticipant API

Примечание

  • Не кэшить роли участников, так как организатор собрания может изменить роли в любое время.
  • Teams в настоящее время не поддерживает большие списки рассылки или размеры реестра более 350 участников GetParticipant API.

API позволяет боту получать сведения о GetParticipant участниках, встречая ID и ID участника. API включает параметры запросов, примеры и коды ответа.

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

API GetParticipant включает следующие параметры запроса:

Значение Тип Обязательный Описание
meetingId Строка Да Идентификатор собрания доступен через Bot Invoke и Teams клиентской SDK.
participantId Строка Да ID участника — это пользовательский ИД. Он доступен в вкладке SSO, Bot Invoke и Teams клиентской SDK. Рекомендуется получить ID участника из SSO tab.
tenantId Строка Да Для пользователей-клиентов требуется ID клиента. Он доступен в вкладке SSO, Bot Invoke и Teams клиентской SDK. Рекомендуется получить ID клиента из SSO tab.

Пример

API GetParticipant содержит следующие примеры:

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
  TeamsMeetingParticipant participant = await TeamsInfo.GetMeetingParticipantAsync(turnContext, "yourMeetingId", "yourParticipantId", "yourParticipantTenantId").ConfigureAwait(false);
  TeamsChannelAccount member = participant.User;
  MeetingParticipantInfo meetingInfo = participant.Meeting;
  ConversationAccount conversation = participant.Conversation;

  await turnContext.SendActivityAsync(MessageFactory.Text($"The participant role is: {meetingInfo.Role}"), cancellationToken);
}

Тело ответа JSON для GetParticipant API:

{
   "user":{
      "id":"29:1JKiJGPAX9TTxtGxhVo0wLx_zwzo-gG8Z-X03306vBwi9p-xMTEbDXsT6KH7-0kkTS8cD-2zkrsoV6f5WJ6_aYw",
      "aadObjectId":"e236c4bf-88b1-4f3a-b1d7-8891dfc332b5",
      "name":"Bob Young",
      "givenName":"Bob",
      "surname":"Young",
      "email":"Bob.young@microsoft.com",
      "userPrincipalName":"Bob.young@microsoft.com",
      "tenantId":"2fe477ab-0efc-4dfd-bde2-484374e2c373",
      "userRole":"user"
   },
   "meeting":{
      "role ":"Presenter",
      "inMeeting":true
   },
   "conversation":{
      "id":"<conversation id>",
      "isGroup":true
   }
}

Коды ответа

API GetParticipant возвращает следующие коды ответа:

Код ответа Описание
403 Сведения о участниках не делятся с приложением. Если приложение не установлено на собрании, оно вызывает наиболее распространенный ответ на ошибку 403. Если администратор клиента отключает или блокирует приложение во время переноса веб-сайта в прямом эфире, запускается ответ на ошибку 403.
200 Данные участника успешно извлекаются.
401 Приложение отвечает недействительным маркером.
404 Собрание истеко или участник не может быть найден.

NotificationSignal API

Все пользователи на собрании получают уведомления, отправленные через NotificationSignal API.

Примечание

  • При вызове диалогового окна на собрании содержимое представляется в качестве сообщения чата.
  • В настоящее время отправка целевых уведомлений не поддерживается.

NotificationSignal API позволяет предоставлять сигналы собраний, которые доставляются с помощью существующего API уведомлений о беседе для чата пользователя-бота. Этот API позволяет сигнализировать на основе действий пользователя, отображает диалоговое окно в собрании. API включает параметр запроса, примеры и коды ответа.

Параметр запроса

API NotificationSignal включает в себя следующий параметр запроса:

Значение Тип Обязательный Описание
conversationId Строка Да Идентификатор беседы доступен в рамках Bot Invoke.

Примеры

Объявляется Bot ID в манифесте, и бот получает объект результата.

Примечание

  • Параметр completionBotId необязательный externalResourceUrl в примере запрашиваемой полезной нагрузки. Bot ID объявляется в манифесте, и бот получает объект результата.
  • Параметры externalResourceUrl ширины и высоты должны быть в пикселях. Чтобы размеры были в пределах допустимого, см. в рекомендациях по проектированию.
  • URL-адрес — это страница, загруженная в диалоговом окне на <iframe> собрании. Домен должен быть в массиве приложения в validDomains манифесте приложения.

API NotificationSignal содержит следующие примеры:

Activity activity = MessageFactory.Text("This is a meeting signal test");
activity.TeamsNotifyUser(true, "https://teams.microsoft.com/l/bubble/APP_ID?url=<url>&height=<height>&width=<width>&title=<title>&completionBotId=BOT_APP_ID");
await turnContext.SendActivityAsync(activity).ConfigureAwait(false);

Коды ответа

API NotificationSignal включает в себя следующие коды ответа:

Код ответа Описание
201 Успешно отправляется действие с сигналом.
401 Приложение отвечает недействительным маркером.
403 Приложение не может отправить сигнал. Код ответа 403 может возникать по различным причинам, например, администратор клиента отключает и блокирует приложение во время переноса веб-сайтов в прямом эфире. В этом случае полезное сообщение содержит подробное сообщение об ошибке.
404 Чат собраний не существует.

API сведений о собраниях

Примечание

В настоящее время эта функция доступна только для предварительного просмотра общедоступных разработчиков.

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

Предварительное условие

Чтобы использовать API сведений о собраниях, необходимо получить разрешения RSC. Чтобы настроить свойство манифеста приложения, используйте следующий webApplicationInfo пример:

"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
    "applicationPermissions": [
      "OnlineMeeting.ReadBasic.Chat"
    ]
}

Параметр запроса

API сведений о собраниях включает в себя следующий параметр запроса:

Значение Тип Обязательный Описание
meetingId Строка Да Идентификатор собрания доступен через Bot Invoke и Teams клиентской SDK.

Пример

API сведений о собраниях содержит следующие примеры:

MeetingInfo result = await TeamsInfo.GetMeetingInfoAsync(turnContext);
await turnContext.SendActivityAsync(JsonConvert.SerializeObject(result));

The JSON response body for Meeting Details API is as follows:

{ 
   "details": { 
        "id": "meeting ID", 
        "msGraphResourceId": "", 
        "scheduledStartTime": "2020-08-21T02:30:00+00:00", 
        "scheduledEndTime": "2020-08-21T03:00:00+00:00", 
        "joinUrl": "https://teams.microsoft.com/l/xx", 
        "title": "All Hands", 
        "type": "Scheduled" 
    }, 
    "conversation": { 
            "isGroup": true, 
            “conversationType”: “groupchat”, 
            "id": "meeting chat ID" 
    }, 
    "organizer": { 
        "id": "<organizer user ID>", 
        "aadObjectId": "<AAD ID>", 
        "tenantId": "<Tenant ID>" 
    }
} 

API shareAppContentToStage

API позволяет обмениваться определенными частями приложения shareAppContentToStage на стадии собрания. API доступен через Teams клиента SDK.

Предварительное условие

Чтобы использовать shareAppContentToStage API, необходимо получить разрешения RSC. В манифесте приложения настройте authorization свойство, а также поле name и type в resourceSpecific поле. Например:

"authorization": {
    "permission": { 
    "resourceSpecific": [
      { 
      "name": "MeetingStage.Write.Chat",
      "type": "Delegated"
      }
    ]
   }
}

Параметр запроса

API shareAppContentToStage включает следующие параметры:

Значение Тип Обязательный Описание
callback Строка Да Callback содержит два параметра: ошибка и результат. Ошибка может содержать ошибку типа SdkError, в случае ошибки или null при успешном совместном окне. Результат может содержать истинное значение в случае успешной доли или нулевую при сбойе.
appContentURL Строка Да URL-адрес, который будет делиться на сцене.

Пример

В следующих кодах приводится пример shareAppContentToStage API:

Недоступно

Коды ответа

API shareAppContentToStage возвращает следующие коды ответа:

Код ответа Описание
500 Внутренняя ошибка.
501 API не поддерживается в текущем контексте.
1000 Приложение не имеет надлежащих разрешений для допуска к этапу обмена данными.

API getAppContentStageSharingState

API позволяет получать сведения о совместном использовании приложений getAppContentStageSharingState на стадии собрания.

Параметр запроса

API getAppContentStageSharingState включает в себя следующий параметр:

Значение Тип Обязательный Описание
callback Строка Да Callback содержит два параметра: ошибка и результат. Ошибка может содержать ошибку типа SdkError, в случае ошибки или null при успешном совместном окне. В результате может содержаться объект, указывающий на успешное и повторное и повторное, или null, указывающий на неудачное AppContentStageSharingState и повторное.

Пример

В следующих кодах приводится пример getAppContentStageSharingState API:

Недоступно

Тело ответа JSON для getAppContentStageSharingState API:

{
   "isAppSharing":true
  }
  

Коды ответа

API getAppContentStageSharingState возвращает следующие коды ответа:

Код ответа Описание
500 Внутренняя ошибка.
501 API не поддерживается в текущем контексте.
1000 Приложение не имеет надлежащих разрешений для допуска к этапу обмена данными.

getAppContentStageSharingCapabilities API

API позволяет добирать возможности приложений для getAppContentStageSharingCapabilities совместного использования до стадии собрания.

Параметр запроса

Включает getAppContentStageSharingCapabilities в себя следующие параметры:

Значение Тип Обязательный Описание
callback Строка Да Callback содержит два параметра: ошибка и результат. Ошибка может содержать ошибку типа SdkError, в случае ошибки или null при успешном совместном окне. В результате может содержаться объект, указывающий на успешное и повторное и повторное, или null, указывающий на неудачное AppContentStageSharingState и повторное.

Пример

В следующих кодах приводится пример getAppContentStageSharingCapabilities API:

Недоступно

Тело ответа JSON для getAppContentStageSharingCapabilities API:

{
   "doesAppHaveSharePermission":true
  }
  

Коды ответа

API getAppContentStageSharingCapabilities возвращает следующие коды ответа:

Код ответа Описание
500 Внутренняя ошибка.
1000 У приложения нет разрешений на доступ к совместному доступу к этапу.

События Teams в режиме реального времени

Пользователь может получать события собраний в режиме реального времени. Как только любое приложение связано с собранием, фактическое время начала и окончания собрания передается боту.

Фактическое время начала и окончания собрания отличается от запланированного времени начала и окончания. API сведений о собраниях предоставляет запланированное время начала и окончания. Событие предоставляет фактическое время начала и окончания.

Предварительное условие

Манифест приложения должен иметь свойство для получения событий webApplicationInfo начала и окончания собрания. Чтобы настроить манифест, используйте следующий пример:

"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
    "applicationPermissions": [
      "OnlineMeeting.ReadBasic.Chat"
    ]
}

Пример полезной нагрузки на начало собрания

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

{ 
    "name": "application/vnd.microsoft.meetingStart", 
    "type": "event", 
    "timestamp": "2021-04-29T16:10:41.1252256Z", 
    "id": "123", 
    "channelId": "msteams", 
    "serviceUrl": "https://microsoft.com", 
    "from": { 
        "id": "userID", 
        "aadObjectId": "aadOnjectId" 
    }, 
    "conversation": { 
        "isGroup": true, 
        "tenantId": "tenantId", 
        "id": "thread id" 
    }, 
    "recipient": { 
        "id": "user Id", 
        "name": "user name" 
    }, 
    "entities": [ 
        { 
            "locale": "en-US", 
            "country": "US", 
            "type": "clientInfo" 
        } 
    ], 
    "channelData": { 
        "tenant": { 
            "id": "channel id" 
        }, 
        "source": null, 
        "meeting": { 
            "id": "meeting id" 
        } 
    }, 
    "value": { 
        "MeetingType": "Scheduled", 
        "Title": "Meeting Start/End Event", 
        "Id": "meeting id", 
        "JoinUrl": "url" 
        "StartTime": "2021-04-29T16:17:17.4388966Z" 
    }, 
    "locale": "en-US" 
}

Пример полезной нагрузки конечного события собрания

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

{ 
    "name": "application/vnd.microsoft.meetingEnd", 
    "type": "event", 
    "timestamp": "2021-04-29T16:17:17.4388966Z", 
    "id": "123", 
    "channelId": "msteams", 
    "serviceUrl": "https://microsoft.com", 
    "from": { 
        "id": "user id", 
        "aadObjectId": "aadObjectId" 
    }, 
    "conversation": { 
        "isGroup": true, 
        "tenantId": "tenantId", 
        "id": "thread id" 
    }, 
    "recipient": { 
        "id": "user id", 
        "name": "user name" 
    }, 
    "entities": [ 
        { 
            "locale": "en-US", 
            "country": "US", 
            "type": "clientInfo" 
        } 
    ], 
    "channelData": { 
        "tenant": { 
            "id": "channel id" 
        }, 
        "source": null, 
        "meeting": { 
            "id": "meeting Id" 
        } 
    }, 
    "value": { 
        "MeetingType": "Scheduled", 
        "Title": "Meeting Start/End Event in Canary", 
        "Id": "19:meeting_NTM3ZDJjOTUtZGRhOS00MzYxLTk5NDAtMzY4M2IzZWFjZGE1@thread.v2", 
        "JoinUrl": "url", 
        "EndTime": "2021-04-29T16:17:17.4388966Z" 
    }, 
    "locale": "en-US" 
}

Пример получения метаданных собрания

Ваш бот получает событие через OnEventActivityAsync обработник.

Для десерализации полезной нагрузки json для получения метаданных собрания вводится объект модели. Метаданные собрания в свойстве в value полезной нагрузке события. Создается объект модели, переменные члена которого соответствуют клавишам, которые находятся под свойством MeetingStartEndEventvalue value в полезной нагрузке события.

Примечание

  • Получите ID собрания из turnContext.ChannelData .
  • Не используйте ИД беседы в качестве ИД собрания.
  • Не используйте ID собрания из полезной нагрузки на события turncontext.activity.value собраний.

В следующем коде показано, как захватить метаданные собрания, которое является MeetingType , , , , , и из события начала и конца Title Id JoinUrl StartTime EndTime собрания:

Событие "Начало собрания"

protected override async Task OnTeamsMeetingStartAsync(MeetingEndEventDetails meeting, ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
    await turnContext.SendActivityAsync(JsonConvert.SerializeObject(meeting));
}

Событие конца собрания

protected override async Task OnTeamsMeetingEndAsync(MeetingEndEventDetails meeting, ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
    await turnContext.SendActivityAsync(JsonConvert.SerializeObject(meeting));
}

Пример кода

Название примера Описание C# Node.js
Разнонасть собраний Microsoft Teams для прохождения маркеров. View View
Бот-бот для пузырьков контента для собраний Microsoft Teams для взаимодействия с ботом пузырьков контента на собрании. View View
Собрание MeetingSidePanel Microsoft Teams для взаимодействия с боковой панелью на собрании. View View
Вкладка "Сведения в собрании" Microsoft Teams для взаимодействия с вкладками Details in-meeting. View View
Пример событий собраний Пример приложения для демонстрации событий Teams собраний в режиме реального времени View View
Пример набора собраний Пример приложения для демонстрации опыта собраний для сценария набора персонала. View View
Установка приложения с помощью кода QR Пример приложения, которое создает код QR и устанавливает приложение с помощью кода QR View Просмотр

Дополнительные ресурсы

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