API BigBlueButton

Przegląd

Ten dokument opisuje interfejs programowania aplikacji (API) BigBlueButton.

Dla programistów to API umożliwia

• tworzenie spotkań
• dołączanie do spotkań
• kończenie spotkań
• wstawianie dokumentów
• pobierz nagrania z poprzednich spotkań (i usuń je)
• przesyłaj pliki z napisami dla spotkań
• wysyłaj wiadomość na czacie publicznym

Aby wykonać wywołanie API do serwera BigBlueButton, aplikacja wysyła żądania HTTPS do punktu końcowego API serwera BigBlueButton (zwykle jest to nazwa hosta serwera, po której następuje /bigbluebutton/api). Wszystkie wywołania API muszą zawierać sumę kontrolną obliczoną z sekretem udostępnionym serwerowi BigBlueButton.

Serwer BigBlueButton zwraca odpowiedź XML na wszystkie wywołania API.

Aktualizacje API w BigBlueButton

Zaktualizowano w wersji 0.9.0:

• dołącz - configToken może teraz odwoływać się do plik w formacie /var/bigbluebutton/configs, na przykład myconfig.xml.
• utwórz - Dodano trzy parametry: moderatorOnlyMessage, aby wyświetlić wiadomość widoczną tylko dla moderatorów i autoStartRecording/allowStartStopRecording, aby zapewnić lepszą kontrolę nad nagraniami.

Aktualizacja w wersji 1.0:

• getMeetings - Dodano pola w zwróconym formacie XML
• getMeetingInfo - Dodano pola w zwróconym formacie XML i przestarzałe parametry
• getRecordings - Dodano metaparametr i parametr stanu do filtrowania zwracanych wyników

Aktualizacja w wersji 1.1:

• create - Dodano pola w zwracanym formacie XML
• getMeetings - Dodano pola do zwróconego XML
• getMeetingInfo - Dodano pola do zwróconego XML
• getRecordings - Zwraca blok XML z miniaturami slajdów oraz element <participants>N</participants> z liczbą uczestników, którzy biorą udział w spotkaniu.
• updateRecordings - Możliwość edycji metaparametrów

Aktualizacja w wersji 2.0:

• utwórz - Dodano bannerText, bannerColor, logo, copyright i muteOnStart.
• getMeetings - Teraz zwraca wszystkie pola w getMeetingInfo.
• getMeetingInfo - Dodano pole <client> umożliwiające zwrócenie typu klienta (FLASH lub HTML5).

Aktualizacja w wersji 2.2:

• utwórz - Dodano endWhenNoModerator, meetingEndedURL.
• getRecordingTextTracks - Uzyskaj listę plików podpisów/napisów aktualnie dostępnych dla nagrania.
• putRecordingTextTrack - Prześlij plik podpisu lub napisów, aby dodać go do nagrania. Jeśli istnieje jakaś ścieżka z tymi samymi wartościami rodzaju i języka, zostanie ona zastąpiona.

Aktualizacja w wersji 2.3:

• utwórz - Zmieniono nazwę keepEvents na meetingKeepEvents, usunięto joinViaHtml5, dodano endWhenNoModeratorDelayInMinutes.
• getDefaultConfigXML przestarzały, nieużywany w kliencie HTML5.
• setConfigXML przestarzały, nie używany w kliencie HTML5.

Zaktualizowano w wersji 2.4:

• getDefaultConfigXML Usunięty, nieużywany w kliencie HTML5.
• setConfigXML Usunięty, nieużywany w kliencie HTML5.
• utwórz
• Dodano meetingLayout, learningDashboardEnabled, learningDashboardCleanupDelayInMinutes, allowModsToEjectCameras, virtualBackgroundsDisabled, allowRequestsWithoutSession, userCameraCap.
• name, attendeePW i moderatorPW muszą mieć długość od 2 do 64 znaków
• meetingID muszą mieć długość od 2 do 256 znaków i nie mogą zawierać przecinków
• dołącz - Dodano role, excludeFromDashboard.

Zaktualizowano w wersji 2.5:

• utwór - Dodano: meetingCameraCap, groups, disabledFeatures, meetingExpireIfNoUserJoinedInMinutes, meetingExpireWhenLastUserLeftInMinutes, preUploadedPresentationOverrideDefault; Przestarzałe: learningDashboardEnabled, breakoutRoomsEnabled, virtualBackgroundsDisabled.

• Po raz pierwszy wprowadzono punkt końcowy insertDocument

Zaktualizowano w wersji 2.6:

• utwórz - Dodano: notifyRecordingIsOn, presentationUploadExternalUrl, presentationUploadExternalDescription, recordFullDurationMedia (v2.6.9); disabledFeaturesExclude(2.6.9); maxPinnedCameras, breakoutRoomsCaptureSlides, breakoutRoomsCaptureSlidesFilename, breakoutRoomsCaptureNotes, breakoutRoomsCaptureNotesFilename; Dodano liveTranscription i presentation jako opcje dla disabledFeatures.

• getRecordings - Dodano: Dodano obsługę paginacji przy użyciu offset, limit

• dołącz: Dodano userdata-bbb_hide_presentation_on_join.

Aktualizacja w 2.7:

• utwórz - Dodano: preUploadedPresentation, preUploadedPresentationName, allowPromoteGuestToModerator (2.7.9), Opcje disabledFeatures``cameraAsContent, snapshotOfCurrentSlide, downloadPresentationOriginalFile, downloadPresentationConvertedToPdf, timer, learningDashboardDownloadSessionData (2.7.5).
• dołącz - Dodano: errorRedirectUrl, userdata-bbb_fullaudio_bridge
• getRecordings - Aktualizacja: Zmodyfikowano odpowiedź dotyczącą paginacji, aby usunąć nadmiar metadanych paginacji i zwrócić tylko totalElements oprócz normalnych danych odpowiedzi.

Aktualizacja w wersji 3.0:

• utwórz
• Dodano parametry: loginURL, pluginManifests, pluginManifestsFetchUrl, presentationConversionCacheEnabled, maxNumPages, multiUserWhiteboardEnabled, clientSettingsOverrideJsonUrl, sharedNotesEditor, sharedNotesInitialContentJsonUrl (3.0.25), sharedNotesInitialContentMarkdown (3.0.33), sharedNotesInitialContentMarkdownUrl (3.0.33), cameraBridge, screenShareBridge, audioBridge, darklogo.
• Dodano opcje: Parametr meetingLayout obsługuje kilka nowych opcji: CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY;
• Dodano opcje: Parametr disabledFeatures obsługuje kilka nowych opcji: infiniteWhiteboard, deleteChatMessage, editChatMessage, replyChatMessage, chatMessageReactions, raiseHand, userReactions, chatEmojiPicker, quizzes;
• Dodano moduł POST: clientSettingsOverride (bramkowany przez ustawienie po stronie serwera allowOverrideClientSettingsOnCreateCall w bbb-web.properties);
• Usunięto: breakoutRoomsEnabled, learningDashboardEnabled, virtualBackgroundsDisabled.
• dołącz
• Dodano: bot, enforceLayout, logoutURL, firstName, lastName, userdata-bbb_default_layout, userdata-bbb_skip_echotest_if_previous_device, userdata-bbb_prefer_dark_theme. userdata-bbb_hide_notifications, userdata-bbb_hide_controls, userdata-bbb_initial_selected_tool
• Usunięto: defaultLayout (zastąpione przez userdata-bbb_default_layout) i usunięto obsługę wszystkich metod żądań HTTP z wyjątkiem GET, userdata-bbb_ask_for_feedback_on_logout.
• Po raz pierwszy wprowadzono punkt końcowy sendChatMessage.
• po raz pierwszy wprowadzono punkt końcowy getJoinUrl.
• Usunięto punkt końcowy enter. Był używany tylko wewnętrznie, nigdy nie był częścią dokumentacji API.
• Usunięto punkt końcowy html5client/check. Wykorzystano go do sprawdzenia kondycji serwera powracającego {"html5clientStatus":"running"}
• wprowadzono punkt końcowy feedback, zastępując wywołania /html5client/feedback przez /api/feedback

Aktualizacja w wersji 4.0:

• utwórz
• Dodano parametry: requireUserConsentBeforeUnmuting (istotne tylko w przypadku allowModsToUnmuteUsers=true; w przypadku true użytkownikowi pojawia się okno dialogowe wyrażające zgodę, zanim moderator będzie mógł wyłączyć wyciszenie), lockSettingsPresenterPolicy (kontroluje politykę „Prośba o prezentację”; jedna z moderatorOnly, requireApproval (domyślnie), freeForAll), notifyRecordingAppend (w przypadku notifyRecordingIsOn=true dołącza opcjonalny zwykły tekst do okna dialogowego powiadomienia o nagraniu).
• Dodano opcje: Parametr disabledFeatures obsługuje nowe opcje: multiFunctionalMode (panel pomocniczy/podwójny panel boczny), pinChatMessage i webcamGrid.
• Usunięty parametr: lockSettingsDisableNote (liczba pojedyncza); zamiast tego użyj lockSettingsDisableNotes (liczba mnoga).
• Usunięto parametr: copyright (nie przyniosło to żadnego efektu; wartość została zapisana, ale nigdy nie została przesłana do klienta). Aby dostosować tekst praw autorskich na spotkanie, zastąp app.copyright do clientSettingsOverride / clientSettingsOverrideJsonUrl (wymaga allowOverrideClientSettingsOnCreateCall=true).
• Usunięty parametr: logoutTimer (nie przyniosło to żadnego efektu; wartość była przechowywana w bbb-web, ale nigdy nie została przesłana do akka-apps ani klienta HTML5).
• Usunięty parametr: webVoice (przestarzały; wybierał oddzielną konferencję głosową dla starego klienta Flash i nie miał żadnego wpływu na dalszy ciąg po usunięciu tego klienta w BBB 2.3, zawsze powracając do voiceBridge).
• Zmieniono: Domyślnym parametrem meetingLayout jest teraz UNIFIED_LAYOUT. Usunięto: meetingLayout nie obsługuje już CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS. Pozostałe opcje inne niż domyślne przeznaczone dla scenariuszy hybrydowych/niszowych to CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY.
• Usunięty parametr: sharedNotesEditor (obsługa Etherpada została usunięta; parametr jest teraz ignorowany, a spotkania zawsze używają BlockNote do udostępniania notatek).
• Zmieniono: Pokoje podgrup teraz zawsze dziedziczą efektywną wartość meetingKeepEvents spotkania nadrzędnego; jawny parametr meetingKeepEvents i ogólnoserwerowa rezerwa defaultKeepEvents mają zastosowanie tylko do spotkań na najwyższym poziomie (poprzednio przerwania zawsze wracały do ​​defaultKeepEvents, nawet jeśli element nadrzędny miał jawne zastąpienie).
• Usunięta opcja: layouts nie jest już prawidłową wartością disabledFeatures (usunięto interfejs wyboru układu).
• Usunięta opcja: captions nie jest już prawidłową wartością disabledFeatures (nie ma to żadnego efektu od wersji BBB 3.0, kiedy podpisy tekstów zostały przeniesione do wtyczki). Użyj liveTranscription, aby wyłączyć automatyczną transkrypcję.
• dołącz
• Zmieniono: Akceptowane wartości parametru enforceLayout to teraz UNIFIED_LAYOUT, CAMERAS_ONLY, PARTICIPANTS_AND_CHAT_ONLY, PRESENTATION_ONLY, MEDIA_ONLY (przestarzałe CUSTOM_LAYOUT, SMART_LAYOUT, PRESENTATION_FOCUS, VIDEO_FOCUS nie są już akceptowane).
• Zmieniono: Parametr fullName jest teraz ograniczony do 255 znaków; dłuższa wartość jest odrzucana za pomocą klucza komunikatu fullNameTooLong (wcześniej nieograniczonego).
• Usunięte parametry: userdata-bbb_change_layout (redundantne z userdata-bbb_default_layout; jego starsze wartości smart/videoFocus/presentationFocus/custom już nie istnieją) i userdata-enable-user-reaction (redundantny z opcją userReactions disabledFeatures i public.userReaction.enabled w settings.yml).
• Usunięty parametr: webVoiceConf (przestarzały; ustawiał niestandardowe rozszerzenie głosu Asterisk dla starego klienta Flash i nie miał żadnego wpływu na dalszy ciąg, wartość nigdy nie została odczytana).
• clientSettings - Przestarzały punkt końcowy REST /api/rest/clientSettings został usunięty. Ustawienia klienta są teraz obsługiwane przez stos GraphQL.

Typy danych API

W interfejsie API występują trzy typy.

String: Ten typ danych wskazuje ciąg zakodowany (UTF-8). Przekazując wartości String do wywołań API BigBlueButton, upewnij się, że używasz wartości UTF-8 zakodowanych w poprawnym adresie URL, aby tekst międzynarodowy był wyświetlany poprawnie. Ciąg nie może zawierać znaków kontrolnych (wartości od 0x00 do 0x1F).

Niektóre parametry API BigBlueButton nakładają dodatkowe ograniczenia na dozwolone znaki lub na długość łańcucha. Ograniczenia te opisano w dokumentacji parametrów.

Numer: Ten typ danych wskazuje nieujemną wartość całkowitą. Wartość parametru może zawierać wyłącznie cyfry od 0 do 9. Nie powinno być znaku wiodącego (+ lub -), przecinków ani kropek.

Boolean: A wartość prawda/fałsz. Wartość należy określić jako ciąg literału true lub false (wszystkie małe litery), inne wartości mogą zostać błędnie zinterpretowane.

Model zabezpieczeń API

Model zabezpieczeń BigBlueButton API umożliwia aplikacjom innych firm wykonywanie wywołań API (jeśli mają wspólny sekret), ale nie pozwala innym osobom (użytkownikom końcowym) na wykonywanie wywołań API.

Prawie wszystkie wywołania API BigBlueButton są wykonywane między serwerami. Jeśli zainstalowałeś pakiet bbb-demo na swoim serwerze BigBlueButton, otrzymasz zestaw przykładów API napisanych w Java Server Pages (JSP), które demonstrują, jak używać API BigBlueButton. Te dema działają jako aplikacja internetowa w Tomcat7. Aplikacja internetowa wysyła żądania HTTPS do punktu końcowego API serwera BigBlueButton.

Możesz pobrać parametry API BigBlueButton (punkt końcowy API i współdzielony sekret) za pomocą polecenia

$ bbb-conf --secret

Oto przykładowy zwrot

    URL: http://bbb.example.com/bigbluebutton/
    Secret: ECCJZNJWLPEA3YB6Y2LTQGQD3GJZ3F93

Nie powinieneś_ osadzać wspólnego sekretu na stronie internetowej i wykonywać wywołań API BigBlueButton w JavaScript działającym w przeglądarce. Wbudowane narzędzia do debugowania dla nowoczesnej przeglądarki sprawią, że ten sekret będzie łatwo dostępny dla każdego użytkownika. Gdy ktoś zdobędzie wspólny sekret dla Twojego serwera BigBlueButton, będzie mógł utworzyć własne wywołania API. Wspólny sekret powinien być dostępny tylko dla komponentów aplikacji po stronie serwera (a zatem niewidoczny dla użytkowników końcowych).

Konfiguracja

Wspólny sekret znajduje się w pliku /etc/bigbluebutton/bbb-web.properties.

Poszukaj parametru securitySalt (nazywa się securitySalt ze względu na starsze nazewnictwo łańcucha)

securitySalt=<your_salt>

Będziemy nazywać tę wartość sharedSecret. Kiedy po raz pierwszy instalujesz BigBlueButton na serwerze, skrypty pakujące tworzą losowy 32-znakowy kod sharedSecret. Możesz także zmienić sharedSecret w dowolnym momencie za pomocą polecenia bbb-conf --setsecret.

$ sudo bbb-conf --setsecret <new_shared_secret>

Poniższe polecenie utworzy nowy wspólny sekret o długości 32 znaków dla Twojego serwera

$ sudo bbb-conf --setsecret \$(openssl rand -base64 32 | sed 's/=//g' | sed 's/+//g' | sed 's/\///g')

WAŻNE: NIE POZWALAJ UŻYTKOWNIKOM KOŃCOWYM NA POZNANIE TWOJEGO TAJEMNICY WSPÓLNEJ, W przeciwnym razie Twoje bezpieczeństwo zostanie naruszone.

Istnieją inne wartości konfiguracyjne w konfiguracji bbb-web bigbluebutton.properties (nadpisane przez /etc/bigbluebutton/bbb-web.properties ) związany z cyklem życia spotkania. Nie musisz rozumieć tego wszystkiego, aby zacząć korzystać z API BigBlueButton. W przypadku większości serwerów BigBlueButton można pozostawić wartości domyślne.

W BigBlueButton 2.5 dodano obsługę dodatkowych algorytmów haszujących, oprócz sha1 i sha256. Należą do nich sha384 i sha512. Właściwość supportedChecksumAlgorithms w bbb-web określa, które algorytmy są obsługiwane. Domyślnie sumy kontrolne można sprawdzać za pomocą dowolnego obsługiwanego algorytmu. Aby usunąć obsługę jednego lub więcej z tych algorytmów, po prostu usuń go z pliku konfiguracyjnego. Jeśli porzucisz obsługę sha256 (na przykład jeśli chcesz wymusić używanie tylko sha512), będziesz musiał także zaktualizować właściwość checkSumAlgorithmForBreakouts w akka-apps.

W /etc/bigbluebutton/bbb-web.properties:

supportedChecksumAlgorithms=sha512

W /etc/bigbluebutton/bbb-apps-akka.conf:

services {
  checkSumAlgorithmForBreakouts = "sha512"
  #...
}

I pamiętaj o ponownym uruchomieniu BigBlueButton.

Zastosowanie

Implementacja modelu bezpieczeństwa BigBlueButton leży w kontrolerze ApiController.groovy. Dla każdego przychodzącego żądania API kontroler oblicza sumę kontrolną na podstawie kombinacji całego ciągu zapytania HTTPS i wspólnego sekretu serwera. Następnie dopasowuje przychodzącą sumę kontrolną do obliczonej sumy kontrolnej. Jeśli są zgodne, kontroler akceptuje przychodzące żądanie.

Aby skorzystać z modelu bezpieczeństwa, musisz mieć możliwość utworzenia sumy kontrolnej SHA-1 na podstawie nazwy wywołania plus ciągu zapytania plus wspólnego hasła skonfigurowanego na serwerze. Aby to zrobić, wykonaj następujące kroki:

1. Utwórz cały ciąg zapytania dla wywołania API bez parametru sumy kontrolnej.

• Przykład tworzenia wywołania API spotkania: name=Test+Meeting&meetingID=abc123&attendeePW=111222&moderatorPW=333444

2. Dodaj nazwę wywołania API do swojego ciągu znaków

• Przykład powyższego ciągu zapytania:
• Nazwa wywołania API to create
• Ciąg znaków staje się: createname=Test+Meeting&meetingID=abc123&attendeePW=111222&moderatorPW=333444

3. Teraz dołącz wspólny sekret do swojego ciągu

• Przykład powyższego ciągu zapytania:
• wspólny sekret to 639259d4-9dd8-4b25-bf01-95f9567eaf4b
• Ciąg znaków ma postać: createname=Test+Meeting&meetingID=abc123&attendeePW=111222&moderatorPW=333444639259d4-9dd8-4b25-bf01-95f9567eaf4b

4. Teraz znajdź sumę SHA-1 dla tego ciągu (implementacja różni się w zależności od języka programowania).

• suma SHA-1 dla powyższego ciągu to: 1fcbb0c4fc1f039f73aa6d697d2db9ba7f803f17

5. Dodaj parametr sumy kontrolnej do ciągu zapytania, który zawiera tę sumę kontrolną.

• Powyższy przykład ma postać: name=Test+Meeting&meetingID=abc123&attendeePW=111222&moderatorPW=333444&checksum=1fcbb0c4fc1f039f73aa6d697d2db9ba7f803f17

MUSISZ wysłać tę sumę kontrolną przy KAŻDYM wywołaniu API. Ponieważ użytkownicy końcowi nie znają Twojego wspólnego sekretu, nie mogą sfałszować wywołań do serwera i nie mogą modyfikować żadnych wywołań API, ponieważ zmiana nazwy lub wartości pojedynczego parametru tylko o jeden znak całkowicie zmieni sumę kontrolną wymaganą do sprawdzenia poprawności wywołania.

UWAGA Sumy kontrolne dla żądań POST muszą być obliczane również przy użyciu ciągu zapytania URL. Na przykład, jeśli wszystkie parametry żądania znajdują się w treści żądania, suma kontrolna zostanie obliczona przy użyciu pustego ciągu zapytania.

Implementacje funkcjonalności SHA-1 istnieją w prawie wszystkich językach programowania. Oto przykładowe metody lub linki do przykładowych implementacji dla różnych języków:

• JavaScript
• opisuje także MD5
• Java
• Możesz użyć org.apache.commons.codec.digest.DigestUtils i zadzwonić DigestUtils.shaHex(string + sharedSecret)
• PHP
• po prostu zadzwoń sha1(string . sharedSecret)

Obsługa błędów

W przypadku błędu wszystkie wywołania API dokładają wszelkich starań, aby zwrócić prawidłowo sformatowany plik XML zawierający wystarczającą ilość informacji, aby osoba wywołująca mogła określić źródło błędu.

Błędy są zwracane z wartością returncode wynoszącą FAILED oraz wartościami message i messageKey. Dołożymy wszelkich starań, aby MessageKey był stabilny (niezmienny) przez cały okres istnienia API. Jednakże wartość message jest wartością w postaci zwykłego tekstu (w języku angielskim), która może zmieniać się z czasem.

Możesz użyć messageKey do określenia rodzaju błędu i, jeśli to konieczne, wyszukać międzynarodowy tekst w swoim własnym systemie. Na przykład nieprawidłowe żądanie może zwrócić komunikat o błędzie „Brak konferencji o tym identyfikatorze spotkania”, ale klucz komunikatu to po prostu „invalidMeetingIdentifier”.

Zasoby API

Administracja

Poniższa sekcja opisuje wywołania administracyjne

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Monitorowanie

Poniższy rozdział opisuje połączenia monitorujące

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Nagrywanie

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Wywołania API

Poniższe parametry odpowiedzi są standardowe dla każdego wywołania i mogą zostać zwrócone z dowolnego połączenia.

Parametry:

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Odpowiedź:

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

GET POST create

Tworzy spotkanie BigBlueButton.

Wywołanie create jest idempotentne: można je wywołać wielokrotnie z tymi samymi parametrami, bez skutków ubocznych. Upraszcza to logikę dołączania użytkownika do sesji, ponieważ aplikacja może zawsze wywołać funkcję create przed zwróceniem użytkownikowi adresu URL przyłączania. W ten sposób, niezależnie od kolejności dołączania użytkowników, spotkanie będzie zawsze istnieć, gdy użytkownik spróbuje się dołączyć (pierwsze wywołanie create faktycznie tworzy spotkanie; kolejne wywołania create po prostu zwracają SUCCESS).

Serwer BigBlueButton automatycznie usunie puste spotkania, które zostały utworzone, ale nigdy nie miały żadnych użytkowników, po liczbie minut określonej przez meetingExpireIfNoUserJoinedInMinutes zdefiniowanym we właściwościach bbb-web.

URL zasobu:

http://yourserver.com/bigbluebutton/api/create?[parameters]&checksum=[checksum]

Parametry:

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Przykładowe żądania:

• http://yourserver.com/bigbluebutton/api/create?name=Test&meetingID=test01&suma kontrolna=1234
• http:///yourserver.com/bigbluebutton/api/create?name=Test&meetingID=test01&moderatorPW=mp&attendeePW=ap&checksum=wxyz
• http://yourserver.com/bigbluebutton/api/create?name=Test&meetingID=test01&moderatorPW=mp&attendeePW=ap&meta_presenter=joe&meta_category=education&checksum=abcd

Przykładowa odpowiedź:

<response>
  <returncode>SUCCESS</returncode>
  <meetingID>Test</meetingID>
  <internalMeetingID>640ab2bae07bedc4c163f679a746f7ab7fb5d1fa-1531155809613</internalMeetingID>
  <parentMeetingID>bbb-none</parentMeetingID>
  <attendeePW>ap</attendeePW>
  <moderatorPW>mp</moderatorPW>
  <createTime>1531155809613</createTime>
  <`voiceBridge`>70757</`voiceBridge`>
  <dialNumber>613-555-1234</dialNumber>
  <createDate>Mon Jul 09 17:03:29 UTC 2018</createDate>
  <hasUserJoined>false</hasUserJoined>
  <duration>0</duration>
  <hasBeenForciblyEnded>false</hasBeenForciblyEnded>
  <messageKey>duplicateWarning</messageKey>
  <message>This conference was already in existence and may currently be in progress.</message>
</response>

Żądanie POST

W żądaniu możesz także zawrzeć ładunek, może to być przydatne w przypadkach, gdy niektóre parametry zapytania są na tyle duże, że przekraczają maksymalną liczbę znaków w adresach URL. BigBlueButton obsługuje żądanie POST, w którym parametry, które zwykle byłyby przekazywane w adresie URL, mogą zostać przesłane przez treść, patrz przykład poniżej:

curl --request POST \
  --url https://<your-host>/bigbluebutton/api/create \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data welcome=Welcome \
  --data allowStartStopRecording=true \
  --data attendeePW=ap \
  --data autoStartRecording=false \
  --data meetingID=random-1730297 \
  --data moderatorPW=mp \
  --data name=random-1730297 \
  --data record=false \
  --data `voiceBridge`=71296 \
  --data checksum=1234;

W następnej sekcji zostanie szczegółowo omówiona możliwość wysyłania również innych typów danych w ładunku.

Jeszcze jedną rzeczą, na którą warto zwrócić uwagę, jest nie umieszczanie żadnych parametrów zarówno w adresie URL, jak i w treści, w przeciwnym razie wyświetli się błąd checksum does not match:

<response>
<returncode>FAILED</returncode>
<messageKey>checksumError</messageKey>
<message>Checksums do not match</message>
</response>

Udostępnione notatki Początkowa treść

Możesz wysłać początkową treść udostępnionych notatek. Można tego dokonać za pomocą parametru create sharedNotesInitialContentJsonUrl zawierającego adres URL, z którego zostanie pobrana treść, lub wysłać treść bezpośrednio poprzez ładunek create.

Jeśli wybierzesz drugą opcję (bezpośrednie wysyłanie treści), ładunek żądania POST musi być następujący:

<modules>
   <module name="sharedNotesInitialContentJson">
      <![CDATA[
        [
          {
            "id": "00000000-0000-0000-0000-000000000000",
            "type": "paragraph",
            "props": {
              "textAlignment": "left",
              "backgroundColor": "default",
              "textColor": "default"
            },
            "content": [
              {
                "type": "text",
                "text": "Welcome to BigBlueButton Shared Notes! Start collaborating here...",
                "styles": {}
              }
            ],
            "children": []
          }
        ]
      ]]>
   </module>
</modules>

Zwróć szczególną uwagę: początkowa struktura JSON treści musi być zgodna z opisem w dokumentacji BlockNote. To samo dotyczy parametru create sharedNotesInitialContentJsonUrl (treść wewnątrz adresu URL musi mieć tę samą strukturę).

Alternatywnie, początkowa treść może być dostarczona w postaci zwykłego Markdown zamiast struktury BlockNote JSON. Markdown jest przenoszony w nienaruszonym stanie przez potok i konwertowany na bloki BlockNote na serwerze udostępnionych notatek przed umieszczeniem pustego dokumentu. Można to zapewnić na trzy sposoby:

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Oczekiwany format to surowy Markdown (nagłówki, listy, wyróżnienia itp.), a nie struktura BlockNote JSON.

Aby wysłać Markdown w treści POST, użyj tej samej koperty <modules>, co wariant JSON:

<modules>
   <module name="sharedNotesInitialContentMarkdown">
      <![CDATA[
# Welcome to BigBlueButton Shared Notes

Start collaborating here...

- First item
- Second item
      ]]>
   </module>
</modules>

Pierwszeństwo: początkowa treść BlockNote JSON ma pierwszeństwo przed Markdown. Jeśli podano zarówno JSON, jak i Markdown, JSON jest używany do zapełniania dokumentu, a Markdown jest używany tylko jako rezerwa, gdy JSON jest nieobecny, pusty lub nie można go przekonwertować na prawidłowy dokument. W ramach opcji Markdown najpierw rozwiązywany jest parametr tworzenia sharedNotesInitialContentMarkdownUrl, następnie wbudowany parametr tworzenia sharedNotesInitialContentMarkdown, a na końcu moduł POST.

Ograniczenia pobierania adresów URL: dwa warianty adresów URL (sharedNotesInitialContentJsonUrl i sharedNotesInitialContentMarkdownUrl) są pobierane przez serwer za pośrednictwem tej samej przypiętej do DNS, wzmocnionej ścieżki, która jest używana w przypadku adresów URL wtyczek, prezentacji i wywołań zwrotnych. Integratorzy muszą pamiętać o następujących kwestiach, ponieważ adres URL, który je narusza, po cichu generuje pustą treść początkową (spotkanie jest nadal tworzone):

• Tylko HTTPS. Domyślnie akceptowane są tylko adresy URL https (fetchUrlSupportedProtocols=https); adres URL http:// został odrzucony. Adresy lokalne, zwrotne, lokalne i lokalne dla łącza są zawsze blokowane. Użyj fetchUrlBlockedExternalHosts, aby zablokować dodatkowe hosty publiczne, lub fetchUrlAllowedLocalHosts, aby umożliwić określonym hostom wewnętrznym rozpoznawanie adresów prywatnych.
• Maksymalna ładowność Pobrana odpowiedź nie może przekraczać maxSharedNotesInitialContentUrlPayloadSize (domyślnie 1024 KiB). Większe odpowiedzi są odrzucane.
• Limit czasu. Limit czasu połączenia i gniazda wynosi 6000 ms; wolniejszy punkt końcowy jest traktowany jako nieudane pobranie.

Wstępne przesłanie slajdów

Możesz przesyłać slajdy w ramach połączenia tworzenia. Jeśli to zrobisz, serwer BigBlueButton natychmiast pobierze i przetworzy slajdy.

Możesz przekazać slajdy jako adres URL lub osadzić slajdy w base64 jako część żądania POST. Aby osadzić slajdy należy wysłać żądanie HTTPS POST (domyślnie całkowity rozmiar żądania POST nie może przekroczyć 2MB, więc osadzanie bardzo dużych slajdów nie będzie działać). Zasób URL musi być taki sam, jak opisano wcześniej.

W części treści należy dołączyć prosty kod XML, jak w przykładzie poniżej:

<modules>
   <module name="presentation">
      <document url="http://www.sample-pdf.com/sample.pdf" filename="report.pdf"/>
      <document name="sample-presentation.pdf">JVBERi0xLjQKJ....
        [clipped here]
        ....0CiUlRU9GCg==
      </document>
   </module>
</modules>

Jeśli chcesz dostarczyć dokument za pomocą adresu URL, a adres URL dokumentu nie zawiera rozszerzenia, możesz użyć parametru filename, takiego jak filename=test-results.pdf, aby pomóc serwerowi BigBlueButton określić typ pliku (w tym przykładzie będzie to plik PDF).

Od 2.5.x i nowszych można podać także 3 opcjonalne parametry, są to następujące parametry:

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

W ładunku zmienne są przekazywane wewnątrz każdego znacznika <document> pliku XML w następujący sposób:

<document downloadable="false" removable="true" url="http://www.sample-pdf.com/sample.pdf" filename="report.pdf"/>
<document removable="false" current="true" name="sample-presentation.pdf">JVBERi0xLjQKJ....
  [clipped here]
  ....0CiUlRU9GCg==
</document>

Pierwszy plik z wartością current="true" zostanie załadowany do klienta. Jeśli żaden plik nie ma wartości current="true", do klienta zostanie załadowany pierwszy. Przetwarzanie pozostałych dokumentów będzie kontynuowane w tle i będą one dostępne do wyświetlenia, gdy użytkownik wybierze jeden z nich u klienta.

Aby uzyskać więcej informacji na temat slajdów przed przesłaniem, sprawdź następujący link.

clientSettingsOverride

Obsługujemy nadpisywanie ustawień klienta (cały zestaw opcji znajdziesz w /usr/share/bigbluebutton/html5-client/private/config/settings.yml) w ramach wywołania CREATE. Należy pamiętać, że te wartości będą miały wyższy priorytet w stosunku do dostosowań dokonanych w /etc/bigbluebutton/bbb-html5.yml.

Domyślnie to podejście zastępujące przy UTWÓRZ jest wyłączone. Aby to włączyć, ustaw allowOverrideClientSettingsOnCreateCall=true w /etc/bigbluebutton/bbb-web.properties i zrestartuj bbb-web. Jest to ustawienie tylko po stronie serwera — nie jest odczytywane z żądania utworzenia, więc przekazanie allowOverrideClientSettingsOnCreateCall jako parametru /create nie ma żadnego efektu.

Ponieważ treść POST nie jest objęta /create sumą kontrolną, należy włączyć tę opcję tylko na serwerach, na których podpisane parametry żądania utworzenia nie są widoczne dla użytkowników. Jako alternatywę, która utrzymuje ustawienia parametru GET z sumą kontrolną, zobacz clientSettingsOverrideJsonUrl, który nie wymaga allowOverrideClientSettingsOnCreateCall.

Możesz skonstruować żądanie HTTPS POST w następujący sposób:

curl -s -X POST "$URL/$CONTROLLER?$PARAMS&checksum=$CHECKSUM" --header "Content-Type: application/xml" --data '
<modules>
   <module name="clientSettingsOverride">
         <![CDATA[
         {
            "public": {
               "kurento": {
                  "wsUrl": "wss://test.bigbluebutton.org/bbb-webrtc-sfu"
               },
               "app": {
                    "appName": "Test",
                    "helpLink": "https://www.bigbluebutton.org",
                    "autoJoin": false,
                    "askForConfirmationOnLeave": false,
                    "userSettingsStorage": "localStorage",
                    "defaultSettings": {
                     "application": {
                        "overrideLocale": "en"
                     }
                    }
                }
            }
         }
         ]]>
   </module>
</modules>'

Prześlij slajdy z aplikacji zewnętrznej do aktywnej sesji BigBlueButton

W przypadku aplikacji zewnętrznych, które integrują się z BigBlueButton przy użyciu wywołania API insertDocument, parametrów presentationUploadExternalUrl i presentationUploadExternalDescription można użyć w wywołaniu API create w celu wyświetlenia przycisku i komunikatu na dole okna dialogowego przesyłania prezentacji.

Kliknięcie tego przycisku spowoduje otwarcie adresu URL w nowej karcie, która pokazuje selektor plików dla aplikacji zewnętrznej. Użytkownik może następnie wybrać pliki w aplikacji zewnętrznej i zostaną one przesłane do sesji na żywo.

Spotkanie zakończone Adres URL wywołania zwrotnego

Możesz poprosić serwer BigBlueButton o wykonanie oddzwonienia do Twojej aplikacji po zakończeniu spotkania. Po otrzymaniu wywołania zwrotnego Twoja aplikacja może na przykład zmienić interfejs użytkownika, aby ukryć przycisk „dołącz”.

Aby określić wywołanie zwrotne do BigBlueButton, przekaż adres URL za pomocą parametru meetingEndedURL w żądaniu create. Kiedy serwer BigBlueButton zakończy spotkanie, wyśle ​​żądanie HTTP GET do przekazanego adresu URL.

BigBlueButton doda dodatkowy parametr zapytania recordingmarks=true|false, , który podpowie, czy dla spotkania zostanie wygenerowane nagranie. Wartość będzie wynosić true jeśli spotkanie było ustawione na nagrywanie (record=true zostało przekazane przy wywołaniu tworzenia API) i nagrywanie zostało rozpoczęte podczas sesji na żywo (moderator kliknął przycisk Rozpocznij/Zatrzymaj nagrywanie podczas spotkania, W wywołaniu tworzenia przekazano lub autoStartRecording=true).

Na przykład, aby określić adres URL wywołania zwrotnego jako

https://myapp.example.com/meetingEndedCallback?token=a817dde5-0a18-43ad-9016-2d5d4c758a50

dodaj następujący parametr do wywołania API create:

&meetingEndedURL=https%3A%2F%2Fmyapp.example.com%2FmeetingEndedCallback%3Ftoken%3Da817dde5-0a18-43ad-9016-2d5d4c758a50

(pamiętaj, że adres URL wywołania zwrotnego musi być zakodowany w formacie URL). Rzeczywisty adres URL, pod którym zostanie wykonane wywołanie zwrotne, będzie wyglądał następująco:

https://myapp.example.com/meetingEndedCallback?token=a817dde5-0a18-43ad-9016-2d5d4c758a50&recordingmarks=true

Ze względów bezpieczeństwa adres URL wywołania zwrotnego generowany przez aplikację powinien być w jakiś sposób uwierzytelniony, , aby uniemożliwić złośliwym użytkownikom powodowanie przez aplikację myślenia, że ​​spotkanie się zakończyło, gdy jest jeszcze uruchomiona. Zalecanym sposobem jest dodanie do adresu URL niemożliwego do odgadnięcia parametru , a następnie zweryfikowanie tego parametru po otrzymaniu żądania oddzwonienia. Na przykład możesz dołączyć losowo wygenerowany jednorazowy token lub podpisane roszczenie w JWT. Zdecydowanie zalecamy używanie adresów URL https.

Funkcja ta była wcześniej zaimplementowana przy użyciu parametrów o nazwie meta_endCallbackUrl, , których aplikacje nie powinny już używać. Parametry meta_* mogą zostać ujawnione użytkownikom podczas spotkania, może spowodować wyciek tajnego tokena lub podpisanych parametrów, które aplikacja umieściła w adresie URL.

Adres URL wywołania zwrotnego panelu Learning Analytics

Możesz poprosić serwer BigBlueButton o wykonanie oddzwonienia do Twojej aplikacji po zakończeniu spotkania. Po otrzymaniu wywołania zwrotnego aplikacja może pobrać i zapisać dane z panelu Learning Analytics w celu długoterminowego przechowywania, analizy lub integracji z własnym systemem zarządzania nauczaniem.

Aby określić wywołanie zwrotne do BigBlueButton, przekaż adres URL za pomocą metaparametru meta_analytics-callback-url w poleceniu create. Gdy serwer BigBlueButton zakończy spotkanie, sprawdzi czy ustawiono meta_analytics-callback-url i jeśli tak, wyśle ​​żądanie HTTP POST na podany adres URL.

Na przykład, aby określić adres URL wywołania zwrotnego jako

  https://myapp.example.com/analytics-callback?meetingID=test01

dodaje następujący parametr do wywołania API create: &meta_analytics-callback-url=https%3A%2F%2Fmyapp.example.com%2Fanalytics-callback%3FmeetingID%3Dtest01 (pamiętaj, że adres URL wywołania zwrotnego analizy musi być zakodowany w formacie URL).

Wywołanie zwrotne będzie żądaniem POST z treścią JSON zawierającą pełne dane analityczne. Struktura JSON obejmuje:

Pola najwyższego poziomu:

• version - wersja API (np. "1.0")
• meeting_id - Identyfikator spotkania podany podczas tworzenia spotkania
• internal_meeting_id - Identyfikator spotkania wewnętrznego używany przez BigBlueButton
• data - Obiekt zawierający wszystkie dane analityczne (patrz poniżej)

Struktura obiektu danych:

• metadata - Metadane spotkania zawierające:
• analytics_callback_url - Adres URL wywołania zwrotnego, który został skonfigurowany
• is_breakout - Czy był to pokój podgrupy („prawda”/„fałsz”)
• meeting_name - Nazwa spotkania
• Dodatkowe niestandardowe pola metadanych przekazane podczas tworzenia spotkania
• duration - Całkowity czas trwania spotkania w sekundach
• start - Znacznik czasu rozpoczęcia spotkania (ISO 8601)
• finish - Znacznik czasu zakończenia spotkania (format ISO 8601)
• attendees - Tablica obiektów uczestników, każdy zawierający:
• ext_user_id - Zewnętrzny identyfikator użytkownika
• name - Wyświetlana nazwa użytkownika
• moderator - Wartość logiczna wskazująca, czy użytkownik był moderatorem
• joins - Tablica znaczników czasu dołączenia
• leaves — Tablica znaczników czasu opuszczenia — duration — Całkowity czas spędzony przez użytkownika na spotkaniu (w sekundach) — recent_talking_time — Ostatnia aktywność związana z rozmowami — engagement — Obiekt z zaangażowaniem metryki:
• chats - Liczba wysłanych wiadomości na czacie
• talks - Liczba zdarzeń rozmów
• raisehand - Liczba podniesionych rąk
• emojis – Liczba reakcji emoji – poll_votes – Liczba oddanych głosów w ankietach – talk_time – Całkowity czas rozmów w sekundach – sessions – Tablica obiektów sesji ze szczegółowymi informacjami dołącz/opuść wydarzenia
• files - Tablica plików prezentacji używanych podczas spotkania
• polls - Tablica obiektów ankiety z danymi ankiety i wynikami

Przykładowy ładunek:

{
  "version": "1.0",
  "meeting_id": "random-1397955",
  "internal_meeting_id": "82de1f45d28e38b6ab1e304aa39bfece5700cb64-1769423218203",
  "data": {
    "metadata": {
      "analytics_callback_url": "https://myapp.example.com/analytics-callback",
      "is_breakout": "false",
      "meeting_name": "My Meeting"
    },
    "duration": 16,
    "start": "2026-01-26T11:26:58.000+01:00",
    "finish": "2026-01-26T11:27:14.000+01:00",
    "attendees": [
      {
        "ext_user_id": "w_vi6djg93icce",
        "name": "John Doe",
        "moderator": true,
        "joins": ["2026-01-26T11:27:02.000+01:00"],
        "leaves": ["2026-01-26T11:27:14.000+01:00"],
        "duration": 12,
        "engagement": {
          "chats": 1,
          "talks": 0,
          "raisehand": 0,
          "emojis": 0,
          "poll_votes": 0,
          "talk_time": 0
        }
      }
    ],
    "files": ["presentation.pdf"],
    "polls": []
  }
}

Adres URL wywołania zwrotnego gotowy do nagrywania

Możesz poprosić serwer BigBlueButton o wykonanie oddzwonienia do Twojej aplikacji, gdy nagranie spotkania będzie gotowe do przeglądania. Po otrzymaniu oddzwonienia Twoja aplikacja może na przykład wysłać do prezentera wiadomość e-mail z powiadomieniem, że nagranie jest gotowe.

Aby określić wywołanie zwrotne do BigBlueButton, przekaż adres URL za pomocą metaparametru meta_bbb-recording-ready-url w poleceniu create. Później, gdy serwer BigBlueButton zakończy przetwarzanie nagrania, sprawdzi, czy ustawiono meta_bbb-recording-ready-url i jeśli tak, wykona żądanie HTTP POST na podany adres URL.

Na przykład, biorąc pod uwagę adres URL wywołania zwrotnego

https://example.com/api/v1/recording_status

, aby przekazać to do BigBlueButton, dodaj następujący parametr do wywołania API create: &meta_bbb-recording-ready-url=https%3A%2F%2Fexample.com%2Fapi%2Fv1%2Frecording_status (pamiętaj, że adres URL wywołania zwrotnego musi być zakodowany w formacie URL).

Później, gdy nagranie będzie gotowe, serwer BigBlueButton wyśle ​​żądanie HTTPS POST do tego adresu URL (https jest obsługiwany i zalecany).

Treść żądania POST będzie w standardowym formacie application/x-www-form-urlencoded. Treść będzie zawierać jeden parametr o nazwie signed_parameters. Wartość tego parametru to ciąg zakodowany w formacie JWT (JSON Web Tokens).

JWT będzie kodowany przy użyciu metody „HS256”. (tj. nagłówek powinien mieć postać { "typ": "JWT", "alg": "HS256" } ). Ładunek będzie zawierał następujące klucze JSON:

• meeting_id - wartością będzie spotkanie_id (zgodnie z wywołaniem API tworzenia BigBlueButton).
• record_id - Identyfikator konkretnego nagrania, którego dotyczy powiadomienie. Odpowiada to identyfikatorom zwróconym w interfejsie API getRecordings i polu internalMeetingId w żądaniu getMeetingInfo.

Sekret użyty do podpisania wiadomości JWT będzie wspólnym sekretem punktu końcowego API BigBlueButton, który został użyty do utworzenia pierwotnego spotkania.

Odbierający punkt końcowy powinien odpowiedzieć jednym z poniższych kodów HTTP, aby wskazać status, jak opisano poniżej. Każda podana treść odpowiedzi zostanie zignorowana, chociaż może zostać zarejestrowana w ramach obsługi błędów.

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Wszystkie pozostałe kody odpowiedzi HTTP będą traktowane jako błędy przejściowe.

GET join

Dołącza użytkownika do spotkania określonego w parametrze MeetingID.

URL zasobu:

http://yourserver.com/bigbluebutton/api/join?[parameters]&checksum=[checksum]

Parametry:

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Przykładowe żądania:

• http:///yourserver.com/bigbluebutton/api/join?meetingID=test01&role=moderator&fullName=John&checksum=1234
• http://yourserver.com/bigbluebutton/api/join?meetingID=test01&role=viewer&fullName=Mark&checksum=wxyz
• http:///yourserver.com/bigbluebutton/api/join?meetingID=test01&role=viewer&fullName=Chris&createTime=273648&checksum=abcd

Przykładowa odpowiedź:

Odpowiedź XML dla tego wywołania istnieje tylko wtedy, gdy parametr redirect jest ustawiony na false. Powinieneś po prostu przekierować użytkownika na adres URL połączenia, a on zostanie dodany do spotkania.

<response>
  <returncode>SUCCESS</returncode>
  <messageKey>successfullyJoined</messageKey>
  <message>You have joined successfully.</message>
  <meeting_id>640ab2bae07bedc4c163f679a746f7ab7fb5d1fa-1531155809613</meeting_id>
  <user_id>w_euxnssffnsbs</user_id>
  <auth_token>14mm5y3eurjw</auth_token>
  <session_token>ai1wqj8wb6s7rnk0</session_token>
  <url>https://yourserver.com/client/BigBlueButton.html?sessionToken=ai1wqj8wb6s7rnk0</url>
</response>

Zobacz Przekazywanie metadanych użytkownika do klienta przy dołączaniu, aby uzyskać dodatkowe parametry join, które mogą zastąpić ustawienia domyślne użytkownika.

POST insertDocument

Ten punkt końcowy wstawia jeden lub więcej dokumentów do działającego spotkania poprzez wywołanie API.

Dokumenty są pobierane i konwertowane w tle: odpowiedź SUCCESS oznacza, że ​​wniosek został zaakceptowany, a nie, że dokumenty są już dostępne na spotkaniu. Błędy pobierania lub konwersji — a w przypadku przeciążenia serwera zadania odrzucone z powodu przepełnienia puli pobierania w tle — są zgłaszane klientom spotkania (i dziennikowi serwera), a nie w odpowiedzi interfejsu API. To samo dotyczy prezentacji przesłanych wcześniej poprzez wywołanie create (preUploadedPresentation lub treść żądania z modułem presentation).

URL zasobu:

https://yourserver.com/bigbluebutton/api/insertDocument?[parameters]&checksum=[checksum]

Parametry:

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Przykładowe żądania:

Możesz wykonać żądanie albo poprzez zielone światło, albo poprzez curl, co zademonstruję w następnym akapicie.

Najpierw należy mieć pod ręką ciąg xml z partią żądanych prezentacji. Jako przykład zobacz plik XML poniżej:

<modules>
   <module name="presentation">
        <document current="true" downloadable="true" url="{link to download the presentation}" filename="sample.pdf"/>
        <document removable="false" name="sample.pdf">
          JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAoT3RoZXJfc2FtcGxlKQovUHJvZHVjZXIgKFNraWEvUERGIG0xMDAgR29vZ2xlIERvY3MgUmVuZGVyZXIpPj4KZW5... {base64 encoded document}
        </document>
   </module>
</modules>

Teraz musisz napisać komendę curl, która będzie brzmiała:

curl -s -X POST "https://{your-host}/bigbluebutton/api/insertDocument?meetingID=Test&checksum=6b76e90b9a20481806a7ef513bc81ef0299609ed" --header "Content-Type: application/xml" --data '{xml}'

Łącząc oba razem, otrzymujemy:

curl -s -X POST "https://{your-host}/bigbluebutton/api/insertDocument?meetingID=Test&checksum=6b76e90b9a20481806a7ef513bc81ef0299609ed" --header "Content-Type: application/xml" --data '<modules>
   <module name="presentation">
        <document current="true" downloadable="true" url="{link to download the presentation}" filename="sample.pdf"/>
        <document removable="false" name="sample.pdf">
        JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAoT3RoZXJfc2FtcGxlKQovUHJvZHVjZXIgKFNraWEvUERGIG0xMDAgR29vZ2xlIERvY3MgUmVuZGVyZXIpPj4KZW5... {base64 encoded document}
        </document>
   </module>
</modules>'

Istnieje również możliwość przekazywania zmiennych wymiennych, możliwych do pobrania i bieżących wewnątrz ładunku. Są one umieszczane w znaczniku document, jak już pokazano. Sposób działania jest dokładnie taki sam jak w przypadku (POST) tworzenia punktu końcowego

GET POST isMeetingRunning

To call umożliwia proste sprawdzenie, czy spotkanie się toczy, sprawdzając je za pomocą identyfikatora spotkania.

URL zasobu:

http://yourserver.com/bigbluebutton/api/isMeetingRunning?[parameters]&checksum=[checksum]

Parametry:

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Przykładowe żądania:

http://yourserver.com/bigbluebutton/api/isMeetingRunning?meetingID=test01&checksum=1234

Przykładowa odpowiedź:

<response>
  <returncode>SUCCESS</returncode>
  <running>true</running>
</response>

Uruchomienie może mieć wartość „prawda” lub „fałsz”, co sygnalizuje, czy spotkanie o tym identyfikatorze jest aktualnie uruchomione.

GET POST end

Użyj tej opcji, aby wymusić zakończenie spotkania i wyrzucić wszystkich uczestników ze spotkania.

URL zasobu:

• http://yourserver.com/bigbluebutton/api/end?[parametry]&checksum=[suma kontrolna]

Parametry:

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Przykładowe żądania:

• http://yourserver.com/bigbluebutton/api/end?meetingID=1234567890&checksum=1234

Przykład Odpowiedź:

<response>
  <returncode>SUCCESS</returncode>
  <messageKey>sentEndMeetingRequest</messageKey>
  <message>
    A request to end the meeting was sent.  Please wait a few seconds, and then use the getMeetingInfo or isMeetingRunning API calls to verify that it was ended
  </message>
</response>

Żądanie POST

Podobnie jak w przypadku utwórz żądanie, możesz wysłać POST w celu zakończenia spotkania, składnia jest prawie taka sama, patrz przykład poniżej:

curl --request POST \
	--url https://<your-host>/bigbluebutton/api/end \
	--header 'Content-Type: application/x-www-form-urlencoded' \
	--data meetingID=Test+Meeting \
	--data checksum=1234

WAŻNA UWAGA: Należy pamiętać, że zakończenie spotkania oznacza po prostu wysłanie żądania do serwera zaplecza, który obsługuje cały ruch konferencyjny. Ten serwer zaplecza natychmiast spróbuje wysłać każdemu podłączonemu klientowi zdarzenie wylogowania, wyrzucając go ze spotkania. Spowoduje to ich rozłączenie, a spotkanie zostanie zakończone. Może to jednak zająć kilka sekund, w zależności od warunków sieciowych. Dlatego połączenie kończące spotkanie zakończy się sukcesem natychmiast po wysłaniu żądania. Aby jednak mieć pewność, że zostało ono zakończone, należy sprawdzić ponownie kilka sekund później, korzystając z wywołań getMeetingInfo lub isMeetingRunning, aby sprawdzić, czy wszyscy uczestnicy opuścili spotkanie i czy zakończyło się ono pomyślnie.

GET POST getMeetingInfo

To wywołanie zwróci wszystkie informacje o spotkaniu, w tym listę uczestników oraz godzinę rozpoczęcia i zakończenia.

Adres URL zasobu:

• http://yourserver.com/bigbluebutton/api/getMeetingInfo?[parametry]&suma kontrolna=[suma kontrolna]

Parametry:

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Przykładowe żądania:

• http://yourserver.com/bigbluebutton/api/getMeetingInfo?meetingID=test01&checksum=1234

Przykładowa odpowiedź:

<response>
	<returncode>SUCCESS</returncode>
	<meetingName>Anton G's Room</meetingName>
	<meetingID>gbesu6dht08uobpislzqxsizjzihn87cmewqyacs</meetingID>
	<internalMeetingID>a0715c95000a2bcb90604ecc7097dbc94592c690-1715261728123</internalMeetingID>
	<createTime>1715261728123</createTime>
	<createDate>Thu May 09 13:35:28 UTC 2024</createDate>
	<voiceBridge>66052</voiceBridge>
	<dialNumber>613-555-1234</dialNumber>
	<attendeePW>1umEM3ic</attendeePW>
	<moderatorPW>V91JirCa</moderatorPW>
	<running>true</running>
	<duration>0</duration>
	<hasUserJoined>true</hasUserJoined>
	<recording>true</recording>
	<hasBeenForciblyEnded>false</hasBeenForciblyEnded>
	<startTime>1715261728142</startTime>
	<endTime>0</endTime>
	<participantCount>1</participantCount>
	<listenerCount>0</listenerCount>
	<voiceParticipantCount>1</voiceParticipantCount>
	<videoCount>1</videoCount>
	<maxUsers>0</maxUsers>
	<moderatorCount>1</moderatorCount>
	<attendees>
		<attendee>
			<userID>w_ftcrsyuh44oj</userID>
			<fullName>Anton G</fullName>
			<role>MODERATOR</role>
			<isPresenter>true</isPresenter>
			<isListeningOnly>false</isListeningOnly>
			<hasJoinedVoice>true</hasJoinedVoice>
			<hasVideo>true</hasVideo>
			<clientType>HTML5</clientType>
			<customdata></customdata>
		</attendee>
	</attendees>
	<metadata>
		<bbb-origin-version>summit2024-6d8120x</bbb-origin-version>
		<bbb-origin-server-name>test30.bigbluebutton.org</bbb-origin-server-name>
		<bbb-recording-ready-url>https://test30.bigbluebutton.org/recording_ready</bbb-recording-ready-url>
		<bbb-origin>greenlight</bbb-origin>
		<endcallbackurl>https://test30.bigbluebutton.org/meeting_ended</endcallbackurl>
	</metadata>
	<isBreakout>false</isBreakout>
</response>

Jeśli w ramach spotkania powstały pokoje podgrup, getMeetingInfo wyświetli także listę identyfikatorów spotkań dla pokojów podgrup.

 <response>
  <returncode>success</returncode>
  ...
     <breakoutRooms>
        <breakout>breakout-room-id-1</breakout>
        <breakout>breakout-room-id-2</breakout>
        <breakout>breakout-room-id-3</breakout>
     </breakoutRooms>
 </response>

Jeśli spotkanie samo w sobie jest pokojem podgrupy, getMeetingInfo zwróci również link do identyfikatora spotkania nadrzędnego.

<response>
  <returncode>success</returncode>
  ...
    <breakout>
     <parentMeetingID>ParentMeetingId</parentMeetingID>
     <sequence>1</sequence>
     <freeJoin>false</freeJoin>
    </breakout>
 </response>

GET POST getMeetings

To wywołanie zwróci listę wszystkich spotkań znalezionych na tym serwerze.

URL zasobu:

http://yourserver.com/bigbluebutton/api/getMeetings?checksum=[checksum]

Parametry:

Od wersji BigBlueButton 0.80 nie jest już wymagane przekazywanie żadnego parametru dla tego wywołania.

Przykładowe żądania:

http://yourserver.com/bigbluebutton/api/getMeetings?checksum=1234

Przykładowa odpowiedź:

<response>
  <returncode>SUCCESS</returncode>
  <meetings>
    <meeting>
      <meetingName>Demo Meeting</meetingName>
      <meetingID>Demo Meeting</meetingID>
      <internalMeetingID>183f0bf3a0982a127bdb8161e0c44eb696b3e75c-1531241258036</internalMeetingID>
      <createTime>1531241258036</createTime>
      <createDate>Tue Jul 10 16:47:38 UTC 2018</createDate>
      <`voiceBridge`>70066</`voiceBridge`>
      <dialNumber>613-555-1234</dialNumber>
      <attendeePW>ap</attendeePW>
      <moderatorPW>mp</moderatorPW>
      <running>false</running>
      <duration>0</duration>
      <hasUserJoined>false</hasUserJoined>
      <recording>false</recording>
      <hasBeenForciblyEnded>false</hasBeenForciblyEnded>
      <startTime>1531241258074</startTime>
      <endTime>0</endTime>
      <participantCount>0</participantCount>
      <listenerCount>0</listenerCount>
      <voiceParticipantCount>0</voiceParticipantCount>
      <videoCount>0</videoCount>
      <maxUsers>0</maxUsers>
      <moderatorCount>0</moderatorCount>
      <attendees />
      <metadata />
      <isBreakout>false</isBreakout>
    </meeting>
  </meetings>
</response>

GET getRecordings

Pobiera nagrania, które są dostępne do odtwarzania dla danego identyfikatora spotkania (lub zestawu identyfikatorów spotkania). W wersji 2.6 dodano obsługę paginacji. Od wersji 2.7, gdy w odpowiedzi włączona jest paginacja, poprzez użycie parametrów limitu i/lub przesunięcia, całkowita liczba nagrań spełniających podane kryteria zostanie zwrócona za pośrednictwem znacznika totalElements.

URL zasobu:

http://yourserver.com/bigbluebutton/api/getRecordings?[parameters]&checksum=[checksum]

Parametry:

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Przykładowe żądania:

• http://yourserver.com/bigbluebutton/api/getRecordings?checksum=1234
• http://yourserver.com/bigbluebutton/api/getRecordings?meetingID=CS101&checksum=abcd
• http://yourserver.com/bigbluebutton/api/getRecordings?meetingID=CS101,CS102&checksum=wxyz
• http:///yourserver.com/bigbluebutton/api/getRecordings?recordID=652c9eb4c07ad49283554c76301d68770326bd93-1462283509434&checksum=wxyz
• http:///yourserver.com/bigbluebutton/api/getRecordings?recordID=652c9eb4c07ad49283554c76301d68770326bd93-146228 3509434,9e359d17635e163c4388281567601d7fecf29df8-1461882579628&suma kontrolna=wxyz
• http:///yourserver.com/bigbluebutton/api/getRecordings?recordID=652c9eb4c07ad49283554c76301d68770326bd93&checksum=wxyz
• http:///yourserver.com/bigbluebutton/api/getRecordings?recordID=652c9eb4c07ad49283554c76301d68770326bd93,9e359d17635e163c4388281567601d7fecf29df8&checksum=wxyz
• http://yourserver.com/bigbluebutton/api/getRecordings?state=published&offset=20&limit=10&checksum=abc123

Przykładowa odpowiedź:

Tutaj wywołanie API getRecordings zwróciło dwa nagrania spotkania o identyfikatorze c637ba21adcd0191f48f5c4bf23fab0f96ed5c18. Każde nagranie miało dwa formaty: podcast i presentation.

<response>
   <returncode>SUCCESS</returncode>
   <recordings>
      <recording>
         <recordID>ffbfc4cc24428694e8b53a4e144f414052431693-1530718721124</recordID>
         <meetingID>c637ba21adcd0191f48f5c4bf23fab0f96ed5c18</meetingID>
         <internalMeetingID>ffbfc4cc24428694e8b53a4e144f414052431693-1530718721124</internalMeetingID>
         <name>Fred's Room</name>
         <isBreakout>false</isBreakout>
         <published>true</published>
         <state>published</state>
         <startTime>1530718721124</startTime>
         <endTime>1530718810456</endTime>
         <participants>3</participants>
         <metadata>
            <isBreakout>false</isBreakout>
            <meetingName>Fred's Room</meetingName>
            <gl-listed>false</gl-listed>
            <meetingId>c637ba21adcd0191f48f5c4bf23fab0f96ed5c18</meetingId>
         </metadata>
         <playback>
            <format>
               <type>podcast</type>
               <url>https://demo.bigbluebutton.org/podcast/ffbfc4cc24428694e8b53a4e144f414052431693-1530718721124/audio.ogg</url>
               <processingTime>0</processingTime>
               <length>0</length>
            </format>
            <format>
               <type>presentation</type>
               <url>https://demo.bigbluebutton.org/playback/presentation/2.0/playback.html?meetingId=ffbfc4cc24428694e8b53a4e144f414052431693-1530718721124</url>
               <processingTime>7177</processingTime>
               <length>0</length>
               <preview>
                  <images>
                     <image alt="Welcome to" height="136" width="176">https://demo.bigbluebutton.org/presentation/ffbfc4cc24428694e8b53a4e144f414052431693-1530718721124/presentation/d2d9a672040fbde2a47a10bf6c37b6a4b5ae187f-1530718721134/thumbnails/thumb-1.png</image>
                     <image alt="(this slide left blank for use as a whiteboard)" height="136" width="176">https://demo.bigbluebutton.org/presentation/ffbfc4cc24428694e8b53a4e144f414052431693-1530718721124/presentation/d2d9a672040fbde2a47a10bf6c37b6a4b5ae187f-1530718721134/thumbnails/thumb-2.png</image>
                     <image alt="(this slide left blank for use as a whiteboard)" height="136" width="176">https://demo.bigbluebutton.org/presentation/ffbfc4cc24428694e8b53a4e144f414052431693-1530718721124/presentation/d2d9a672040fbde2a47a10bf6c37b6a4b5ae187f-1530718721134/thumbnails/thumb-3.png</image>
                  </images>
               </preview>
            </format>
         </playback>
      </recording>
      <recording>
         <recordID>ffbfc4cc24428694e8b53a4e144f414052431693-1530278898111</recordID>
         <meetingID>c637ba21adcd0191f48f5c4bf23fab0f96ed5c18</meetingID>
         <internalMeetingID>ffbfc4cc24428694e8b53a4e144f414052431693-1530278898111</internalMeetingID>
         <name>Fred's Room</name>
         <isBreakout>false</isBreakout>
         <published>true</published>
         <state>published</state>
         <startTime>1530278898111</startTime>
         <endTime>1530281194326</endTime>
         <participants>7</participants>
         <metadata>
            <meetingName>Fred's Room</meetingName>
            <isBreakout>false</isBreakout>
            <gl-listed>true</gl-listed>
            <meetingId>c637ba21adcd0191f48f5c4bf23fab0f96ed5c18</meetingId>
         </metadata>
         <playback>
            <format>
               <type>podcast</type>
               <url>https://demo.bigbluebutton.org/podcast/ffbfc4cc24428694e8b53a4e144f414052431693-1530278898111/audio.ogg</url>
               <processingTime>0</processingTime>
               <length>33</length>
            </format>
            <format>
               <type>presentation</type>
               <url>https://demo.bigbluebutton.org/playback/presentation/2.0/playback.html?meetingId=ffbfc4cc24428694e8b53a4e144f414052431693-1530278898111</url>
               <processingTime>139458</processingTime>
               <length>33</length>
               <preview>
                  <images>
                     <image width="176" height="136" alt="Welcome to">https://demo.bigbluebutton.org/presentation/ffbfc4cc24428694e8b53a4e144f414052431693-1530278898111/presentation/d2d9a672040fbde2a47a10bf6c37b6a4b5ae187f-1530278898120/thumbnails/thumb-1.png</image>
                     <image width="176" height="136" alt="(this slide left blank for use as a whiteboard)">https://demo.bigbluebutton.org/presentation/ffbfc4cc24428694e8b53a4e144f414052431693-1530278898111/presentation/d2d9a672040fbde2a47a10bf6c37b6a4b5ae187f-1530278898120/thumbnails/thumb-2.png</image>
                     <image width="176" height="136" alt="(this slide left blank for use as a whiteboard)">https://demo.bigbluebutton.org/presentation/ffbfc4cc24428694e8b53a4e144f414052431693-1530278898111/presentation/d2d9a672040fbde2a47a10bf6c37b6a4b5ae187f-1530278898120/thumbnails/thumb-3.png</image>
                  </images>
               </preview>
            </format>
         </playback>
      </recording>
   </recordings>
</response>

Przykładowa odpowiedź podzielona na strony:

<response>
    <returncode>SUCCESS</returncode>
    <recordings>
        ...
    </recordings>
    <totalElements>3</totalElements>
</response>

GET publishRecordings

Publikuj i cofaj publikację nagrań dla danego identyfikatora rekordu (lub zestawu identyfikatorów rekordu).

URL zasobu:

• http://yourserver.com/bigbluebutton/api/publishRecordings?[parametry]&checksum=[suma kontrolna]

Parametry:

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Przykładowe żądania:

• http://yourserver.com/bigbluebutton/api/publishRecordings?recordID=record123&publish=true&checksum=1234
• http://yourserver.com/bigbluebutton/api/publishRecordings?recordID=record123,recordABC&publish=true&checksum=wxyz

Przykładowa odpowiedź:

<response>
  <returncode>SUCCESS</returncode>
  <published>true</published>
</response>

GET deleteRecordings

Usuń jedno lub więcej nagrań dla danego identyfikatora rekordu (lub zestawu identyfikatorów rekordu).

URL zasobu:

http://yourserver.com/bigbluebutton/api/deleteRecordings?[parameters]&checksum=[checksum]

Parametry:

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Przykładowe żądania:

• http:///yourserver.com/bigbluebutton/api/deleteRecordings?recordID=record123&checksum=1234
• http://yourserver.com/bigbluebutton/api/deleteRecordings?recordID=record123,recordABC&checksum=wxyz

Przykładowa odpowiedź:

<response>
  <returncode>SUCCESS</returncode>
  <deleted>true</deleted>
</response>

GET POST updateRecordings

Aktualizacja metadanych dla danego identyfikatora rekordu (lub zestawu identyfikatorów rekordu). Dostępne od wersji 1.1

URL zasobu:

• http://yourserver.com/bigbluebutton/api/updateRecordings?[parametry]&suma kontrolna=[suma kontrolna]

Parametry:

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Przykładowe żądania:

• http://yourserver.com/bigbluebutton/api/updateRecordings?recordID=record123&meta_Presenter=Jane%20Doe,meta_category=FINANSE,meta_TERM=Fall2016&checksum=1234

Przykładowa odpowiedź:

<response>
  <returncode>SUCCESS</returncode>
  <updated>true</updated>
</response>

GET POST getRecordingTextTracks

Uzyskaj listę plików podpisów/napisów aktualnie dostępnych dla nagrania. Będzie zawierać informacje o napisach (język itp.), a także link do pobrania. Może to być przydatne do pobierania napisów na żywo lub automatycznie transkrybowanych z nagrania w celu ręcznej edycji.

URL zasobu:

GET http://yourserver.com/bigbluebutton/api/getRecordingTextTracks?[parameters]&checksum=[checksum]

Parametry:

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Przykładowa odpowiedź:

Przykładowa odpowiedź wygląda następująco:

{
  "response": {
    "returncode": "SUCCESS",
    "tracks": [
      {
        "href": "https://captions.example.com/textTrack/0ab39e419c9bcb63233168daefe390f232c71343/183f0bf3a0982a127bdb8161e0c44eb696b3e75c-1554230749920/subtitles_en-US.vtt",
        "kind": "subtitles",
        "label": "English",
        "lang": "en-US",
        "source": "upload"
      },
      {
        "href": "https://captions.example.com/textTrack/95b62d1b762700b9d5366a9e71d5fcc5086f2723/183f0bf3a0982a127bdb8161e0c44eb696b3e75c-1554230749920/subtitles_pt-BR.vtt",
        "kind": "subtitles",
        "label": "Brazil",
        "lang": "pt-BR",
        "source": "upload"
      }
    ]
  }
}

Obiekt ścieżki ma następujące atrybuty:

rodzaj

: Wskazuje przeznaczenie ścieżki tekstowej. Wartością będzie jeden z następujących ciągów znaków: napisy

podpisy

: Znaczenie tych wartości jest określone przez element wideo HTML5. Szczegóły znajdziesz w dokumentacji MDN. Należy pamiętać, że specyfikacja HTML5 definiuje dodatkowe wartości, które nie są obecnie tutaj używane, ale mogą zostać dodane w późniejszym terminie.

lang : Język ścieżki tekstowej, jako znacznik języka. Szczegółowe informacje na temat formatu można znaleźć w dokumencie RFC 5646 oraz w wyszukiwaniu podtagów języka, aby uzyskać pomoc w ich używaniu. Zwykle składa się z 2-3-literowego kodu języka pisanego małymi literami, po którym opcjonalnie następuje myślnik i 2-3-literowego kodu regionu geograficznego (kod kraju) pisanego wielkimi literami.

etykieta : Czytelna dla człowieka etykieta ścieżki tekstowej. Jest to ciąg wyświetlany na liście wyboru napisów podczas odtwarzania nagrania.

źródło : Wskazuje, skąd pochodzi utwór. Wartością będzie jeden z następujących ciągów znaków:

• na żywo - Ścieżka z napisami pochodząca z napisów na żywo wykonywanych w BigBlueButton.
• automatyczny - Ścieżka napisów generowana automatycznie poprzez komputerowe rozpoznawanie głosu.
• przesyłanie - Ścieżka napisów przesłana przez stronę trzecią.

href : Link do pobrania tego pliku tekstowego. Formatem będzie zawsze WebVTT (typ mime tekst/vtt), który jest podobny do formatu SRT.

Czas odtwarzania utworu będzie odpowiadał bieżącemu odtwarzaniu plików wideo i audio. Należy pamiętać, że jeśli nagranie zostanie poddane edycji (dostosowanie znaczników wejścia/wyjścia), ścieżki ze źródeł na żywo lub źródeł automatycznych zostaną odtworzone z nowym taktowaniem. Przesłane utwory zostaną poddane edycji, ale może to spowodować utratę danych, jeśli podczas edycji zostaną usunięte fragmenty nagrania.

Błędy : Oprócz standardowego błędu sumy kontrolnej BigBlueButton, to wywołanie API może zwrócić następujące błędy w <messageKey>, gdy kod powrotu zakończy się niepowodzeniem:

brakujący parametr : Brak wymaganego parametru.

noRecordings : Nie znaleziono nagrania odpowiadającego podanemu identyfikatorowi nagrania.

POST putRecordingTextTrack

Prześlij plik podpisu lub napisów, aby dodać go do nagrania. Jeśli istnieje jakaś ścieżka z tymi samymi wartościami rodzaju i języka, zostanie ona zastąpiona.

Należy pamiętać, że ten interfejs API wymaga użycia żądania POST. Parametry wymienione jako parametry GET muszą być zawarte w identyfikatorze URI żądania, a faktycznie przesłany plik musi być zawarty w treści żądania w formacie danych wieloczęściowych/formularzy.

Należy pamiętać, że standardowy algorytm sumy kontrolnej BigBlueButton musi zostać wykonany na parametrach GET, ale treść żądania (plik z napisami) nie jest sumą kontrolną.

Ten projekt polega na tym, że aplikacja internetowa może wygenerować formularz z podpisanym adresem URL i wyświetlić go w przeglądarce z polem wyboru przesyłania pliku. Gdy użytkownik prześle formularz, prześle ścieżkę bezpośrednio do interfejsu API nagrywania. Oczywiście API może być również wykorzystywane programowo.

Ten interfejs API jest asynchroniczny. Uwzględnienie przesłanego pliku w opublikowanym nagraniu może zająć kilka minut, a jeśli przesłany plik zawiera nieodwracalne błędy, może on nigdy się nie pojawić.

URL zasobu:

POST http://yourserver.com/bigbluebutton/api/putRecordingTextTrack

Parametry:

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Treść POST: Jeśli żądanie ma treść, nagłówek Content-Type musi określać dane wieloczęściowe/formularza. W treści postu mogą być zakodowane następujące parametry.

plik: (Typ danych binarnych, opcjonalnie) Zawiera przesłany plik napisów lub podpisów. Jeśli brakuje tego parametru lub jeśli żądanie POST nie ma treści, wówczas każda istniejąca ścieżka tekstowa pasująca do określonego rodzaju i języka zostanie usunięta. Jeśli jest znana, aplikacja przesyłająca powinna ustawić Content-Type na wartość odpowiednią do formatu pliku. Jeśli typ zawartości nie jest ustawiony lub nie pasuje do znanego formatu napisów, przesłany plik zostanie sprawdzony w celu automatycznego wykrycia typu.

Do przesyłania akceptowanych jest wiele typów napisów, ale w celu wyświetlenia zostaną one przekonwertowane do formatu WebVTT.

Rozmiar żądania jest ograniczony (TODO: określić limit może 8MB?)

Akceptowane są następujące typy plików z napisami:

• SRT (SubRip Text), łącznie z podstawowym formatowaniem.
• SRT nie ma standardowego typu MIME, ale akceptowana jest aplikacja/x-subrip. — SSA lub ASS (stacja podrzędna Alpha, zaawansowana stacja podrzędna). Większość formatowania zostanie odrzucona, ale podstawowe style wbudowane (pogrubienie, kursywa itp.) mogą zostać zachowane. — SSA/ASS nie ma standardowego typu MIME.
• WebVTT. Przesłane pliki WebVTT zostaną użyte w niezmienionej postaci, ale należy pamiętać, że obsługa przeglądarek jest różna, dlatego nie zaleca się włączania bloków REGION ani STYLE.

Typ MIME WebVTT to text/vtt.

Błędy

Oprócz standardowego błędu sumy kontrolnej BigBlueButton, to wywołanie API może zwrócić w <messageKey> następujące błędy, gdy kod powrotu nie powiedzie się:

brakującyParametr : Brak wymaganego parametru.

noRecordings : Nie znaleziono nagrania odpowiadającego podanemu identyfikatorowi nagrania.

validKind : Parametr rodzaju nie jest ustawiony na dozwoloną wartość.

validLang : Parametr lang nie jest poprawnie sformułowanym znacznikiem języka.

Przesłana ścieżka tekstowa nie jest sprawdzana podczas przesyłania. Jeśli jest nieprawidłowy, zostanie zignorowany, a istniejące napisy nie zostaną zastąpione.

Sukces

{
  "response": {
    "messageKey": "upload_text_track_success",
    "message": "Text track uploaded successfully",
    "recordId": "baz",
    "returncode": "SUCCESS"
  }
}

Awaria

{
  "response": {
    "messageKey": "upload_text_track_failed",
    "message": "Text track upload failed.",
    "recordId": "baz",
    "returncode": "SUCCESS"
  }
}

lub

{
  "response": {
    "message": "Empty uploaded text track.",
    "messageKey": "empty_uploaded_text_track",
    "returncode": "FAILED"
  }
}

Błąd braku parametru

{
  "response": {
    "messageKey": "paramError",
    "message": "Missing param checksum.",
    "returncode": "FAILED"
  }
}

GET sendChatMessage

To połączenie umożliwia wysłanie wiadomości na czacie publicznym trwającego spotkania. Wiadomości są renderowane jako zwykły tekst: przed wyświetleniem wiadomości usuwane są znaki specjalne i nie jest stosowane formatowanie HTML ani Markdown.

<i>ADodano:</i> 3.0

URL zasobu:

http://yourserver.com/bigbluebutton/api/sendChatMessage?[parameters]&checksum=[checksum]

Parametry:

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Przykładowe żądania:

http://yourserver.com/bigbluebutton/api/sendChatMessage?meetingID=test01&message=my+test&userName=System+Admin&checksum=1234

Przykładowa odpowiedź:

<response>
    <returncode>SUCCESS</returncode>
    <messageKey></messageKey>
    <message></message>
</response>

Błędy

Oprócz standardowego błędu sumy kontrolnej BigBlueButton, to wywołanie API może zwrócić następujące błędy w <messageKey>, gdy kod powrotu nie powiedzie się:

brakParamMeetingID : Brak wymaganego parametru meetingID lub jest on pusty.

brakującyParamMessage : Brak wymaganego parametru message.

sizeError : Parametr przekracza dozwoloną długość: message musi zawierać się od 1 do 500 znaków, meetingID od 2 do 256 znaków, a userName maksymalnie 255 znaków.

validationError : meetingID zawiera nieprawidłowe znaki (nie może zawierać przecinka).

MeetingNotFound : Żadne trwające spotkanie nie pasuje do podanego meetingID. Spotkanie musi być uruchomione (utworzone i jeszcze nie zakończone) — wiadomości nie można umieścić w kolejce na przyszłe spotkanie.

Wewnętrzne wywołania API

Oprócz opisanego powyżej interfejsu API integracji, BigBlueButton udostępnia niewielki zestaw punktów końcowych, które istnieją tylko po to, aby obsługiwać klienta HTML5 BigBlueButton, gdy użytkownik uczestniczy w spotkaniu na żywo. Są tutaj udokumentowane, więc ich zachowanie jest możliwe do wykrycia, ale nie są częścią stabilnej umowy integracyjnej z stroną trzecią.

Najważniejszą różnicą jest sposób ich uwierzytelniania. Integracyjny interfejs API opisany w Modelu zabezpieczeń API jest uwierzytelniany za pomocą checksum wyprowadzonego na podstawie wspólnego hasła, a połączenia są wykonywane między serwerami. Zamiast tego połączenia wewnętrzne są uwierzytelniane przy użyciu konkretnego użytkownika sessionToken:

• sessionToken jest generowane przez wywołanie join. Jest zwracany (i znany tylko) przeglądarce, która dołączyła do spotkania.
• Identyfikuje sesję pojedynczego użytkownika; serwer rozpoznaje na tej podstawie spotkanie, użytkownika i rolę. Nie ma checksum, a wspólny sekret nie jest zaangażowany.
• Nie jest dostępny dla frontendów (Greenlight, Moodle,…) ani dla systemów równoważenia obciążenia (Scalelite, b3scale,…), które znajdują się przed BigBlueButton, ponieważ te komponenty nigdy nie widzą tokena sesji – widzi to tylko klient.

Z tego powodu powinieneś traktować te punkty końcowe jako szczegóły implementacji klienta:

• Nie buduj na nich integracji ani logiki równoważenia obciążenia. — Ich parametry, reakcje i istnienie mogą zmieniać się pomiędzy wydaniami bez powiadomienia i bez cyklu wycofywania.
• Żądania bez ważnego, wciąż aktywnego tokena sesji są odrzucane.

:::note Ta sekcja została dodana w odpowiedzi na problem #24212, który wymagał, aby getJoinUrl (i podobne punkty końcowe) były wyraźnie oznaczone jako wewnętrzne, a nie prezentowane obok interfejsu API integracji. :::

Wewnętrzne punkty końcowe obecnie udostępniane przez bbb-web to getJoinUrl, stuns, signOut i learningDashboard, opisany poniżej. Należy pamiętać, że poza tym kontrolerem istnieje kilka innych punktów końcowych skierowanych do klienta (na przykład trasy wysyłania/pobierania prezentacji pod /bigbluebutton/presentation/...) i również nie są częścią interfejsu API integracji.

GET POST getJoinUrl

Punkt końcowy getJoinUrl generuje nowy adres URL /join, którego można użyć do utworzenia nowej sesji dla istniejącego użytkownika. Dzięki powiązaniu nowego tokena sesji z tym samym identyfikatorem użytkownika wszystkie sesje będą wyświetlane jako ten sam użytkownik na liście użytkowników, co zapewni dokładne zliczenie użytkowników. Użytkownicy mogą także dostosować układ nowej sesji i parametry danych użytkownika, umożliwiając elastyczną kontrolę nad środowiskiem i funkcjonalnością sesji.

Jest to szczególnie przydatne w środowiskach hybrydowych, gdzie wiele ekranów w tym samym pomieszczeniu wymaga odrębnej sesji z różnymi układami.

Ułatwia także bezproblemowe przesyłanie sesji użytkownika na inne urządzenie. Na przykład urządzenie mobilne może zeskanować kod QR wyświetlony na komputerze, natychmiastowo przenosząc sesję użytkownika z jednego urządzenia na drugie.

Osoba wywołująca musi przedstawić sessionToken istniejącej, wciąż aktywnej sesji; wynikowy adres URL /join zawiera prawidłowy adres checksum i można go następnie otworzyć bezpośrednio w przeglądarce.

URL zasobu:

http://yourserver.com/bigbluebutton/api/getJoinUrl?[parameters]

Parametry:

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Przykładowe żądania:

https://yourserver.com/bigbluebutton/api/getJoinUrl?sessionToken=xyn1fbqlrhug1j6z&enforceLayout=PRESENTATION_ONLY&sessionName=Presentation%20session&userdata-bbb_client_title=Presentation%20client

Przykładowa odpowiedź:

{
    "response": {
        "returncode": "SUCCESS",
        "message": "Join URL provided successfully.",
        "url": "https://yourserver.com/bigbluebutton/api/join?&redirect=true&existingUserID=w_t18rn7uc1wjm&role=MODERATOR&userdata-bbb_client_title=Presentation+client&sessionName=Presentation+session&fullName=teacher%2B1&meetingID=random-7653737&enforceLayout=PRESENTATION_ONLY&checksum=135f230a2339b9485d91a3e87b1a22420ca57e8b"
    }
}

GET POST stuns

Punkt końcowy stuns zwraca konfigurację serwera STUN/TURN i zdalnych kandydatów ICE, których klient potrzebuje do nawiązania połączeń multimedialnych WebRTC (audio, kamera internetowa, udostępnianie ekranu). Spotkanie zostaje rozwiązane na podstawie sesji, więc meetingID nie jest przekazywane.

URL zasobu:

http://yourserver.com/bigbluebutton/api/stuns?[parameters]

Parametry:

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Przykładowe żądania:

https://yourserver.com/bigbluebutton/api/stuns?sessionToken=xyn1fbqlrhug1j6z

Przykładowa odpowiedź:

{
    "stunServers": [
        { "url": "stun:stun.example.com:3478" }
    ],
    "turnServers": [
        {
            "username": "1699999999:bbb",
            "password": "somegeneratedcredential",
            "url": "turns:turn.example.com:443?transport=tcp",
            "ttl": 86400
        }
    ],
    "remoteIceCandidates": []
}

Gdy brakuje tokena sesji lub jest on nieprawidłowy, punkt końcowy odpowiada zamiast tego ładunkiem błędu:

{
    "returncode": "FAILED",
    "message": "Could not find conference.",
    "logoutURL": "https://yourserver.com/"
}

GET POST signOut

Punkt końcowy signOut unieważnia sesję użytkownika, gdy klient opuszcza spotkanie. Usuwa sesję użytkownika po stronie serwera powiązaną z dostarczonym sessionToken. Zawsze odpowiada z sukcesem, niezależnie od tego, czy znaleziono pasującą sesję.

URL zasobu:

http://yourserver.com/bigbluebutton/api/signOut?[parameters]

Parametry:

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Przykładowe żądania:

https://yourserver.com/bigbluebutton/api/signOut?sessionToken=xyn1fbqlrhug1j6z

Przykładowa odpowiedź:

<response>
    <returncode>SUCCESS</returncode>
</response>

GET POST learningDashboard

Punkt końcowy learningDashboard zwraca dane Learning Analytics Dashboard dla spotkania sesji. Dostęp jest ograniczony: sesja musi należeć do użytkownika z rolą MODERATOR, spotkanie musi być uruchomione, a funkcja learningDashboard nie może być wymieniona w disabledFeatures spotkania. Pole data zawiera dokument JSON panelu kontrolnego serializowany jako ciąg znaków.

URL zasobu:

http://yourserver.com/bigbluebutton/api/learningDashboard?[parameters]

Parametry:

Tabela jest szersza od ekranu. Przewiń ją w poziomie.

Przykładowe żądania:

https://yourserver.com/bigbluebutton/api/learningDashboard?sessionToken=xyn1fbqlrhug1j6z

Przykładowa odpowiedź:

{
    "response": {
        "returncode": "SUCCESS",
        "data": "{ ...learning dashboard data as a JSON-encoded string... }",
        "sessionToken": "xyn1fbqlrhug1j6z"
    }
}

Przykładowy kod API

BigBlueButton udostępnia przykładowe kody API, dzięki czemu można je łatwo zintegrować z aplikacją. Możesz wnieść swój wkład i opublikować swoją implementację API w innym kodzie językowym na liście mailingowej bigbluebutton-dev.

PHP

W BigBlueButton PHP API znajduje się stabilna biblioteka PHP.

Aby ten przykład mógł zadziałać, musisz włączyć opcję „allow_url_fopen” na „Włącz”. Po prostu dodaj/zastąp do swojego pliku php.ini:

<code>allow_url_fopen = On</code>

Więcej przykładów użycia PHP znajdziesz w źródle pliku Integracje Moodle i WordPress.

Rubin

Zobacz następujący klejnot bigbluebutton-api-ruby stworzony przez dobrych ludzi z Mconf.

Testowanie wywołań API za pomocą API Mate

Aby pomóc Ci w tworzeniu/testowaniu prawidłowych wywołań API na serwerze BigBlueButton, użyj doskonałego API Mate do interaktywnego tworzenia wywołań API. API Mate generuje sumy kontrolne w przeglądarce (nie jest potrzebny komponent serwera), dzięki czemu można go używać do testowania wywołań API na lokalnym serwerze BigBlueButton.

Jeśli opracowujesz nowe wywołania API lub dodajesz parametry do wywołań API, nadal możesz używać API Mate do ich testowania. Po prostu przewiń stronę w dół lub wpisz „custom” w filtrze parametrów, a zobaczysz dane wejściowe, w których możesz dodać niestandardowe wywołania API lub metadane użytkownika. Nowe wywołania API pojawią się na liście łączy API, a do wszystkich łączy API zostaną dodane nowe parametry.

Jeśli używasz API Mate do testowania nagrań i chcesz wysyłać zapytania za pomocą meetingID, pamiętaj najpierw o wyczyszczeniu pola recordID. Interfejs API BigBlueButton obsługuje zapytania o nagrania według dowolnej wartości, ale nie obu jednocześnie.

Obsługa JSON/JSONP

• Byłoby bardzo miło opcjonalnie zezwolić na odpowiedzi JSON i wspierać JSONP. Może to pozwolić na prostsze integracje, nawet w obrębie statycznych lub prawie statycznych stron internetowych, w których JavaScript jest głównym językiem integracji. Nie należy zakładać, że wszyscy użytkownicy będą uruchamiać niestandardowe oprogramowanie na serwerze i będą mogli przetwarzać odpowiedzi XML itp.
• w związku z tym nawet w JavaScript istnieją proste sposoby wykonywania wywołań API i przetwarzania zwróconego XML (na przykład przy użyciu jQuery i $.xml2json)

Wywołania zwrotne dotyczące zdarzeń spotkań

Można to nawet nazwać „odwrotnym API” – w którym definiujemy interfejs, który aplikacja innej firmy może zaimplementować w celu powiadamiania o zdarzeniach. Nie byłoby to konieczne w przypadku pierwszej wersji interfejsu API, ale byłoby przydatną funkcją w przypadku przyszłych ulepszeń. Więcej szczegółów:

Kiedy w trakcie spotkań mają miejsce ważne wydarzenia, bardzo pomocne byłoby zapewnienie możliwości powiadamiania aplikacji innych firm o tych wydarzeniach. Na przykład, gdy użytkownik dołącza do konferencji, prawdopodobnie dołączy za pośrednictwem aplikacji innej firmy. Jednakże, gdy opuszczą konferencję, aplikacja może zostać poddana pewnemu audytowi, aby zarejestrować czas rozłączenia itp. Jeśli BigBlueButton mógłby oddzwonić do aplikacji, pomogłoby to w takich scenariuszach.

Na przykład aplikacja może być w stanie zarejestrować adres URL, który BigBlueButton będzie wywoływał z aktualizacjami statusu. BigBlueButton zdefiniowałby interfejs API, który taka aplikacja musiałaby zaimplementować pod tym adresem URL. Na przykład BigBlueButton może wywołać:

• http://third-party-app/bbb-integ.php?event=meetingEnded&meetingID=abcd
• http://third-party-app/bbb-integ.php?event=userLeft&userID=1234
• http://third-party-app/bbb-integ.php?event=meetingEnded&meetingID=abcd

Inne tematy

Obsługiwane typy dokumentów

Dokumenty PDF

• PDF:
• .pdf

Dokumenty biurowe

• Microsoft Word:
• .doc
• .docx
• Microsoft Excel:
• .xls
• .xlsx
• Microsoft PowerPoint:
• .ppt
• .pptx
• Formaty OpenDocument:
• .odt (dokument tekstowy)
• .ods (arkusz kalkulacyjny)
• .odp (Prezentacja)
• .odg (Grafika)

Pliki obrazów

• Typowe formaty obrazów:
• .jpg
• .jpeg
• .png
• .webp
• .svg

Pliki tekstowe

• Format tekstu sformatowanego:
• .rtf
• Zwykły tekst:
• .txt

Wszystkie te prawidłowe formaty są również obecne na liście w back-end i front-end, jeśli potrzeba więcej szczegółów.