Версия API: 4.x последняя 3.x

Вы просматриваете документацию API для BigBlueButton 3.x. Текущая версия — BigBlueButton 4.x. Планируете обновление? В руководстве по миграции перечислены все изменения, которые необходимо внести в ваши вызовы API.

Глава 1

Obzor API

API BigBlueButton — это интерфейс на основе HTTP, который позволяет внешним приложениям — таким как системы управления обучением, веб-порталы и пользовательские интеграции — программно создавать, управлять и отслеживать встречи. Все API-вызовы защищены с помощью механизма checksum, основанного на shared secret.

Как работает API

API BBB использует простую модель запрос-ответ. Вы отправляете запрос HTTPS к определённой конечной точке на вашем сервере BigBlueButton, а сервер отвечает документом XML, указывающим на успех или неудачу.

  • Протокол: HTTPS (GET или POST)
  • Базовый URL: https://<server>/bigbluebutton/api/<endpoint>?<parameters>&checksum=<hash>
  • Формат ответа: XML (за несколькими исключениями, которые возвращают JSON)
  • Аутентификация: Shared-secret-на основе checksum (без OAuth, без API-ключа)

Категории endpoint

Endpoint API организованы по следующим категориям:

Категория Endpoint Описание
Администрация create, join, end Создание, присоединение и завершение встреч
Monitoring isMeetingRunning, getMeetings, getMeetingInfo Мониторинг активных встреч
Записи getRecordings, publishRecordings, deleteRecordings, updateRecordings, getRecordingTextTracks, putRecordingTextTrack Управление записями встреч
Webhooks hooks/create, hooks/list, hooks/destroy Уведомления о событиях в реальном времени
Сообщения sendChatMessage Отправка сообщений чата BBB 3.0+
Сессия getJoinUrl Управление сессиями BBB 3.0+

Методы HTTP

Большинство конечных точек принимают как запросы GET, так и POST. При использовании POST обратите внимание, что checksum вычисляется по URL query string, а не по телу запроса. Тело POST может содержать дополнительные данные, такие как XML презентации или переопределения настроек клиента.

Даже при отправке запроса POST, checksum должен вычисляться из параметров query string в URL. Содержимое тела не включается в вычисление checksum.

Формат ответа

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

<response>
  <returncode>SUCCESS</returncode>
  <!-- or -->
  <returncode>FAILED</returncode>
  <messageKey>errorKey</messageKey>
  <message>Human-readable error message</message>
</response>
Поле Описание
returncode Всегда SUCCESS или FAILED
messageKey Машиночитаемый код сообщения (присутствует при ошибках и предупреждениях, а также в некоторых успешных ответах, таких как noMeetings или sentEndMeetingRequest)
message Человекочитаемое описание ошибки или предупреждения

Версионирование API

API BigBlueButton не использует традиционное версионирование на основе URL (без путей /v1/, /v2/). Вместо этого новые параметры добавляются с сохранением обратной совместимости, а устаревшие параметры помечаются соответствующим образом, но не удаляются сразу.

Версия BBB Заметные изменения API
2.2 настройки Lock, allowModsToUnmuteUsers
2.4 meetingLayout, allowModsToEjectCameras, role (join), Панель обучения
2.5 disabledFeatures, поддержка SHA-384/SHA-512, webhook eventID фильтр
2.6 notifyRecordingIsOn, presentationUploadExternalUrl, Постраничная выдача записей, темный режим
2.7 preUploadedPresentation (один URL)
3.0 sendChatMessage, getJoinUrl, pluginManifests, clientSettingsOverride

Недокументированные конечные точки

Следующие конечные точки существуют в исходном коде BigBlueButton, но не входят в API для интеграций. Официальная документация описывает stuns, signOut и learningDashboard только как внутренние конечные точки клиента HTML5, использующие для аутентификации sessionToken вместо контрольной суммы; getSessions вообще не описана в документации. Они могут изменяться без предварительного уведомления.

Конечная точка Метод Описание Статус
/api/stuns GET POST Возвращает конфигурацию сервера STUN/TURN для соединений WebRTC Internal
/api/signOut GET POST Завершить сеанс / выйти пользователю Internal
/api/getSessions GET POST Получить информацию о сеансе Undocumented
/api/learningDashboard GET POST Получить данные аналитики обучения Internal

Мутации GraphQL (действия во время встречи)

Начиная с BBB 3.0, большинство действий в реальном времени внутри встречи обрабатываются через мутации GraphQL по WebSocket. Они используются внутренне HTML5-клиентом BBB и не являются частью классического API REST.

Категория Количество Примеры
Чат 11 chatSendMessage, chatDeleteMessage, chatEditMessage
Управление пользователями 28 userSetMuted, userSetRole, userEjectFromMeeting
Презентация 10 presentationSetCurrent, presentationSetPage
Управление встречей 8 meetingEnd, meetingRecordingSetStatus
Сессионные комнаты 7 breakoutRoomCreate, breakoutRoomEndAll
Опросы 5 pollCreate, pollSubmitUserVote, pollPublishResult
Таймер 8 timerStart, timerStop, timerReset
Плагины 8 pluginDataChannelPushEntry, pluginPersistEvent

Слой GraphQL предназначен для внутреннего использования клиентом и не предоставляет стабильный публичный API. Мутации и их параметры могут изменяться между версиями BBB без предупреждения.

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

Прежде чем начать использовать API BigBlueButton, убедитесь, что у вас есть следующее:

Работающий сервер BigBlueButton (рекомендуется версия 3.0)

Общий секрет (также называемый «security salt»), настроенный в /etc/bigbluebutton/bbb-web.properties

Доступ HTTPS к серверу

Серверное приложение, которое генерирует API-вызовы — shared secret никогда не должен раскрываться на стороне клиента

Никогда не раскрывайте shared secret в клиентском коде (JavaScript, мобильные приложения). Все API-вызовы должны генерироваться на стороне сервера, чтобы предотвратить несанкционированный доступ к вашему серверу BigBlueButton.

Если вы используете bbbserver.de, обратитесь к специальной главе bbbserver.de IntegrationAPI для настройки панели управления, совместимости плагинов и отличий от стандартного API.

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

API использует механизм shared-secret на основе checksum. Каждый запрос должен включать параметр checksum, который вычисляется путём хеширования имени API-вызова, query string и shared secret. Аутентификация через OAuth или API-ключ отсутствует.

Стандартный формат ответа — XML. Несколько отдельных конечных точек могут возвращать JSON, но подавляющее большинство API-вызовов возвращают документы XML с полем returncode, указывающим SUCCESS или FAILED.

Нет, API BigBlueButton не использует версионирование на основе URL. Новые параметры добавляются с сохранением обратной совместимости, а устаревшие параметры помечаются, но не удаляются сразу. Вам всегда следует проверять журнал изменений для вашей версии BBB.

Нет. Слой GraphQL предназначен для внутреннего использования HTML5-клиентом BBB. Он не предоставляет стабильный публичный API, и мутации могут изменяться между версиями без предупреждения. Для всех внешних интеграций используйте API REST.

BigBlueButton 3.0 по умолчанию поддерживает SHA-1, SHA-256, SHA-384 и SHA-512 для расчёта checksum (настраивается через supportedChecksumAlgorithms). SHA-384 и SHA-512 были добавлены в BigBlueButton 2.5.8; более ранние версии поддерживают только SHA-1 и SHA-256. Из соображений безопасности рекомендуется использовать SHA-256 или более стойкий алгоритм.
Руководство по API BigBlueButton