Глава 18

Мета-параметры и callback-адреса

Мета-параметры — это произвольно задаваемые пары ключ-значение, которые вы передаёте при создании встречи. Они позволяют прикреплять пользовательские метаданные, запускать автоматические обратные вызовы при определённых событиях, управлять анонимизацией записей и документировать происхождение встречи для интеграций LMS.

Как работают мета-параметры

Мета-параметры передаются в API-вызове create с использованием соглашения об именовании meta_=. Вы можете прикрепить к одной встрече любое количество мета-параметров. 

create?meetingID=replace-with-meeting-id&meta_coursename=Computer+Science+101&meta_instructor=Prof.+Mueller&checksum=replace-with-checksum
  • Мета-параметры возвращаются в ответах getMeetingInfo и getRecordings.
  • Записи можно фильтровать по мета-значениям с помощью getRecordings?meta_=.
  • Метаданные записи можно обновить позже через updateRecordings.

Callback-мета-параметры

Некоторые мета-параметры имеют особое значение и запускают обратные вызовы HTTP при наступлении определённых событий. Это позволяет вашему приложению автоматически реагировать на события жизненного цикла встречи.

meta_endCallbackUrl

Отправляет запрос HTTP GET на указанный URL, когда встреча завершается. 

meta_endCallbackUrl=https://api-guide.bbbserver.com/callbacks/meeting-ended
Свойство Значение
Метод HTTP GET
Триггер Когда встреча заканчивается
Параметры Callback meetingID — идентификатор встречи
recordingmarks — true если запись содержит метки, в противном случае false

Пример запроса обратного вызова: 

GET https://api-guide.bbbserver.com/callbacks/meeting-ended?meetingID=replace-with-meeting-id&recordingmarks=true

meta_bbb-recording-ready-url

Отправляет запрос HTTP POST, когда запись была полностью обработана и опубликована. 

meta_bbb-recording-ready-url=https://api-guide.bbbserver.com/callbacks/recording-ready
Свойство Значение
Метод HTTP POST
Триггер Когда запись полностью обработана и опубликована
Безопасность Параметры подписаны с помощью JWT (JSON Web Token)
Тело POST Содержит подписанные данные с информацией о записи

Не путайте этот обратный вызов с endCallbackUrl. Обработка записи может занять значительное время после завершения встречи. Обратный вызов recording-ready срабатывает только после завершения обработки.

meta_analytics-callback-url

Отправляет запрос HTTP POST с агрегированными аналитическими данными после завершения встречи. 

meta_analytics-callback-url=https://api-guide.bbbserver.com/callbacks/analytics
Свойство Значение
Метод HTTP POST
Триггер После завершения встречи (post-events hook)
Аутентификация Токен JWT, отправляемый в заголовке Authorization: Bearer (HS512, подписан общим секретом BBB, действителен 24 часа)
Формат тела Объект JSON, содержащий version, meeting_id, internal_meeting_id, data
Содержимое данных Продолжительность участия, статистика активности, использование чата и другие агрегированные события встречи

URL обратного вызова аналитики берётся из кодовой базы BigBlueButton и не полностью документирован в официальной документации API. Точная схема объекта аналитических данных не стандартизирована и может меняться между версиями. undocumented

Обратите внимание на различие в доставке JWT: analytics-callback-url отправляет JWT в заголовке HTTP Authorization, тогда как bbb-recording-ready-url включает JWT непосредственно в тело POST.

Параметры анонимизации записи

Эти метапараметры определяют, будут ли имена отправителей чата анонимизированы в обработанных записях. Они полезны для соблюдения требований конфиденциальности и защиты данных.

Параметр Тип По умолчанию Описание
meta_bbb-anonymize-chat Boolean false Анонимизирует отправителей сообщений чата в обработанных записях. Влияет только на сообщения зрителей (не модераторов). Имена модераторов остаются видимыми.
meta_bbb-anonymize-chat-moderators Boolean false Дополнительно анонимизирует отправителей сообщений модераторов в чате записей. Обычно также требуется установить meta_bbb-anonymize-chat=true.
create?meetingID=replace-with-meeting-id&meta_bbb-anonymize-chat=true&meta_bbb-anonymize-chat-moderators=true&checksum=replace-with-checksum

Параметры анонимизации лишь кратко упоминаются в официальной документации API. Их поведение выведено из исходного кода BigBlueButton. undocumented

Параметры интеграции LMS

Многие плагины LMS автоматически устанавливают мета-параметры, чтобы документировать происхождение встречи. Они носят информационный характер и не влияют на поведение встречи, но полезны для аудита и отчётности.

Параметр Пример Описание
meta_bbb-origin greenlight, moodle Исходное приложение, создавшее встречу.
meta_bbb-origin-version v3.1.0 Версия исходного приложения.
meta_bbb-origin-server-name api-guide.bbbserver.com Имя хоста исходного приложения.
meta_bbb-context Course: Computer Science Контекстная информация, например название курса.
meta_bbb-context-id course-42 Идентификатор контекста для программного использования.

Рекомендации по использованию пользовательских метапараметров

  • Используйте описательные имена ключей (например, meta_department, meta_project), которые ясно указывают назначение значения.
  • Кодируйте в URL значения, содержащие специальные символы, пробелы или не-ASCII-символы.
  • Используйте мета-параметры для интеграции с внешними системами, такими как CRMs, учебные платформы или аналитические панели.
  • Обновляйте метаданные записи постфактум с помощью эндпоинта updateRecordings, чтобы добавить или исправить метаданные.

Комбинируйте метапараметры с фильтрацией getRecordings, чтобы создавать мощные процессы поиска и категоризации ваших записей. Например, фильтруйте по meta_department=engineering, чтобы получать только записи встреч инженерного отдела.

Часто задаваемые вопросы

Жёсткого ограничения на количество метапараметров нет. Однако, поскольку они передаются как параметры URL-запроса, следует оставаться в пределах практических ограничений длины URL (обычно от 2 000 до 8 000 символов в зависимости от конфигурации веб-сервера).

Мета-параметры, заданные во время вызова create, нельзя изменить, пока встреча идёт. Однако метаданные записи можно обновить после обработки с помощью эндпоинта updateRecordings.

endCallbackUrl срабатывает сразу после завершения встречи, используя простой запрос GET. bbb-recording-ready-url срабатывает значительно позже — только после полной обработки и публикации записи — и использует подписанный JWT запрос POST.

Детали подписи JWT не полностью указаны в официальной документации. На основе исходного кода BigBlueButton, JWT подписывается с использованием общего секрета сервера. Точные claims и алгоритм следует проверить для вашей конкретной версии BigBlueButton.

Большинство мета-параметров носят исключительно информационный характер и не изменяют работу встречи. Исключения составляют URL обратных вызовов, которые отправляют запросы HTTP при событиях, и параметры анонимизации, влияющие на обработку записей.

Да. Ключи мета-параметров рассматриваются как строки с учётом регистра. Например, meta_Department и meta_department будут сохранены как два отдельных параметра. Используйте единообразный регистр в вашей интеграции, чтобы избежать дубликатов.
Руководство по API BigBlueButton