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

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

Глава 7 GET POST

getJoinUrl – Сгенерировать URL для подключения

Конечная точка getJoinUrl генерирует новый URL входа для пользователя, который уже присоединился ко встрече. Это позволяет одному и тому же пользователю открывать дополнительные сессии — например, на втором экране или после смены устройства — без повторной аутентификации через стандартный поток join. BBB 3.0+

Конечная точка

GET/POST https://api-guide.bbbserver.com/bigbluebutton/api/getJoinUrl?<parameters>

Эта конечная точка использует аутентификацию session-token вместо стандартного механизма контрольной суммы shared-secret. Пользователь уже должен был присоединиться через конечную точку join и иметь действительный sessionToken.

В отличие от защищённых контрольной суммой конечных точек API BigBlueButton, которые возвращают XML, эта конечная точка возвращает JSON.

Обязательные параметры

Параметр Тип Обязательно По умолчанию Описание
sessionToken String Да — sessionToken пользователя, для которого нужно сгенерировать новый URL входа.

Необязательные параметры

Параметр Тип Обязательно По умолчанию Описание
replaceSession Boolean Нет false Если установлено значение true, исходная сессия становится недействительной и заменяется новой (перенос сессии).
sessionName String Нет — Описательное имя для новой сессии.
enforceLayout String Нет — Переопределить макет для новой сессии.
userdata-* String Нет — Пользовательские данные для новой сессии. Ключи должны иметь префикс userdata-.

Сценарии использования

  • Гибридные сценарии — модератор использует один экран для презентации, а второй — для просмотра участника.
  • Переключение устройств — пользователь переходит с настольного компьютера на планшет во время встречи.
  • Многомониторные конфигурации — конференц-зал с несколькими дисплеями, показывающими разные макеты.

Поведение

Новая сессия использует ту же пользовательскую идентичность, что и исходная сессия. Пользователь отображается в списке участников только один раз.

Без replaceSession обе сессии существуют параллельно.

С replaceSession=true исходная сессия становится недействительной, и пользователь бесшовно переводится в новую сессию.

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

GET https://api-guide.bbbserver.com/bigbluebutton/api/getJoinUrl?sessionToken=replace-with-session-token&sessionName=SecondScreen&enforceLayout=PRESENTATION_FOCUS

Пример ответа (успех)

{
  "response": {
    "returncode": "SUCCESS",
    "message": "Join URL provided successfully.",
    "url": "https://api-guide.bbbserver.com/bigbluebutton/api/join?...&checksum=replace-with-checksum"
  }
}

Ответы с ошибками

Если запрос завершается неудачно, конечная точка возвращает объект JSON с описательным сообщением об ошибке:

{
  "response": {
    "returncode": "FAILED",
    "message": "<error message>"
  }
}
Сообщение Значение
You must provide a session token Отсутствует параметр sessionToken.
Invalid session token sessionToken недействителен или срок его действия истёк.
Invalid Session Запрос не содержит cookie HTTP-сеанса, созданный с помощью join, а конференция не разрешает запросы без сеанса (allowRequestsWithoutSession, по умолчанию false).
Access denied Пользователь не найден или не имеет прав доступа.
Meeting not found Встреча не существует или больше не выполняется.

В BigBlueButton 3.0 только Meeting not found возвращается как ошибка JSON. Для остальных перечисленных выше ошибок конечная точка не отправляет ответ JSON.

Список блокировки Userdata

При использовании параметров userdata-* с getJoinUrl настраиваемый список блокировки (getJoinUrlUserdataBlocklist) ограничивает определённые ключи userdata для пользователей, не являющихся модераторами:

  • Если список блокировки содержит значение "all", для зрителей блокируются все параметры userdata.
  • Модераторы обходят список блокировки, кроме случая breakout rooms.
  • Параметр enforceLayout всегда разрешён, независимо от списка блокировки.

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

Для сценариев переключения устройств установите replaceSession=true, чтобы бесшовно перенести сессию на новое устройство. Это позволяет избежать сохранения устаревшей сессии на старом устройстве, которая может вызывать путаницу в списке участников.

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

Нет. В отличие от большинства конечных точек API BigBlueButton, getJoinUrl использует аутентификацию session-token. Вы передаёте параметр sessionToken вместо вычисления контрольной суммы с общим секретом.

Нет. Пользователь уже должен присоединиться через стандартную конечную точку join и иметь действительный активный sessionToken. Эту конечную точку нельзя использовать для создания первоначальных URL входа.

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

Как и другие конечные точки на основе токена сеанса, используемые внутри клиента (stuns, learningDashboard), getJoinUrl возвращает JSON. Защищённые контрольной суммой конечные точки API возвращают XML.

Конечная точка getJoinUrl была добавлена в BigBlueButton 3.0. В более ранних версиях она недоступна.

Не обязательно. Настраиваемый список блокировки может ограничивать определённые ключи userdata для пользователей, не являющихся модераторами. Если список блокировки установлен в "all", для зрителей не передаются никакие параметры userdata. Модераторы обходят список блокировки, кроме случая breakout rooms.
Руководство по API BigBlueButton