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 |
create?meetingID=demo&name=Demo
&lockSettingsDisableNote=true
&sharedNotesEditor=blockNote
©right=Example+Inc.
&meetingLayout=SMART_LAYOUTcreate?meetingID=demo&name=Demo
&lockSettingsDisableNotes=true
&clientSettingsOverrideJsonUrl=https%3A%2F%2F
example.com%2Fclient-settings.json
&meetingLayout=UNIFIED_LAYOUTUkł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.
GET https://example.com/ended?token=a817dde5GET https://example.com/ended?token=a817dde5
&recordingmarks=true&meetingID=demoJeś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ść
meetingKeepEventsswojego spotkania nadrzędnego (wcześniej zawsze używały domyślnej wartości serweradefaultKeepEvents). Pokoje podgrup tworzone samodzielnie za pomocącreatezisBreakout=truenadal używają własnego parametrumeetingKeepEvents.
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. |
join?meetingID=demo&role=VIEWER
&fullName=<any length>
&enforceLayout=PRESENTATION_FOCUS
&userdata-bbb_change_layout=smartjoin?meetingID=demo&role=VIEWER
&fullName=<max. 255 characters>
&enforceLayout=UNIFIED_LAYOUT
&userdata-bbb_default_layout=UNIFIED_LAYOUTZmiany w insertDocument
- Maksymalnie 10 dokumentów na wywołanie (
maxPresentationsPerRequest). Nadmiarowe dokumenty są pomijane, a odpowiedź nadal ma wartośćSUCCESSzmessageKey=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ź
FAILEDzawiera terazmessageKey: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ąclientSettingsOverridelubclientSettingsOverrideJsonUrl. - 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ą404z 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ą
200bez nagłówkówAccess-Control-*(wcześniej403);Vary: Originnie jest już wysyłany. - Wszystkie odpowiedzi zawierają nagłówki bezpieczeństwa
X-Frame-Options,X-Content-Type-Options,Referrer-PolicyiX-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ą
rolewjoin(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
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.sha(apiCallName + queryString + sharedSecret) przy użyciu tych samych obsługiwanych algorytmów skrótu.