API приложений для собраний

Статья
03/22/2023
Чтение занимает 21 мин

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

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

Примечание.

Используйте клиентскую библиотеку Microsoft Teams JavaScript (TeamsJS) (версия 1.10 и более поздние версии) для единого входа для работы на боковой панели собрания.

В следующей таблице представлен список API, доступных в библиотеке JavaScript в Microsoft Teams и пакетах SDK Microsoft Bot Framework:

Метод	Описание	Источник
Получить пользовательский контекст	Получите контекстную информацию для отображения соответствующего содержимого на вкладке Microsoft Teams.	Библиотека TeamsJS
Получение участника	Получить информацию об участнике по идентификатору собрания и идентификатору участника.	Пакет SDK для Microsoft Bot Framework
Отправить уведомление о собрании	Предоставляет сигналы собрания с помощью существующего API уведомлений о беседах для чата пользователя-бота и позволяет уведомлять пользователя о действиях, отображающих уведомление о собрании.	Пакет SDK для Microsoft Bot Framework
Получить сведения о собрании	Получите статические метаданные собрания.	Пакет SDK для Microsoft Bot Framework
Отправляйте субтитры в реальном времени	Отправка субтитров к текущему собранию в режиме реального времени.	Библиотека TeamsJS
Делитесь содержимым приложения на сцене	Поделитесь определенными частями приложения на сцене собрания с боковой панели приложения в собрании.	Библиотека TeamsJS
Получать события собраний Teams в режиме реального времени	Узнавать о событиях собраний в режиме реального времени, таких как фактическое время начала и окончания.	Пакет SDK для Microsoft Bot Framework
Получение состояния входящего звука	Позволяет приложению получить параметр состояния входящего звука для пользователя собрания.	Библиотека TeamsJS
Переключение входящего звука	Позволяет приложению переключать параметр состояния входящего звука для пользователя собрания с включения звука или наоборот.	Библиотека TeamsJS

Получить API пользовательского контекста

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

Получить API участника

API GetParticipant должен иметь регистрацию бота и идентификатор для создания токенов авторизации Подробнее в разделе Регистрация и идентификатор бота..

Примечание.

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

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

Совет

Получите идентификаторы участников и арендаторов на вкладке проверки подлинности единого входа.

API Meeting должен иметь meetingId, participantId и tenantId в качестве параметров URL-адреса. Параметры доступны как часть клиентской библиотеки JavaScript (TeamsJS) Microsoft Teams и действия бота.

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

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

Пример

protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
  // Gets the details for the given meeting participant. 
  // This only works in Teams meeting scoped conversations.
  TeamsMeetingParticipant participant = await TeamsInfo.GetMeetingParticipantAsync(turnContext, "yourMeetingId", "yourParticipantId", "yourParticipantTenantId").ConfigureAwait(false);
  TeamsChannelAccount member = participant.User;
  MeetingParticipantInfo meetingInfo = participant.Meeting;
  ConversationAccount conversation = participant.Conversation;

  // Sends a message activity to the sender of the incoming activity. 
  await turnContext.SendActivityAsync(MessageFactory.Text($"The participant role is: {meetingInfo.Role}"), cancellationToken);
}

export class MyBot extends TeamsActivityHandler {
    constructor() {
        super();
        this.onMessage(async (context, next) => {

            // getMeetingParticipant : Gets the details for the given meeting participant. 
            // This only works in Teams meeting scoped conversations.
            TeamsMeetingParticipant participant = getMeetingParticipant(turnContext, "yourMeetingId", "yourParticipantId", "yourTenantId");
            let member = participant.user;
            let meetingInfo = participant.meeting;
            let conversation = participant.conversation;

            // Sends a message activity to the sender of the incoming activity. 
            await context.sendActivity(`The participant role is: '${meetingInfo.role}'`);

            // By calling next() you ensure that the next BotHandler is run.
            await next();
        });
    }
}

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

{
   "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>",
      "conversationType": "groupChat", 
      "isGroup":true
   }
}

Имя свойства	Описание
user.id	Идентификатор пользователя.
user.aadObjectId	Идентификатор объекта Azure Active Directory пользователя.
user.name	Имя пользователя.
user.givenName	Имя пользователя.
user.surname	Фамилия пользователя.
user.email	Идентификатор почты пользователя.
user.userPrincipalName	Имя участника-пользователя.
user.tenantId	Идентификатор клиента Azure Active Directory.
user.userRole	Роль пользователя. Например, "admin" или "user".
meeting.role	Роль участника в собрании. Например, "Организатор", "Выступающий" или "Участник".
meeting.inMeeting	Значение, указывающее, находится ли участник в собрании.
conversation.id	Идентификатор чата собрания.
conversation.isGroup	Логическое значение, указывающее, имеет ли беседа более двух участников.

Коды ответа

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

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

Отправить уведомление о собрании

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

Вы также можете отправить целевое уведомление на собрании конкретному участнику собрания. Дополнительные сведения см. в разделе Уведомление о целевом собрании.

Примечание.

Когда вызывается уведомление о собрании, содержимое представляется в виде сообщения чата.
Вы должны вызвать функцию submitTask() для автоматического закрытия после того, как пользователь выполнит действие в веб-представлении. Это требование для отправки приложения. Подробнее в статье Модуль задач Teams SDK.
Если вы хотите, чтобы ваше приложение поддерживало анонимных пользователей, полезная нагрузка начального запроса на вызов должна полагаться на from.id метаданные запросаfrom в объекте, а не на from.aadObjectId метаданные запроса. from.id — это идентификатор пользователя, а from.aadObjectId — идентификатор Microsoft Azure Active Directory (Azure AD) пользователя. Подробнее в разделеиспользование модулей задач на вкладках и создание и отправка модуля задач..

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

В следующей таблице содержится параметр запроса:

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

Примеры

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

Примечание.

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

// Specifies the type of text data in a message attachment.
Activity activity = MessageFactory.Text("This is a meeting signal test");

// Configures the current activity to generate a notification within Teams.
activity.TeamsNotifyUser(true, "https://teams.microsoft.com/l/bubble/APP_ID?url=<url>&height=<height>&width=<width>&title=<title>&completionBotId=BOT_APP_ID");

// Sends a message activity to the sender of the incoming activity. 
await turnContext.SendActivityAsync(activity).ConfigureAwait(false);

// MessageFactory.text(): Specifies the type of text data in a message attachment.
const replyActivity = MessageFactory.text('Hi'); // this could be an adaptive card instead
replyActivity.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’
    }
};

// Sends a message activity to the sender of the incoming activity.
await context.sendActivity(replyActivity);

POST /v3/conversations/{conversationId}/activities

// In-meeting notification response
{
    "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"
}

Имя свойства	Описание
type	Тип действия.
text	Текстовое содержимое сообщения.
summary	Сводный текст сообщения.
channelData.notification.alertInMeeting	Логическое значение, указывающее, должно ли отображаться уведомление пользователю во время собрания.
channelData.notification.externalResourceUrl	Значение URL-адреса внешнего ресурса уведомления.
replyToId	Идентификатор родительского или корневого сообщения потока.
APP_ID	Идентификатор приложения, объявленный в манифесте.
completionBotId	Идентификатор приложения бота.

Коды ответа

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

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

API уведомлений о целевом собрании

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

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

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

Для манифеста приложения версии 1.12 и более поздних

"webApplicationInfo": {
    "id": "<<MICROSOFT-APP-ID>>",
    "resource": "https://RscBasedStoreApp"  },
  "authorization": {
    "permissions": {
      "resourceSpecific": [
            {
                "name": "OnlineMeetingNotification.Send.Chat",
                "type": "Application"
            }
        ]    
    }
}

Для манифеста приложения версии 1.11 и более ранних версий

"webApplicationInfo": {
    "id": "<<MICROSOFT-APP-ID>>",
    "resource": "https://RscBasedStoreApp",
    "applicationPermissions": [
      "OnlineMeetingNotification.Send.Chat"
    ]
}

Примечание.

Полезные данные API разрешают только модуль задачи с URL-адресом.
Форматы идентификатора пользователя aadObjectid и UPN не поддерживаются.

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

Пример

Ниже приведен пример полезных данных запроса для целевого уведомления о собрании.

POST /v1/meetings/{meetingId}/notification

{

  "type": "targetedMeetingNotification",
  "value": {
    "recipients": [ 
"29:1I12M_iy2wTa97T6LbjTh4rJCWrtw2PZ3lxpD3yFv8j2YPnweY2lpCPPAn3RI0PP7rghfHauUz48I1t7ANhj4CA"
     ], 
    "surfaces": [ 
      { 
        "surface": "meetingStage", 
        "contentType": "task", 
        "content": { 
          "value": { 
            "height": "300", 
            "width": "400", 
            "title": "Targeted meeting Notification", 
            "url": "https://somevalidurl.com"           
}
        } 
      } 
    ] 
  },
  "channelData": { // optional if a developer doesn't want to support user attributes.
    "onBehalfOf": [ 
      { 
        "itemid": 0, 
        "mentionType": "person", 
        "mri": "29:1mDOCfGM9825lMHlwP8NjIVMJeQAbN-ojYBT5VzQfPpnst1IFQeYB1QXC8Zupn2RhgfLIW27HmynQk-4bdx_YhA", 
        "displayName": "yunny chung"      } 
    ] 
  }
}

Имя свойства	Описание
`meetingId`	Идентификатор собрания доступен через вызов бота и библиотеку TeamsJS.
`type`	`targetedMeetingNotification`
`recipients`	Список идентификаторов пользователей. Получение идентификаторов пользователей для участников собрания с помощью GET API участника. Получите весь список списка чатов с помощью API получения участников. Пустой или пустой список получателей вернет 400.
`surface`	Тип поверхности. Поддерживаемый тип поверхности — `meetingStage`.
`surfaces`	Список поверхностей, где можно визуализировать уведомления.
`contentType`	Тип содержимого, отображаемого целевым уведомлением о собрании. Поддерживаемое значение — `task`.
`content`	TaskModuleContinueResponse
`content.value.height`	Необязательный; запрошенная высота уведомления.
`content.value.width`	Необязательный; запрошенная ширина уведомления.
`content.value.title`	Необязательный; название уведомления.
`content.value.url`	Необязательный; URL-адрес для отображения в уведомлении. Убедитесь, что URL-адрес является частью манифеста `validDomains` приложения. Если пустая строка или URL-адрес не указан, ничего не будет отображаться в уведомлении о собрании.
`ChannelData.OnBehalfOf`	Необязательный; Это предназначено для поддержки атрибутов пользователя.
`onBehalfOf.itemid`	Описывает идентификацию элемента. Его значение должно быть 0.
`onBehalfOf.mentionType`	`person` Ключевое слово. Описывает упоминание человека.
`onBehalfOf.mri`	Пользователь MRI отображается как отправитель.
`onBehalfOf.displayName`	Необязательный; имя объекта `person`. Используется в качестве резервного варианта, если разрешение имен недоступно.

Примечание.

Если указать недопустимые входные данные, API возвращает код состояния 400.

Код ответа

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

Код ответа	Описание
202	Уведомление успешно отправлено.
207	Уведомления отправляются только нескольким участникам.
400	Сбой проверки полезных данных запроса уведомления о собрании.
401	Недопустимый маркер бота.
403	Бот не может отправлять уведомление.
404	Чат собрания не найден или никто из участников не найден в реестре.

Получить API сведений о собрании

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

API Meeting Details должен иметь регистрацию бота и идентификатор бота. Для получения TurnContext требуется bot SDK. Чтобы использовать API сведений о собрании, вы должны получить различные разрешения RSC в зависимости от области собрания, например закрытого собрания или собрания канала.

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

Чтобы использовать API сведений о собрании, вы должны получить различные разрешения RSC в зависимости от области собрания, например закрытого собрания или собрания канала.

Для манифеста приложения версии 1.12 и более поздних

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

"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
},
"authorization": {
    "permissions": {
        "resourceSpecific": [
            {
                "name": "OnlineMeeting.ReadBasic.Chat",
                "type": "Application"
            }
        ]
    }
}

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

"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
},
"authorization": {
    "permissions": {
        "resourceSpecific": [
            {
                "name": "ChannelMeeting.ReadBasic.Group",
                "type": "Application"
            }
        ]
    }
}

Для манифеста приложения версии 1.11 и более ранних версий

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

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

Используйте следующий пример для настройки свойства webApplicationInfo манифеста приложения для любого собрания канала:

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

Примечание.

Бот может автоматически получать события начала или окончания собрания из всех собраний, созданных во всех каналах, путем добавления ChannelMeeting.ReadBasic.Group в манифест для разрешения RSC.
Для один-на-один вызов organizer является инициатором чата, а для групповых вызовов organizer — инициатором звонка. Для собраний в общедоступных каналах organizer — это пользователь, создавший запись канала.

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

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

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

Пример

// Gets the information for the given meeting id.
MeetingInfo result = await TeamsInfo.GetMeetingInfoAsync(turnContext);

// Sends a message activity to the sender of the incoming activity. 
await turnContext.SendActivityAsync(JsonConvert.SerializeObject(result));


Not available

GET /v1/meetings/{meetingId}

Текст отклика JSON для API сведений о собрании выглядит следующим образом:

Запланированные собрания:


{
   "details":  { 
         "id": "<meeting ID>", 
         "msGraphResourceId": "MSowYmQ0M2I4OS1lN2QxLTQxNzAtOGZhYi00OWJjYjkwOTk1YWYqMCoqMTk6bWVldGluZ19OVEkyT0RjM01qUXROV1UyW", 
         "scheduledStartTime": "2022-04-24T22:00:00Z", 
         "scheduledEndTime": "2022-04-24T23:00:00Z", 
         "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 object ID>",
         "objectId": "<organizer object ID>",
         "tenantId": "<Tenant ID>" 
     }
}

Запланированные собрания каналов:

{ 
    "details": { 
    "msGraphResourceId": "MSoxNmUwYjdiYi05M2Q1LTQzNTItOTllMC0yM2VlNWYyZmZmZTIqMTY2MDc1ODYwNzc0MCoqMTk6a0RtQkpEWFZsYWl0QWhHcVB2SzBtRExZbHVTWnJub01WX1MxeFNkTjQxNDFAdGhyZWFkLnRhY3Yy", 
    "scheduledStartTime": "2022-08-17T18:00:00Z", 
    "scheduledEndTime": "2022-08-17T18:30:00Z", 
    "type": "ChannelScheduled", 
    "id": "MCMxOTprRG1CSkRYVmxhaXRBaEdxUHZLMG1ETFlsdVNacm5vTVZfUzF4U2RONDE0MUB0aHJlYWQudGFjdjIjMTY2MDc1ODYwNzc0MA==", 
    "joinUrl": "https://teams.microsoft.com/l/meetup-join/19%3akDmBJDXVlaitAhGqPvK0mDLYluSZrnoMV_S1xSdN4141%40thread.tacv2/1660758607740?context=%7b%22Tid%22%3a%229f044231-b634-4bdd-b29d-2776e3dbd699%22%2c%22Oid%22%3a%2216e0b7bb-93d5-4352-99e0-23ee5f2fffe2%22%7d", 
    "title": "Test channel meeting"
}, 
"conversation": { 
    "isGroup": true, 
    "conversationType": "channel", 
    "id": "19:kDmBJDXVlaitAhGqPvK0mDLYluSZrnoMV_S1xSdN4141@thread.tacv2;messageid=1660758607740"
}, 
"organizer": { 
    "tenantId": "9f044231-b634-4bdd-b29d-2776e3dbd699", 
    "objectId": "16e0b7bb-93d5-4352-99e0-23ee5f2fffe2", 
    "id": "29:1q4D6ekLXEAALkrqyLXUIcwtVSdXx31bf6vMdfahmkTb9euYVYSsN9x4133pXLV_I2idpVriFe40e19XEZt57bQ", 
    "aadObjectId": "16e0b7bb-93d5-4352-99e0-23ee5f2fffe2"
}
}

1-на-один:

{
    "details": {
         "id": "<meeting ID>",
         "type": "OneToOneCall"
     },
    "conversation": {
         "isGroup": true,
         "conversationType": "groupChat",
         "id": "meeting chat ID"
     },
    "organizer  ": {
         "id": "<organizer user ID>",
         "aadObjectId": "<AAD object ID>",
         "objectId": "<organizer object ID>",
         "tenantId": "<Tenant ID>" 
     }
}

Групповые вызовы:

{
    "details": {
         "id": "<meeting ID>",
         "type": "GroupCall",
         "joinUrl": "https://teams.microsoft.com/l/xx"
     },
    "conversation": {
         "isGroup": true,
         "conversationType": "groupChat",
         "id": "meeting chat ID"
     },
    "organizer": {
         "id": "<organizer user ID>",
         "objectId": "<organizer object ID>",
         "aadObjectId": "<AAD object ID>",
         "tenantId": "<Tenant ID>" 
     }
}

Мгновенные собрания:

{ 
   "details": { 
         "id": "<meeting ID>", 
         "msGraphResourceId": "MSowYmQ0M2I4OS1lN2QxLTQxNzAtOGZhYi00OWJjYjkwOTk1YWYqMCoqMTk6bWVldGluZ19OVEkyT0RjM01qUXROV1UyW", 
         "scheduledStartTime": "2022-04-24T22:00:00Z", 
         "scheduledEndTime": "2022-04-24T23:00:00Z", 
         "joinUrl": "https://teams.microsoft.com/l/xx", 
         "title": "All Hands", 
         "type": "MeetNow" 
     }, 
    "conversation": { 
         "isGroup": true, 
         "conversationType": "groupChat", 
         "id": "meeting chat ID" 
     },
    "organizer": { 
         "id": "<organizer user ID>", 
         "aadObjectId": "<AAD object ID>", 
         "tenantId": "<Tenant ID>" ,
         "objectId": "<organizer object ID>"
     }
}

Имя свойства	Описание
details.id	Идентификатор собрания, закодированный как строка BASE64.
details.msGraphResourceId	MsGraphResourceId, используемый специально для вызовов MS API Graph.
details.scheduledStartTime	Запланированное время начала собрания в формате UTC.
details.scheduledEndTime	Запланированное время окончания собрания в формате UTC.
details.joinUrl	URL-адрес, используемый для присоединения к собранию.
details.title	Название собрания.
details.type	Тип собрания (OneToOneCall, GroupCall, Scheduled, Повторяющийся, MeetNow, ChannelScheduled и ChannelRecurring).
conversation.isGroup	Логическое значение, указывающее, имеет ли беседа более двух участников.
conversation.conversationType	Тип беседы.
conversation.id	Идентификатор чата собрания.
organizer.id	Идентификатор пользователя организатора.
organizer.aadObjectId	Идентификатор объекта Azure Active Directory организатора.
organizer.tenantId	Идентификатор клиента Azure Active Directory организатора.

В случае типа повторяющегося собрания

startDate: указывает дату начала применения шаблона. Значение startDate должно соответствовать значению даты свойства start ресурса события. Первое событие собрания может не произойти в эту дату, если оно не соответствует шаблону.

endDate: указывает дату прекращения применения шаблона. Последнее вхождение собрания может не произойти в эту дату, если оно не соответствует шаблону.

API отправки субтитров в режиме реального времени

API отправки субтитров в режиме реального времени предоставляет конечную точку POST для субтитров перевода в режиме реального времени (CART) Teams, закрытых субтитров с человеческим типом. Текстовое содержимое, отправляемое в эту конечную точку, отображается конечным пользователям в собрании Teams, если для них включены субтитры.

URL-адрес CART

ВЫ можете получить URL-адрес CART для конечной точки POST на странице Параметры собрания в собрании Teams. Подробнее в разделе Субтитры CART на собрании Microsoft Teams. Вам не нужно изменять URL-адрес CART, чтобы использовать субтитры CART.

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

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

Значение	Тип	Обязательный	Описание
meetingId	String	Да	Идентификатор собрания доступен через Bot Invoke и библиотеку TeamsJS. Например, meetingid=%7b%22tId%22%3a%2272f234bf-86f1-41af-91ab-2d7cd0321b47%22%2c%22oId%22%3a%22e071f268-4241-47f8-8cf3-fc6b84437f23%22%2c%22thId%22%3a%2219%3ameeting_NzJiMjNkMGQtYzk3NS00ZDI1LWJjN2QtMDgyODVhZmI3NzJj%40thread.v2%22%2c%22mId%22%3a%220%22%7d
токен	String	Да	Токен авторизации Например, token=04751eac

Пример

https://api.captions.office.microsoft.com/cartcaption?meetingid=%7b%22tId%22%3a%2272f234bf-86f1-41af-91ab-2d7cd0321b47%22%2c%22oId%22%3a%22e071f268-4241-47f8-8cf3-fc6b84437f23%22%2c%22thId%22%3a%2219%3ameeting_NzJiMjNkMGQtYzk3NS00ZDI1LWJjN2QtMDgyODVhZmI3NzJj%40thread.v2%22%2c%22mId%22%3a%220%22%7d&token=gjs44ra

Метод

Ресурс	Метод	Описание
/cartcaption	POST	Обработка субтитров для собрания, которое было начато

Примечание.

Убедитесь, что тип содержимого для всех запросов — обычный текст в кодировке UTF-8. Текст запроса содержит только субтитры.

Пример

POST /cartcaption?meetingid=04751eac-30e6-47d9-9c3f-0b4ebe8e30d9&token=04751eac&lang=en-us HTTP/1.1
Host: api.captions.office.microsoft.com
Content-Type: text/plain
Content-Length: 22
Hello I’m Cortana, welcome to my meeting.

Примечание.

Каждый запрос POST создает новую строку субтитров. Чтобы у конечного пользователя было достаточно времени для чтения содержимого, ограничьте текст каждого POST-запроса до 80–120 символов.

Коды ошибок

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

Код ошибки	Описание
400	Неправильный запрос. В тексте отклика есть дополнительные сведения. Например, представлены не все необходимые параметры.
401	Недостаточно полномочий. Неверный или просроченный токен. Если вы получаете эту ошибку, создайте новый URL-адрес CART в Teams.
404	Собрание не найдено или не началось. Если вы получили эту ошибку, убедитесь, что вы начали собрание и выберите начальные субтитры. После включения субтитров на собрании вы можете начать публиковать субтитры на собрании.
500	Внутренняя ошибка сервера. Для получения дополнительной информации обратитесь в службу поддержки или оставьте отзыв.

Получите API событий собраний Teams в реальном времени

Примечание.

События собраний Teams в режиме реального времени поддерживаются только для запланированных собраний.

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

Вы должны быть знакомы с объектомTurnContext, доступным через Bot SDK. Объект Activity в TurnContext содержит полезные данные с фактическим временем начала и окончания. Для проведения собраний в реальном времени требуется зарегистрированный идентификатор бота на платформе Teams. Бот может автоматически получать событие начала или окончания собрания, добавляя ChannelMeeting.ReadBasic.Group в манифест.

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

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

Для манифеста приложения версии 1.12 и более поздних

"webApplicationInfo": {
    "id": "<bot id>",
    "resource": "https://RscPermission",
    },
"authorization": {
    "permissions": {
        "resourceSpecific": [
            {
                "name": "OnlineMeeting.ReadBasic.Chat",
                "type": "Application"
            }
        ]    
    }
}

Для манифеста приложения версии 1.11 и более ранних версий

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

Пример получения `MeetingStartEndEventvalue`

Бот получает событие через обработчик OnEventActivityAsync. Чтобы десериализовать полезные данные JSON вводится объект модели для получения метаданных для собрания. Метаданные собрания в свойстве value в полезных данных события. Создается объект модели MeetingStartEndEventvalue, переменные элементы которого соответствуют ключам в свойстве value в полезных данных события.

Примечание.

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

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

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

// Invoked when a Teams Meeting Start event activity is received from the connector.
protected override async Task OnTeamsMeetingStartAsync(MeetingStartEventDetails meeting, ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
    // Sends a message activity to the sender of the incoming activity. 
    await turnContext.SendActivityAsync(JsonConvert.SerializeObject(meeting));
}

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

// Invoked when a Teams Meeting End event activity is received from the connector.
protected override async Task OnTeamsMeetingEndAsync(MeetingEndEventDetails meeting, ITurnContext<IEventActivity> turnContext, CancellationToken cancellationToken)
{
    // Sends a message activity to the sender of the incoming activity.
    await turnContext.SendActivityAsync(JsonConvert.SerializeObject(meeting));
}

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

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

{ 
    "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" 
}

Имя свойства	Описание
name	Имя пользователя.
type	Тип действия.
timestamp	Локальная дата и время сообщения, выраженные в формате ISO-8601.
id	Идентификатор действия.
channelId	Канал, с которым связано это действие.
serviceUrl	URL-адрес службы, куда должны отправляться ответы на это действие.
from.id	Идентификатор пользователя, отправившего запрос.
from.aadObjectId	Идентификатор объекта Azure Active Directory пользователя, отправившего запрос.
conversation.isGroup	Логическое значение, указывающее, имеет ли беседа более двух участников.
conversation.tenantId	Идентификатор клиента Azure Active Directory беседы или собрания.
conversation.id	Идентификатор чата собрания.
recipient.id	Идентификатор пользователя, получающего запрос.
recipient.name	Имя пользователя, получающего запрос.
entities.locale	сущность, содержащая метаданные о языковом стандарте.
entities.country	сущность, содержащая метаданные о стране.
entities.type	сущность, которая содержит метаданные о клиенте.
channelData.tenant.id	Идентификатор клиента Azure Active Directory.
channelData.source	Имя источника, из которого запускается или вызывается событие.
channelData.meeting.id	Идентификатор по умолчанию, связанный с собранием.
Значение. MeetingType	Тип собрания.
Значение. Название	Тема собрания.
Значение. Id	Идентификатор по умолчанию, связанный с собранием.
Значение. JoinUrl	URL-адрес присоединения собрания.
Значение. Starttime	Время начала собрания в формате UTC.
Значение. EndTime	Время окончания собрания в формате UTC.
locale	Языковой стандарт сообщения, заданный клиентом.

Получение состояния входящего звука

getIncomingClientAudioState API позволяет приложению получить параметр состояния входящего звука для пользователя собрания. API доступен через библиотеку TeamsJS.

Примечание.

getIncomingClientAudioState API для мобильных устройств доступен в общедоступной предварительной версии для разработчиков.
Согласие на использование конкретного ресурса доступно для манифеста версии 1.12 и более поздних версий, поэтому этот API не работает для манифеста версии 1.11 и более ранних версий.

Манифест

"authorization": {
    "permissions": {
      "resourceSpecific": [
        {
          "name": "OnlineMeetingParticipant.ToggleIncomingAudio.Chat",
          "type": "Delegated"
        }
      ]
    }
  }

Пример

callback = (errcode, result) => {
        if (errcode) {
            // Handle error code
        }
        else {
            // Handle success code
        }
    }
// The getIncomingClientAudioState API shows the current audio state.
microsoftTeams.meeting.getIncomingClientAudioState(this.callback)

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

В следующей таблице содержится параметр запроса:

Значение	Тип	Обязательный	Описание
callback	String	Да	Обратный вызов содержит два параметра `error` и `result`. Ошибка может содержать тип `SdkError` ошибки или `null` при успешном получении звука. Результат может содержать значение true или false при успешном получении звука или значение NULL при сбое выборки звука. Входящий звук отключается, если результат имеет значение true, и отключается, если результат имеет значение false.

Коды ответа

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

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

Переключение входящего звука

toggleIncomingClientAudio API позволяет приложению переключать параметр состояния входящего звука для пользователя собрания с включения звука или наоборот. API доступен через библиотеку TeamsJS.

Примечание.

toggleIncomingClientAudio API для мобильных устройств доступен в общедоступной предварительной версии для разработчиков.
Согласие на использование конкретного ресурса доступно для манифеста версии 1.12 и более поздних версий, поэтому этот API не работает для манифеста версии 1.11 и более ранних версий.

Манифест

"authorization": {
 "permissions": {
  "resourceSpecific": [
   {
    "name": "OnlineMeetingParticipant.ToggleIncomingAudio.Chat",
    "type": "Delegated"
   }
  ]
 }
}

Пример

callback = (error, result) => {
        if (error) {
            // Handle error code
        }
        else {
            // Handle success code
        }
    }
// The toggleIncomingClientAudio API allows an app to toggle the incoming audio state.
microsoftTeams.meeting.toggleIncomingClientAudio(this.callback)

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

В следующей таблице содержится параметр запроса:

Значение	Тип	Обязательный	Описание
callback	String	Да	Обратный вызов содержит два параметра `error` и `result`. Ошибка может содержать тип `SdkError` ошибки или `null` при успешном выполнении переключателя. Результат может содержать значение true или false при успешном выполнении переключателя или значение NULL при сбое переключателя. Входящий звук отключается, если результат имеет значение true, и отключается, если результат имеет значение false.

Код ответа

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

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

Пример кода

Название примера	Описание	.NET	Node.js	Манифест
Расширяемость собраний	Пример расширяемости собраний Teams для передачи маркеров.	Просмотр	Просмотр	Просмотр
Уведомление на собрании	Демонстрирует реализацию уведомлений на собрании с помощью бота.	Просмотр	Просмотр	Просмотр
Боковая панель собрания	Пример расширяемости собраний Teams для взаимодействия с боковой панелью в собрании.	Просмотр	Просмотр
Вкладка "Сведения" в собрании	В этом примере приложения показана функция расширения собраний Teams, с помощью которой пользователь может создать опрос, а участники могут отвечать на опрос на собрании.	Просмотр	Просмотр	Просмотр
Пример событий собрания	В этом примере показаны события собраний Teams в режиме реального времени с помощью бота.	Просмотр	Просмотр	Просмотр
Образец собрания для набора сотрудников	В этом примере приложения показан интерфейс собрания для сценария набора с помощью приложений на собраниях.	Просмотр	Просмотр	Просмотр

API приложений для собраний

Получить API пользовательского контекста

Получить API участника

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

Пример

Коды ответа

Отправить уведомление о собрании

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

Примеры

Коды ответа

API уведомлений о целевом собрании

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

Пример

Код ответа

Получить API сведений о собрании

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

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

Пример

API отправки субтитров в режиме реального времени

URL-адрес CART

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

Пример

Метод

Пример

Коды ошибок

Получите API событий собраний Teams в реальном времени

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

Пример получения MeetingStartEndEventvalue

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

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

Получение состояния входящего звука

Манифест

Пример

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

Коды ответа

Переключение входящего звука

Манифест

Пример

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

Код ответа

Пример кода

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

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

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

Пример получения `MeetingStartEndEventvalue`