Wersja API: 4.x najnowsza 3.x

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.

Rozdział 7 GET POST

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 enforceLayout jest 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.

Najczęściej zadawane pytania

Nie. W przeciwieństwie do większości punktów końcowych API BigBlueButton, getJoinUrl używa uwierzytelniania session-token. Przekazujesz parametr sessionToken zamiast obliczać sumę kontrolną przy użyciu wspólnego sekretu.

Nie. Użytkownik musi wcześniej dołączyć przez standardowy punkt końcowy join i posiadać prawidłowy, aktywny sessionToken. Punkt końcowy nie może być używany do tworzenia początkowych URL-i dołączania.

Obie sesje — oryginalna i nowa — będą istnieć równolegle. Użytkownik pojawia się tylko raz na liście uczestników, ale oba okna przeglądarki lub urządzenia pozostają aktywne.

Podobnie jak inne punkty końcowe oparte na tokenach sesji i używane wewnętrznie przez klienta (stuns, learningDashboard), getJoinUrl zwraca JSON. Punkty końcowe API chronione sumą kontrolną zwracają XML.

Punkt końcowy getJoinUrl został wprowadzony w BigBlueButton 3.0. Nie jest dostępny we wcześniejszych wersjach.

Niekoniecznie. Konfigurowalna lista blokad może ograniczać niektóre klucze userdata dla użytkowników niebędących moderatorami. Jeśli lista blokad jest ustawiona na "all", żadne parametry userdata nie są przekazywane dla widzów. Moderatorzy omijają listę blokad z wyjątkiem breakout rooms.