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.

To jedyny punkt końcowy API BigBlueButton, który zwraca JSON zamiast XML.

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-* ↗ undocumented 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>",
        "sessionToken": "replace-with-session-token"
  }
}
Komunikat Znaczenie
Invalid Session sessionToken jest nieprawidłowy lub wygasł.
Access denied Nie znaleziono użytkownika lub nie ma on uprawnień.
Meeting not found Spotkanie nie istnieje lub nie jest już uruchomione.

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.

Uwagi dla użytkowników bbbserver.de

Punkt końcowy getJoinUrl jest dostępny na wszystkich instancjach bbbserver.de działających na BigBlueButton 3.0 lub nowszym. Jeśli twoja integracja musi obsługiwać scenariusze wieloekranowe lub przełączanie urządzeń, ten punkt końcowy zapewnia przejrzysty sposób generowania dodatkowych URL-i dołączania bez konieczności wykonywania drugiego wywołania join z poświadczeniami moderatora.

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.

To decyzja projektowa podjęta przez deweloperów BigBlueButton przy wprowadzaniu tego punktu końcowego w wersji 3.0. To jedyny punkt końcowy API, który zwraca JSON. Wszystkie pozostałe punkty końcowe nadal 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.