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 spotkanie jest nagrywane.
hasBeenForciblyEnded Boolean Czy spotkanie zostało zakończone przez wywołanie API end.
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 uczestników udostępniających swoją kamerę internetową.
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 ID spotkania nadrzędnego. Obecne tylko dla pokoi breakout.
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 Wewnętrzny identyfikator użytkownika BigBlueButton, zwykle w formacie w_xxxxxxxx.
fullName String Wyświetlana nazwa uczestnika.
role Enum Rola uczestnika: MODERATOR lub VIEWER.
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 niestandardowe dane klucz-wartość jako podrzędne elementy XML. Występuje tylko wtedy, gdy dla uczestnika ustawiono niestandardowe dane podczas join.

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>
    </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>We could not find a meeting with that meeting ID</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 Wszyscy użytkownicy, w tym ci, którzy opuścili spotkanie 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.
  • Status nagrywania — sprawdź, czy nagrywanie jest obecnie aktywne 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. W przeciwieństwie do tego getMeetings może zawierać użytkowników, którzy opuścili spotkanie, w niektórych wersjach BigBlueButton.

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 przechowuje pary klucz-wartość specyficzne dla użytkownika, które zostały przekazane jako parametry, gdy użytkownik dołączał do spotkania przez wywołanie API join. Każdy klucz staje się podrzędnym elementem XML. Jeśli nie podano niestandardowych danych, ten element może być nieobecny.