Wersja API: 4.x najnowsza 3.x
Rozdział 2

Migracja z wersji 3.x do 4.x

BigBlueButton 4.0 usuwa szereg przestarzałych parametrów i wartości układu, zmienia kilka wartości domyślnych i wprowadza nowe klucze błędów. Ten przewodnik zawiera wszystko, co należy sprawdzić w wywołaniach API, gdy Twoja integracja komunikuje się z serwerem BigBlueButton 4.x zamiast z serwerem BigBlueButton 3.x.

Zakres: Ten przewodnik obejmuje zmiany w wywołaniach API wykonywanych przez Twoją aplikację (create, join, insertDocument, …). Nie obejmuje aktualizacji ani migracji samych serwerów konferencyjnych.

Najpierw dobra wiadomość: punkty końcowe, obliczanie checksum, format odpowiedzi XML i wszystkie punkty końcowe dotyczące nagrań pozostają bez zmian. Większość integracji wymaga jedynie dostosowania kilku parametrów. Nieznane lub usunięte parametry są ignorowane bez zgłaszania błędu – usunięty parametr nie powoduje więc błędu, ale też nie ma już żadnego wpływu na działanie.

Przegląd wszystkich zmian

Punkt końcowy Zmiana Wpływ Wymagane działanie
create Usunięto lockSettingsDisableNote (liczba pojedyncza) Zmiana niezgodna wstecznie Użyj lockSettingsDisableNotes.
create Domyślny most multimedialny to teraz livekit Zmiana zachowania Sprawdź dołączanie telefoniczne przy włączonej poczekalni dla gości; w razie potrzeby ustaw audioBridge.
create sharedNotesEditor jest ignorowany – usunięto Etherpad Zmiana zachowania Usuń parametr; wspólne notatki zawsze korzystają z BlockNote.
create meetingEndedURL otrzymuje meetingID i recordingmarks (4.0.1) Zmiana zachowania Upewnij się, że procedura obsługi wywołania zwrotnego akceptuje dodatkowe parametry.
create Pokoje podgrup utworzone w kliencie dziedziczą meetingKeepEvents ze spotkania nadrzędnego Zmiana zachowania Zwykle żadne.
create Wartość domyślna meetingLayout to teraz UNIFIED_LAYOUT Zmiana zachowania Zwykle żadne; przekaż jawnie meetingLayout, aby użyć jednego ze specjalnych układów.
create Nowe klucze błędów malformedXml i invalidPresentationUrl; spotkanie nie zostaje utworzone Zmiana zachowania Sprawdź obsługę błędów dla dokumentów przesłanych z wyprzedzeniem.
create Usunięto layouts i captions z disabledFeatures Bez wpływu na działanie Usuń te wartości ze swojej listy.
create Usunięto copyright, logoutTimer, webVoice Bez wpływu na działanie Usuń te parametry (wcześniej nie miały wpływu na działanie).
create, insertDocument Maks. 10 dokumentów na wywołanie (4.0.1) Zmiana zachowania Obsłuż documentsDropped lub podziel przesyłanie na mniejsze partie.
create, join Usunięto układy CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS i VIDEO_FOCUS Zmiana zachowania Użyj UNIFIED_LAYOUT lub jednego ze specjalnych układów.
create, join Nowe parametry lockSettingsPresenterPolicy, requireUserConsentBeforeUnmuting, disabledFeatures (+3), userdata-bbb_hide_sidebar_navigation Nowość Opcjonalne.
end Kończy również sesje w pokojach podgrup utworzonych za pośrednictwem API Zmiana zachowania Usuń obejścia, które osobno kończyły sesje w pokojach isBreakout.
insertDocument Limit częstotliwości żądań i nowe klucze błędów (4.0.1) Zmiana zachowania Obsłuż rateLimitExceeded i nowe wartości messageKey.
join Ograniczenie fullName do 255 znaków Zmiana niezgodna wstecznie Skracaj nazwy; obsłuż fullNameTooLong.
join Usunięto webVoiceConf, userdata-bbb_change_layout, userdata-enable-user-reaction i userdata-bbb_parent_room_moderator Zmiana zachowania Zastąp zgodnie z poniższym opisem.
sendChatMessage Nowe klucze błędów dotyczące brakujących parametrów Zmiana zachowania Obsłuż missingParamMeetingID i missingParamMessage.
/api/rest/clientSettings Usunięto punkt końcowy Zmiana niezgodna wstecznie Nie wywołuj go już; użyj clientSettingsOverride, aby dostosować ustawienia klienta.

Zmiany w create

Usunięte parametry

Parametr (3.x) Status w wersji 4.x Zastąpienie
lockSettingsDisableNote Usunięto (był przestarzałym aliasem). Zmiana niezgodna wstecznie lockSettingsDisableNotes
sharedNotesEditor Ignorowany. Etherpad został usunięty, każde spotkanie korzysta z BlockNote. Brak. sharedNotesInitialContentJsonUrl, sharedNotesInitialContentMarkdown i sharedNotesInitialContentMarkdownUrl działają teraz w każdym spotkaniu — już nie tylko z sharedNotesEditor=blockNote.
copyright Usunięto. Wartość nigdy nie była przekazywana do klienta. Ustawienie klienta public.app.copyright za pośrednictwem clientSettingsOverride (wymaga allowOverrideClientSettingsOnCreateCall=true na serwerze) lub clientSettingsOverrideJsonUrl.
logoutTimer Usunięto. Wartość nigdy nie była przekazywana do klienta. —
webVoice Usunięto. Nieaktualne od czasu wycofania klienta Flash w BBB 2.3. voiceBridge
Przed (3.x)
create?meetingID=demo&name=Demo
  &lockSettingsDisableNote=true
  &sharedNotesEditor=blockNote
  &copyright=Example+Inc.
  &meetingLayout=SMART_LAYOUT
Po (4.x)
create?meetingID=demo&name=Demo
  &lockSettingsDisableNotes=true
  &clientSettingsOverrideJsonUrl=https%3A%2F%2F
    example.com%2Fclient-settings.json
  &meetingLayout=UNIFIED_LAYOUT

Układy

Wybór układu w kliencie został zastąpiony jednym układem adaptacyjnym. UNIFIED_LAYOUT jest nową wartością domyślną meetingLayout, a klasyczne układy nie są już akceptowane przez meetingLayout (w create), enforceLayout (w join i getJoinUrl) oraz userdata-bbb_default_layout:

Usunięte wartości układu nie powodują błędu: klient ignoruje je i korzysta z następnego źródła układu (np. układu spotkania lub układu domyślnego).

Wartość w wersji 3.x Status w wersji 4.x Zalecana wartość w wersji 4.x
CUSTOM_LAYOUT (domyślna w wersji 3.x) Usunięto UNIFIED_LAYOUT
SMART_LAYOUT Usunięto UNIFIED_LAYOUT
PRESENTATION_FOCUS Usunięto UNIFIED_LAYOUT; w przypadku ekranu wyświetlającego wyłącznie prezentację (np. projektora) PRESENTATION_ONLY
VIDEO_FOCUS Usunięto UNIFIED_LAYOUT; w przypadku ściany widoków z kamer CAMERAS_ONLY
UNIFIED_LAYOUT, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY Bez zmian —

CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY i MEDIA_ONLY to specjalne układy do zastosowań hybrydowych lub kiosków — ukrywają znaczną część interfejsu użytkownika. Nie używaj ich jako zamienników 1:1 usuniętych układów podczas zwykłych spotkań.

Mostki multimedialne

audioBridge, cameraBridge i screenShareBridge mają teraz domyślnie wartość livekit zamiast bbb-webrtc-sfu. Wartość freeswitch nie jest już prawidłowa dla audioBridge: klient traktuje ją jako nieznany mostek i korzysta teraz z livekit (wcześniej bbb-webrtc-sfu). Zamiast tego użyj audioBridge=bbb-webrtc-sfu.

Osoby dołączające telefonicznie do mostka audio LiveKit pomijają poczekalnię dla gości, nawet przy guestPolicy=ASK_MODERATOR. Jeśli Twoja integracja wymaga wpuszczania uczestników telefonicznych przez moderatorów, przekaż audioBridge=bbb-webrtc-sfu w create, co przełączy mostek audio na FreeSWITCH.

Uwaga dla klientów bbbserver.de: pracujemy nad zachowaniem ograniczenia dołączania przez telefon w BigBlueButton również podczas korzystania z LiveKit.

Parametry userdata o nazwach userdata-bbb_listen_only_mode i userdata-bbb_transparent_listen_only są uwzględniane tylko przy audioBridge=bbb-webrtc-sfu. Przy livekit użytkownicy w trybie tylko do słuchania zawsze dołączają przez połączenie z wyciszonym mikrofonem.

Wartości disabledFeatures

Wartość Zmiana
layouts Nie jest już prawidłowa — wybór układu został usunięty z klienta. Bez wpływu na działanie
captions Nie jest już prawidłowa — nie miała żadnego wpływu od BBB 3.0. Użyj liveTranscription, aby wyłączyć automatyczną transkrypcję. Bez wpływu na działanie
pinChatMessage Nowość: wyłącza przypinanie wiadomości na czacie. Nowość
multiFunctionalMode Nowość: wyłącza pomocniczy panel boczny. Nowość
webcamGrid Nowość: wyłącza kafelki awatarów użytkowników bez kamery, gdy prezentacja jest zminimalizowana. Nowość

Prezentacje przesłane z wyprzedzeniem

Od BBB 4.0.1 wywołanie create przesyła maksymalnie 10 dokumentów (ustawienie serwera maxPresentationsPerRequest; prezentacja domyślna nie jest wliczana). Dokument oznaczony jako current="true" jest zawsze zachowywany, a pozostałe są uwzględniane w kolejności podanej w żądaniu. Nadmiarowe dokumenty są pomijane, ale spotkanie nadal zostaje utworzone, a odpowiedź zawiera messageKey=documentsDropped:

<response>
  <returncode>SUCCESS</returncode>
  <meetingID>demo</meetingID>
  <!-- ... -->
  <messageKey>documentsDropped</messageKey>
  <message>...</message>
</response>

Pamiętaj, że messageKey może teraz mieć wartość documentsDropped w SUCCESS. Jeśli Twój kod traktuje każdą wartość messageKey jako błąd lub sprawdza tylko wartość duplicateWarning, dostosuj go. Kolejne dokumenty prześlij później za pomocą insertDocument.

Ponadto create sprawdza teraz treść żądania przed utworzeniem spotkania: treść, która nie jest poprawnie sformowanym dokumentem XML, powoduje błąd messageKey=malformedXml, a adres URL dokumentu o nieprawidłowej składni powoduje błąd messageKey=invalidPresentationUrl. W obu przypadkach spotkanie nie zostaje utworzone.

Wywołanie zwrotne po zakończeniu spotkania

Od wersji BBB 4.0.1 wywołanie zwrotne meetingEndedURL dołącza meetingID i recordingmarks do ciągu zapytania w Twoim adresie URL (w wersji 4.0.0 adres URL był wywoływany bez zmian). Istniejące parametry zachowują swoje wartości, ale mogą zostać ponownie zakodowane. Jeśli Twój adres URL zawiera już parametr o tej samej nazwie, wysyłane są obie wartości – Twoja jako pierwsza.

Wywołanie zwrotne (3.x)
GET https://example.com/ended?token=a817dde5
Wywołanie zwrotne (4.0.1+)
GET https://example.com/ended?token=a817dde5
  &recordingmarks=true&meetingID=demo

Jeśli nadal używasz meta_endCallbackUrl: oficjalna dokumentacja zaleca teraz zamiast tego meetingEndedURL, ponieważ wartości meta_* mogą być widoczne dla użytkowników podczas spotkania i mogą ujawnić tajne tokeny zawarte w adresie URL wywołania zwrotnego. Nie weryfikuj podpisu na podstawie surowego ciągu zapytania, ponieważ może on zostać ponownie zakodowany.

Pozostałe zmiany

  • Pokoje podgrup tworzone w kliencie dziedziczą teraz efektywną wartość meetingKeepEvents swojego spotkania nadrzędnego (wcześniej zawsze używały domyślnej wartości serwera defaultKeepEvents). Pokoje podgrup tworzone samodzielnie za pomocą create z isBreakout=true nadal używają własnego parametru meetingKeepEvents.

Nowe parametry

Parametr Domyślnie Opis
lockSettingsPresenterPolicy requireApproval Zasady dotyczące prośby o rolę prezentera: moderatorOnly, requireApproval lub freeForAll.
requireUserConsentBeforeUnmuting false Przy ustawieniu true użytkownicy muszą wyrazić zgodę, zanim moderator włączy im mikrofon (ma znaczenie tylko przy ustawieniu allowModsToUnmuteUsers=true).

Domyślna wartość requireApproval oznacza, że widzowie mogą teraz prosić o rolę prezentera w kliencie. Jeśli tylko moderatorzy powinni przydzielać rolę prezentera, przekaż lockSettingsPresenterPolicy=moderatorOnly.

Wszystkie szczegóły: Utwórz spotkanie (4.x).

Zmiany w join

Parametr Zmiana Co należy zrobić
fullName Limit wynosi 255 znaków. Dłuższe wartości są odrzucane z błędem fullNameTooLong (wcześniej bez limitu). Skróć nazwy wyświetlane przed utworzeniem adresu URL dołączania.
enforceLayout Akceptowane są tylko UNIFIED_LAYOUT, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY i MEDIA_ONLY. Zmapuj stare wartości zgodnie z powyższą tabelą układów.
webVoiceConf Usunięto (wartość nigdy nie była odczytywana). Usuń parametr.
userdata-bbb_change_layout Usunięto; jego wartości smart, videoFocus, presentationFocus i custom już nie istnieją. Użyj userdata-bbb_default_layout.
userdata-enable-user-reaction Usunięto. Użyj disabledFeatures=userReactions w create lub ustawienia klienta public.userReaction.enabled.
userdata-bbb_parent_room_moderator Usunięto w wersji 4.0.1; nie miało żadnego wpływu od wersji 3.0.25. Przydziel rolę w pokoju podgrupy za pomocą role.
userdata-bbb_hide_sidebar_navigation Nowość: zamyka nawigację boczną i panel boczny podczas dołączania. Nowość Opcjonalne.
Przed (3.x)
join?meetingID=demo&role=VIEWER
  &fullName=<any length>
  &enforceLayout=PRESENTATION_FOCUS
  &userdata-bbb_change_layout=smart
Po (4.x)
join?meetingID=demo&role=VIEWER
  &fullName=<max. 255 characters>
  &enforceLayout=UNIFIED_LAYOUT
  &userdata-bbb_default_layout=UNIFIED_LAYOUT

Zmiany w insertDocument

  • Maksymalnie 10 dokumentów na wywołanie (maxPresentationsPerRequest). Nadmiarowe dokumenty są pomijane, a odpowiedź nadal ma wartość SUCCESS z messageKey=documentsDropped.
  • Limit wywołań na spotkanie: domyślnie 30 wywołań na 60 sekund. Wywołania przekraczające limit kończą się błędem rateLimitExceeded – ponów próbę po pewnym czasie.
  • Każda odpowiedź FAILED zawiera teraz messageKey: notFound, malformedXml, invalidPresentationUrl, invalidFilename, presentationDisabled, noDocuments.

Jeśli obsługa błędów w Twoim kodzie porównuje tekst message, przejdź na messageKey. Szczegóły: Wstaw prezentację (4.x).

Zmiany w end

Zakończenie spotkania kończy teraz również wszystkie jego pokoje podgrup, w tym pokoje utworzone za pomocą create z isBreakout=true. Wcześniej tylko pokoje podgrup utworzone w kliencie kończyły się wraz ze spotkaniem nadrzędnym. Jeśli Twoja aplikacja kończyła takie pokoje osobnymi wywołaniami end, wywołania te nie są już potrzebne – upewnij się, że Twój kod poprawnie obsługuje pokój podgrupy, który został już zakończony.

Zmiany w sendChatMessage

Zmieniono messageKey dla brakujących parametrów: brak message zwraca teraz missingParamMessage (wcześniej nullError), a brak meetingID zwraca missingParamMeetingID (wcześniej meetingNotFound). Naruszenia limitu długości nadal zwracają sizeError, a nieprawidłowe znaki w meetingID nadal zwracają validationError.

Usunięte punkty końcowe i zmiany na poziomie HTTP

  • Usunięto /api/rest/clientSettings. Ustawienia klienta są teraz dostarczane przez GraphQL wewnątrz klienta; dostosuj je dla poszczególnych spotkań za pomocą clientSettingsOverride lub clientSettingsOverrideJsonUrl.
  • Usunięto części interfejsu API GraphQL związane z Etherpadem. Wtyczki lub integracje, które wysyłają do nich zapytania, otrzymują błąd walidacji.
  • Nieznane adresy URL w ścieżce /bigbluebutton/ zwracają 404 z treścią JSON zamiast dokumentu XML.
  • Żądania zawierające więcej niż 10,000 parametrów otrzymują odpowiedź HTTP 500.
  • Żądania wstępne CORS bez konfiguracji CORS zwracają 200 bez nagłówków Access-Control-* (wcześniej 403); Vary: Origin nie jest już wysyłany.
  • Wszystkie odpowiedzi zawierają nagłówki bezpieczeństwa X-Frame-Options, X-Content-Type-Options, Referrer-Policy i X-XSS-Protection. Jeśli osadzasz odpowiedzi API w ramkach, sprawdź X-Frame-Options.

Zmiany dotyczące odpowiedzi 404, limitu parametrów i żądań wstępnych CORS obowiązują już od wersji BBB 3.0.40 (bbb-web na Grails 8); dotyczą Cię tylko wtedy, gdy Twoje serwery działają na starszym wydaniu wersji 3.0. Nagłówki bezpieczeństwa są nowością w wersji 4.0 – w wersji BBB 3.0.40 są wyłączone.

Bez zmian

Następujące części API są identyczne w 3.x i 4.x – nie są wymagane żadne zmiany:

  • Obliczanie Checksum i obsługiwane algorytmy skrótu (SHA-1, SHA-256, SHA-384, SHA-512)
  • isMeetingRunning, getMeetings, getMeetingInfo (parametry i format odpowiedzi)
  • getRecordings, publishRecordings, deleteRecordings, updateRecordings, getRecordingTextTracks, putRecordingTextTrack
  • Webhooks, z wyjątkiem zdarzenia pad-content, które już nie istnieje z powodu usunięcia Etherpada
  • Przydzielanie ról za pomocą role w join (wprowadzone w wersji BBB 2.4)

Ustawienia serwera wpływające na działanie API

Te ustawienia są konfigurowane przez operatora serwera w bbb-web.properties, a nie za pomocą parametrów API. Jeśli zarządzasz własnymi serwerami lub Twój dostawca zmieni te ustawienia, działanie wywołań API może się zmienić:

Ustawienie Zmiana w wersji 4.x
allowDuplicateExtUserid Usunięto. Wielokrotne dołączanie z tym samym userID jest teraz kontrolowane przez maxUserConcurrentAccesses.
defaultMeetingLayout Domyślnie UNIFIED_LAYOUT (wcześniej CUSTOM_LAYOUT).
audioBridge, cameraBridge, screenShareBridge Domyślnie livekit.
maxPresentationsPerRequest, insertDocumentMaxRequests, insertDocumentRateWindowSec Nowe limity (wartości domyślne: 10, 30, 60).
accessControlAllowOrigin Usunięto; CORS konfiguruje się za pomocą grails.cors.*.

Lista kontrolna migracji

Wyszukaj w kodzie usunięte wartości: CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS, lockSettingsDisableNote=, sharedNotesEditor, bbb_change_layout, enable-user-reaction i clientSettings.

Uporządkuj disabledFeatures: usuń layouts i captions.

Ogranicz wyświetlane nazwy do 255 znaków i dodaj obsługę fullNameTooLong.

Sprawdź przesyłanie prezentacji: nie więcej niż 10 dokumentów na wywołanie create/insertDocument; dodaj obsługę documentsDropped i rateLimitExceeded.

Sprawdź kod obsługi wywołań zwrotnych dla meetingEndedURL: musi przyjmować dodatkowe parametry meetingID i recordingmarks.

Zdecyduj o nowych ustawieniach domyślnych: prośbach o rolę prezentera (lockSettingsPresenterPolicy) i poczekalni dla gości łączących się telefonicznie (audioBridge).

Przetestuj integrację z serwerem w wersji 4.x – w szczególności pokoje podgrup, przesyłanie prezentacji i obsługę błędów opartą na messageKey.

Twoja integracja musi przez pewien czas obsługiwać obie wersje? Wszystkie powyższe zmiany są wstecznie kompatybilne w jednym kierunku: UNIFIED_LAYOUT, lockSettingsDisableNotes, userdata-bbb_default_layout oraz wyświetlane nazwy o długości do 255 znaków działają również na serwerach BBB 3.0.19+. Stosuj je wszędzie, a wywołania API będą działać w obu wersjach.

Szukasz poprzedniej dokumentacji? Pełna dokumentacja referencyjna 3.x pozostaje dostępna, np. Utwórz spotkanie (3.x).

Najczęściej zadawane pytania

Możesz – i warto – zrobić to wcześniej. Zalecane zamienniki (UNIFIED_LAYOUT, lockSettingsDisableNotes, userdata-bbb_default_layout) są już obsługiwane przez BBB 3.0.19. Przygotuj kod tak, aby aktualizacja serwera nie wymagała jednoczesnego wydania nowej wersji aplikacji.

Nie. BigBlueButton ignoruje nieznane parametry, więc usunięty parametr nie ma żadnego efektu i nie powoduje ostrzeżenia. Dlatego łatwo przeoczyć usunięte parametry – sprawdź kod, korzystając z list w tym przewodniku.

Nie. checksum nadal oblicza się jako sha(apiCallName + queryString + sharedSecret) przy użyciu tych samych obsługiwanych algorytmów skrótu.

Nie. Ten przewodnik obejmuje wyłącznie zmiany w wywołaniach API wykonywanych przez aplikację. Aktualizacja samych serwerów konferencyjnych to odrębny temat, którym zajmuje się operator serwera.