Версія 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