Przeglądasz dokumentację API dla BigBlueButton 3.x. Aktualna wersja to BigBlueButton 4.x. Planujesz aktualizację? Przewodnik migracji zawiera wszystkie zmiany wymagane w wywołaniach API.
getMeetingInfo – Pobierz szczegóły spotkania
Punkt końcowy getMeetingInfo zwraca szczegółowe informacje o pojedynczym spotkaniu BigBlueButton, w tym o jego aktualnych uczestnikach, metadanych, ustawieniach konfiguracji i statusie nagrywania. Używaj go do inspekcji konkretnego spotkania w czasie rzeczywistym.
Punkt końcowy
GET/POST https://api-guide.bbbserver.com/bigbluebutton/api/getMeetingInfo?<parameter>&checksum=replace-with-checksum Ten punkt końcowy wymaga prawidłowej sumy kontrolnej obliczonej na podstawie wspólnego sekretu twojego serwera BigBlueButton. Obsługiwane są zarówno żądania GET, jak i POST.
Parametry
| Parametr | Typ | Wymagane | Opis |
|---|---|---|---|
meetingID | String | Tak | Identyfikator spotkania, o które pytasz. Jest to ID podane podczas tworzenia spotkania. |
Pola odpowiedzi
Pomyślna odpowiedź zawiera następujące pola opisujące spotkanie i jego bieżący stan:
| Pole | Typ | Opis |
|---|---|---|
returncode | String | Wskazuje, czy wywołanie zakończyło się powodzeniem. Zwraca SUCCESS lub FAILED. |
meetingName | String | Czytelna dla człowieka nazwa spotkania. |
meetingID | String | Zewnętrzny identyfikator spotkania określony podczas tworzenia. |
internalMeetingID | String | Wewnętrzny unikalny identyfikator wygenerowany przez BigBlueButton. |
createTime | Long | Znacznik czasu (w milisekundach od epoki), kiedy spotkanie zostało utworzone. |
createDate | String | Czytelna dla człowieka data i godzina utworzenia spotkania. |
voiceBridge | String | Numer mostka głosowego do telefonicznego połączenia. |
dialNumber | String | Numer telefonu do dostępu telefonicznego, jeśli został skonfigurowany. |
attendeePW | String deprecated | Hasło uczestnika. Dołączone dla zgodności wstecznej, ale przestarzałe od BigBlueButton 2.5. |
moderatorPW | String deprecated | Hasło moderatora. Dołączone dla zgodności wstecznej, ale przestarzałe od BigBlueButton 2.5. |
running | Boolean | Czy spotkanie jest obecnie uruchomione (true), czy nie (false). |
duration | Integer | Maksymalny czas trwania spotkania w minutach. Wartość 0 oznacza brak limitu. |
hasUserJoined | Boolean | Czy co najmniej jeden użytkownik dołączył do spotkania. |
recording | Boolean | Czy nagrywanie jest włączone dla tego spotkania. |
hasBeenForciblyEnded | Boolean | Ustawiane na true po zakończeniu spotkania, niezależnie od sposobu jego zakończenia. Ponieważ BigBlueButton natychmiast usuwa zakończone spotkanie z pamięci, odpowiedzi praktycznie zawsze zawierają false. |
startTime | Long | Znacznik czasu (w milisekundach) rozpoczęcia spotkania. |
endTime | Long | Znacznik czasu (w milisekundach) zakończenia spotkania. Zwraca 0, jeśli nadal trwa. |
participantCount | Integer | Łączna liczba uczestników obecnie znajdujących się na spotkaniu. |
listenerCount | Integer | Liczba uczestników w trybie tylko słuchania. |
voiceParticipantCount | Integer | Liczba uczestników, którzy dołączyli do kanału audio. |
videoCount | Integer | Liczba strumieni z kamer internetowych aktualnie udostępnianych podczas spotkania. |
maxUsers | Integer | Maksymalna dozwolona liczba użytkowników. Wartość 0 oznacza brak limitu. |
moderatorCount | Integer | Liczba moderatorów obecnie znajdujących się na spotkaniu. |
attendees | XML Container | Zawiera listę elementów attendee ze szczegółami dotyczącymi każdego połączonego uczestnika (zobacz pola uczestnika poniżej). |
metadata | XML Container | Zawiera niestandardowe pary klucz-wartość metadanych przekazane podczas tworzenia spotkania. |
isBreakout | Boolean | Czy spotkanie jest pokojem breakout. |
parentMeetingID | String | Wewnętrzny identyfikator spotkania (internalMeetingID) nadrzędnego. Występuje tylko w przypadku pokojów grupowych. |
sequence | Integer | Numer sekwencyjny pokoju breakout. Obecny tylko dla pokoi breakout. |
freeJoin | Boolean | Czy uczestnicy mogą swobodnie wybrać, do którego pokoju breakout dołączyć. Obecne tylko dla pokoi breakout. |
breakoutRooms | XML Container | Wyświetla identyfikatory pokoi podgrup powiązanych z tym spotkaniem. Obecne tylko wtedy, gdy utworzono pokoje podgrup. |
Pola uczestnika
Każdy element attendee w obrębie attendees zawiera następujące pola:
| Pole | Typ | Opis |
|---|---|---|
userID | String | Zewnętrzny identyfikator użytkownika przekazany jako userID do join. Jeśli go nie przekazano, zwracany jest wewnętrzny identyfikator użytkownika wygenerowany przez BigBlueButton (format w_xxxxxxxxxxxx). |
fullName | String | Wyświetlana nazwa uczestnika. |
role | Enum | Rola uczestnika: MODERATOR lub VIEWER. Użytkownicy łączący się telefonicznie są oznaczani jako DIAL-IN-USER. |
isPresenter | Boolean | Czy uczestnik jest obecnie prezenterem. |
isListeningOnly | Boolean | Czy uczestnik jest w trybie tylko do słuchania. |
hasJoinedVoice | Boolean | Czy uczestnik dołączył do kanału audio z mikrofonem. |
hasVideo | Boolean | Czy uczestnik udostępnia swoją kamerę internetową. |
clientType | String | Typ klienta używanego przez uczestnika. Zwykle HTML5. |
customdata | XML Container | Zawiera parametry userdata-* przekazane do join jako elementy podrzędne XML (bez prefiksu). Obecny dla każdego uczestnika, który dołączył za pośrednictwem join; pusty, jeśli nie przekazano takich parametrów. |
Przykładowe żądanie
GET https://api-guide.bbbserver.com/bigbluebutton/api/getMeetingInfo?meetingID=replace-with-meeting-id&checksum=replace-with-checksum Przykładowa odpowiedź (sukces)
<response>
<returncode>SUCCESS</returncode>
<meetingName>Project Discussion</meetingName>
<meetingID>replace-with-meeting-id</meetingID>
<internalMeetingID>replace-with-internal-meeting-id</internalMeetingID>
<createTime>1715261728123</createTime>
<createDate>Thu May 09 13:35:28 UTC 2024</createDate>
<voiceBridge>66052</voiceBridge>
<dialNumber>613-555-1234</dialNumber>
<attendeePW>replace-with-password</attendeePW>
<moderatorPW>replace-with-password</moderatorPW>
<running>true</running>
<duration>0</duration>
<hasUserJoined>true</hasUserJoined>
<recording>true</recording>
<hasBeenForciblyEnded>false</hasBeenForciblyEnded>
<startTime>1715261728142</startTime>
<endTime>0</endTime>
<participantCount>3</participantCount>
<listenerCount>1</listenerCount>
<voiceParticipantCount>2</voiceParticipantCount>
<videoCount>2</videoCount>
<maxUsers>0</maxUsers>
<moderatorCount>1</moderatorCount>
<attendees>
<attendee>
<userID>replace-with-user-id</userID>
<fullName>Max Mustermann</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>greenlight</bbb-origin>
<bbb-origin-version>v3.1.0</bbb-origin-version>
<endcallbackurl>https://api-guide.bbbserver.com/callbacks/meeting-ended</endcallbackurl>
</metadata>
<isBreakout>false</isBreakout>
</response> Odpowiedź błędu
Jeśli podany identyfikator spotkania nie istnieje lub już się zakończył, API zwraca odpowiedź FAILED:
<response>
<returncode>FAILED</returncode>
<messageKey>notFound</messageKey>
<message>A meeting with that ID does not exist</message>
</response> Błąd notFound niekoniecznie oznacza, że spotkanie nigdy nie zostało utworzone. Mogło już się zakończyć i zostać usunięte z pamięci serwera. BigBlueButton przechowuje dane spotkania tylko wtedy, gdy spotkanie jest aktywne.
getMeetingInfo vs. getMeetings
| Aspekt | getMeetings | getMeetingInfo |
|---|---|---|
| Zakres | Wszystkie aktywne spotkania na serwerze | Jedno konkretne spotkanie |
| Parametry | Brak wymaganych | meetingID wymagane |
| Szczegóły uczestników | Połączeni użytkownicy oraz użytkownicy, którzy niedawno opuścili spotkanie (domyślnie usuwani po 60 sekundach) | Tylko obecnie połączeni użytkownicy |
| Przypadek użycia | Przegląd pulpitu i monitorowania | Ukierunkowana inspekcja konkretnego spotkania |
Typowe przypadki użycia
- Logika dołączania — sprawdź, czy moderator jest obecny, zanim przekierujesz gości do spotkania.
- Listy uczestników — wyświetl bieżących uczestników w zewnętrznej aplikacji lub na stronie poczekalni.
- Stan nagrywania — sprawdź, czy nagrywanie jest włączone dla spotkania.
- Debugowanie — przeprowadź szczegółową analizę konkretnego spotkania w celach diagnostycznych.
getMeetingInfo jest dostępny we wszystkich planach. Dane uwierzytelniające API znajdziesz w panelu zarządzania serwerem.Wskazówki
Odpytuj getMeetingInfo okresowo, aby zbudować listę uczestników na żywo. Połącz pola voiceParticipantCount i videoCount, aby określić, ilu użytkowników aktywnie korzysta z audio i wideo.
Użyj kontenera metadata do przekazywania i pobierania danych specyficznych dla aplikacji, takich jak system źródłowy, URL-e callbacków lub niestandardowe etykiety, bez ingerowania w mechanizmy wewnętrzne BigBlueButton.
Pola attendeePW i moderatorPW są przestarzałe od BigBlueButton 2.5. Nadal są zwracane ze względu na zgodność wsteczną, ale nie należy na nich polegać w logice uwierzytelniania nowych integracji.
Najczęściej zadawane pytania
FAILED z messageKey „notFound”. BigBlueButton usuwa dane spotkania z pamięci po zakończeniu spotkania. Aby uzyskać informacje o przeszłych spotkaniach, użyj zamiast tego punktu końcowego getRecordings.getMeetings nadal wyświetla użytkowników, którzy niedawno opuścili spotkanie, dopóki BigBlueButton ich nie usunie (domyślnie po 60 sekundach).BigBlueButton nie narzuca ścisłego limitu szybkości, ale częste odpytywanie (np. co sekundę) może niepotrzebnie obciążać serwer. Interwał odpytywania od 5 do 10 sekund jest zwykle wystarczający dla większości zastosowań.getMeetingInfo z meetingID. Jeśli returncode w odpowiedzi to SUCCESS, spotkanie istnieje i jest aktywne. Jeśli jest to FAILED z messageKey „notFound”, spotkanie nie istnieje lub już się zakończyło.parentMeetingID, sequence, freeJoin i breakoutRooms pojawiają się w odpowiedzi tylko wtedy, gdy spotkanie jest pokojem podgrup lub ma pokoje podgrup. Dla zwykłych spotkań isBreakout ma wartość false, a pozostałe pola breakout są pomijane.customdata zawiera pary klucz-wartość specyficzne dla użytkownika, przekazane jako parametry userdata-* podczas dołączania użytkownika do spotkania za pomocą wywołania API join. Każdy klucz (bez prefiksu userdata-) staje się elementem podrzędnym XML. Jeśli nie podano danych niestandardowych, element jest pusty.