Wersja API: 4.x najnowsza 3.x

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.

Rozdział 10 GET POST

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.
W bbbserver.de punkt końcowy 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

Otrzymasz odpowiedź 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.

Nie. Lista uczestników zawiera tylko osoby aktualnie połączone ze spotkaniem. Użytkownicy, którzy opuścili spotkanie, nie są już uwzględniani. Natomiast getMeetings nadal wyświetla użytkowników, którzy niedawno opuścili spotkanie, dopóki BigBlueButton ich nie usunie (domyślnie po 60 sekundach).

Sam 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ń.

Tak. Wywołaj 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.

Pola takie jak 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.

Kontener 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.