Вы просматриваете документацию API для BigBlueButton 3.x. Текущая версия — BigBlueButton 4.x. Планируете обновление? В руководстве по миграции перечислены все изменения, которые необходимо внести в ваши вызовы API.
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, чтобы бесшовно перенести сессию на новое устройство. Это позволяет избежать сохранения устаревшей сессии на старом устройстве, которая может вызывать путаницу в списке участников.