Przeglądasz dokumentację API dla BigBlueButton 3.x. Aktualna wersja to BigBlueButton 4.x. Planujesz aktualizację? Przewodnik migracji zawiera wszystkie zmiany wymagane w wywołaniach API.
getJoinUrl – Wygeneruj URL do dołączenia
Punkt końcowy getJoinUrl generuje nowy URL dołączenia dla użytkownika, który już dołączył do spotkania. Pozwala to temu samemu użytkownikowi otwierać dodatkowe sesje — na przykład na drugim ekranie lub po zmianie urządzenia — bez ponownego uwierzytelniania przez standardowy przepływ join. BBB 3.0+
Punkt końcowy
GET/POST https://api-guide.bbbserver.com/bigbluebutton/api/getJoinUrl?<parameters> Ten punkt końcowy używa session-tokensuwierzytelniania zamiast standardowego mechanizmu sumy kontrolnej shared-secret. Użytkownik musi wcześniej dołączyć przez punkt końcowy join i posiadać prawidłowy sessionToken.
W przeciwieństwie do punktów końcowych API BigBlueButton chronionych sumą kontrolną, które zwracają XML, ten punkt końcowy zwraca JSON.
Wymagane parametry
| Parametr | Typ | Wymagane | Domyślnie | Opis |
|---|---|---|---|---|
sessionToken | String | Tak | — | sessionToken użytkownika, dla którego ma zostać wygenerowany nowy URL dołączenia. |
Parametry opcjonalne
| Parametr | Typ | Wymagane | Domyślnie | Opis |
|---|---|---|---|---|
replaceSession | Boolean | Nie | false | Gdy ustawione na true, oryginalna sesja zostaje unieważniona i zastąpiona nową (transfer sesji). |
sessionName | String | Nie | — | Opisowa nazwa nowej sesji. |
enforceLayout | String | Nie | — | Nadpisz układ dla nowej sesji. |
userdata-* | String | Nie | — | Niestandardowe dane użytkownika dla nowej sesji. Klucze muszą mieć prefiks userdata-. |
Zastosowania
- Scenariusze hybrydowe — moderator używa jednego ekranu do prezentacji, a drugiego do widoku uczestników.
- Przełączanie urządzeń — użytkownik przechodzi z komputera stacjonarnego na tablet podczas spotkania.
- Konfiguracje wieloekranowe — sala konferencyjna z wieloma wyświetlaczami pokazującymi różne układy.
Zachowanie
Nowa sesja współdzieli tożsamość użytkownika z oryginalną sesją. Użytkownik pojawia się tylko raz na liście uczestników.
Bez replaceSession obie sesje istnieją równolegle.
Z replaceSession=true oryginalna sesja zostaje unieważniona, a użytkownik jest płynnie przenoszony do nowej sesji.
Przykładowe żądanie
GET https://api-guide.bbbserver.com/bigbluebutton/api/getJoinUrl?sessionToken=replace-with-session-token&sessionName=SecondScreen&enforceLayout=PRESENTATION_FOCUS Przykładowa odpowiedź (sukces)
{
"response": {
"returncode": "SUCCESS",
"message": "Join URL provided successfully.",
"url": "https://api-guide.bbbserver.com/bigbluebutton/api/join?...&checksum=replace-with-checksum"
}
} Odpowiedzi błędów
Gdy żądanie się nie powiedzie, punkt końcowy zwraca obiekt JSON z opisowym komunikatem o błędzie:
{
"response": {
"returncode": "FAILED",
"message": "<error message>"
}
} | Komunikat | Znaczenie |
|---|---|
You must provide a session token | Brakuje parametru sessionToken. |
Invalid session token | sessionToken jest nieprawidłowy lub wygasł. |
Invalid Session | Żądanie nie zawiera pliku cookie sesji HTTP utworzonego przez join, a spotkanie nie zezwala na żądania bez sesji (allowRequestsWithoutSession, domyślnie false). |
Access denied | Nie znaleziono użytkownika lub nie ma on uprawnień. |
Meeting not found | Spotkanie nie istnieje lub nie jest już uruchomione. |
W BigBlueButton 3.0 tylko Meeting not found jest zwracany jako błąd JSON. W przypadku pozostałych błędów wymienionych powyżej punkt końcowy nie wysyła odpowiedzi JSON.
Lista blokad Userdata
Przy używaniu parametrów userdata-* z getJoinUrl konfigurowalna lista blokad (getJoinUrlUserdataBlocklist) ogranicza niektóre klucze userdata dla użytkowników niebędących moderatorami:
- Jeśli lista blokad zawiera wartość
"all", wszystkie parametry userdata są blokowane dla widzów. - Moderatorzy omijają listę blokad, z wyjątkiem breakout rooms.
- Parametr
enforceLayoutjest zawsze dozwolony, niezależnie od listy blokowanych.
Punkt końcowy jest dostępny tylko wtedy, gdy użytkownik posiada już prawidłowy sessionToken — to znaczy, że musi wcześniej dołączyć do spotkania przez standardowy punkt końcowy join. Wygasłe tokeny są odrzucane.
W przypadku scenariuszy przełączania urządzeń ustaw replaceSession=true, aby płynnie przenieść sesję na nowe urządzenie. Pozwala to uniknąć pozostawienia nieaktualnej sesji na starym urządzeniu, co mogłoby powodować zamieszanie na liście uczestników.