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ł 9 GET POST

getMeetings – Wyświetl wszystkie spotkania

Punkt końcowy getMeetings zwraca listę wszystkich spotkań aktualnie istniejących na serwerze BigBlueButton, w tym szczegóły uczestników i metadane. Jest to podstawowe narzędzie do budowania paneli administracyjnych, monitorowania obciążenia serwera i planowania pojemności w całej infrastrukturze.

Punkt końcowy

GET/POST https://api-guide.bbbserver.com/bigbluebutton/api/getMeetings?checksum=replace-with-checksum

Ten punkt końcowy nie wymaga żadnych dodatkowych parametrów poza sumą kontrolną. Zwraca wszystkie spotkania na serwerze w jednej odpowiedzi.

Parametry

Parametr Typ Wymagane Domyślnie Opis
checksum String Tak — Bezpieczna suma kontrolna obliczana na podstawie nazwy wywołania API i wspólnego sekretu.

Przykładowe żądanie

https://api-guide.bbbserver.com/bigbluebutton/api/getMeetings?checksum=replace-with-checksum

Przykładowa odpowiedź

Znalezione spotkania

<response>
  <returncode>SUCCESS</returncode>
  <meetings>
    <meeting>
      <meetingName>Demo Meeting</meetingName>
    <meetingID>replace-with-meeting-id</meetingID>
      <internalMeetingID>a0715c95...</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>true</running>
      <duration>0</duration>
      <hasUserJoined>true</hasUserJoined>
      <recording>false</recording>
      <hasBeenForciblyEnded>false</hasBeenForciblyEnded>
      <startTime>1531241258074</startTime>
      <endTime>0</endTime>
      <participantCount>5</participantCount>
      <listenerCount>2</listenerCount>
      <voiceParticipantCount>3</voiceParticipantCount>
      <videoCount>2</videoCount>
      <maxUsers>0</maxUsers>
      <moderatorCount>1</moderatorCount>
      <attendees>
        <attendee>
          <userID>w_ftcrsyuh44oj</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/>
      <isBreakout>false</isBreakout>
    </meeting>
  </meetings>
</response>

Nie znaleziono spotkań

<response>
  <returncode>SUCCESS</returncode>
  <meetings/>
  <messageKey>noMeetings</messageKey>
  <message>no meetings were found on this server</message>
</response>

Pola odpowiedzi dla każdego spotkania

Pole Typ Opis
meetingName String Wyświetlana nazwa spotkania.
meetingID String Zewnętrzny identyfikator spotkania określony podczas tworzenia.
internalMeetingID String Wewnętrzny unikalny identyfikator wygenerowany przez serwer.
createTime Number Znacznik czasu utworzenia w milisekundach od epoki Unix.
createDate String Czytelny dla człowieka ciąg daty utworzenia.
voiceBridge String Numer mostka głosowego dla konferencji audio.
dialNumber String Numer telefonu do połączenia na spotkanie.
attendeePW String Hasło uczestnika. Generowane losowo, jeśli nie przekazano go do create. Przestarzałe od BBB 3.0.
moderatorPW String Hasło moderatora. Generowane losowo, jeśli nie przekazano go do create. Przestarzałe od BBB 3.0.
running Boolean Czy spotkanie jest obecnie aktywne.
duration Number Maksymalny czas trwania w minutach. 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 Number Znacznik czasu rozpoczęcia w milisekundach od epoki Unix.
endTime Number Znacznik czasu zakończenia. 0, jeśli spotkanie nadal trwa.
participantCount Number Bieżąca liczba uczestników spotkania.
listenerCount Number Liczba uczestników tylko słuchających.
voiceParticipantCount Number Liczba uczestników z aktywnym dźwiękiem.
videoCount Number Liczba aktywnych kamer internetowych.
maxUsers Number Maksymalna dozwolona liczba uczestników. 0 oznacza brak limitu.
moderatorCount Number Liczba moderatorów obecnie znajdujących się na spotkaniu.
attendees List Lista wszystkich uczestników ze szczegółami takimi jak userID, fullName, role i stan mediów.
metadata Object Wszystkie niestandardowe parametry metadanych przekazane podczas wywołania create.
isBreakout Boolean Czy jest to pokój podgrupy.
parentMeetingID String Wewnętrzny identyfikator spotkania (internalMeetingID) nadrzędnego. Występuje tylko w przypadku pokojów grupowych.
sequence Number Numer sekwencyjny pokoju podgrupy. Obecne tylko dla pokoi podgrup.
freeJoin Boolean Czy uczestnicy mogą swobodnie wybrać ten pokój podgrupy. Obecne tylko dla pokoi podgrup.
breakoutRooms List Lista identyfikatorów pokojów grupowych. Występuje tylko wtedy, gdy dla spotkania utworzono pokoje grupowe.

Szczegóły uczestnika

Każdy wpis na liście 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 String 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 dołączył w trybie tylko do słuchania.
hasJoinedVoice Boolean Czy uczestnik dołączył do konferencji głosowej.
hasVideo Boolean Czy uczestnik ma aktywną kamerę internetową.
clientType String Typ klienta używanego przez uczestnika (np. HTML5).

Lista uczestników zwracana przez getMeetings obejmuje również użytkowników, którzy niedawno opuścili spotkanie: pozostają na liście, dopóki BigBlueButton ich nie usunie, domyślnie 60 sekund po opuszczeniu spotkania. Inaczej działa getMeetingInfo, które zwraca tylko aktualnie połączonych użytkowników. Pamiętaj o tym przy obliczaniu liczby aktywnych uczestników.

Typowe przypadki użycia

  • Panel administratora — wyświetla przegląd wszystkich trwających spotkań i liczby ich uczestników.
  • Planowanie pojemności — oblicza łączną liczbę aktywnych uczestników we wszystkich spotkaniach na serwerze.
  • Monitorowanie — identyfikuje spotkania bez moderatora lub spotkania, w których występują problemy.
  • Automatyczne czyszczenie — znajduje spotkania, które istnieją od dłuższego czasu bez żadnych uczestników.

Wskazówki i najlepsze praktyki

Ponieważ getMeetings zwraca wszystkie spotkania na serwerze (nie tylko uruchomione), filtruj wyniki według pola running, jeśli potrzebujesz tylko aktywnych spotkań.

Odpowiedź zawiera wrażliwe informacje, takie jak nazwy uczestników, identyfikatory użytkowników i hasła. Zawsze wywołuj ten endpoint wyłącznie z kodu po stronie serwera. Nigdy nie udostępniaj go aplikacjom po stronie klienta ani użytkownikom końcowym.

Ten endpoint nie obsługuje paginacji. Na serwerach z wieloma równoczesnymi spotkaniami odpowiedź może stać się bardzo duża i wpływać na wydajność. Rozważ buforowanie wyników, jeśli często sondujesz endpoint.

Najczęściej zadawane pytania

Nie. Zwraca wszystkie spotkania, które obecnie istnieją na serwerze, w tym spotkania, które zostały utworzone, ale nie mają jeszcze uczestników. Filtruj po polu running, jeśli potrzebujesz tylko aktywnych spotkań.

getMeetings zwraca podsumowanie wszystkich spotkań na serwerze, natomiast getMeetingInfo zwraca szczegółowe informacje o jednym konkretnym spotkaniu. Ponadto lista uczestników w getMeetings obejmuje również użytkowników, którzy niedawno opuścili spotkanie (domyślnie w ciągu ostatnich 60 sekund), natomiast getMeetingInfo wymienia tylko aktualnie połączonych użytkowników.

Tak. Jeśli nie przekazano hasła do create, BigBlueButton generuje je losowo, więc oba pola są uwzględniane dla każdego spotkania.

Sprawdź pole isBreakout. Jeśli ma wartość true, spotkanie jest pokojem podgrup i będzie zawierać dodatkowe pola, takie jak parentMeetingID, sequence i freeJoin. Spotkanie nadrzędne będzie miało listę breakoutRooms zawierającą identyfikatory jego pokoi podgrup.

Nie. API BigBlueButton nie obsługuje paginacji dla getMeetings. Wszystkie spotkania są zwracane w jednej odpowiedzi. W przypadku serwerów z bardzo dużą liczbą spotkań rozważ wdrożenie pamięci podręcznej lub rzadsze wywoływanie punktu końcowego, aby zmniejszyć obciążenie serwera.