Глава 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, которая возвращает JSON вместо XML.

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

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

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

Параметр Тип Обязательно По умолчанию Описание
replaceSession Boolean Нет false Если установлено значение true, исходная сессия становится недействительной и заменяется новой (перенос сессии).
sessionName String Нет — Описательное имя для новой сессии.
enforceLayout String Нет — Переопределить макет для новой сессии.
userdata-* ↗ undocumented 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>",
        "sessionToken": "replace-with-session-token"
  }
}
Сообщение Значение
Invalid Session sessionToken недействителен или срок его действия истёк.
Access denied Пользователь не найден или не имеет прав доступа.
Meeting not found Встреча не существует или больше не выполняется.

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

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

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

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

Примечания для пользователей bbbserver.de

Конечная точка getJoinUrl доступна на всех экземплярах bbbserver.de, работающих на BigBlueButton 3.0 или новее. Если вашей интеграции нужна поддержка сценариев с несколькими экранами или сменой устройств, эта конечная точка предоставляет удобный способ генерировать дополнительные URL входа без необходимости второго вызова join с учётными данными модератора.

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

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

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

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

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

Это архитектурное решение, принятое разработчиками BigBlueButton при добавлении этой конечной точки в версии 3.0. Это единственная конечная точка API, которая возвращает JSON. Все остальные конечные точки продолжают возвращать XML.

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

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