Versione API: 4.x più recente 3.x

Stai visualizzando la documentazione API per BigBlueButton 3.x. La versione attuale è BigBlueButton 4.x. Stai pianificando un aggiornamento? La guida alla migrazione elenca tutte le modifiche necessarie alle tue chiamate API.

Capitolo 9 GET POST

getMeetings – Elenca tutte le riunioni

L'endpoint getMeetings restituisce un elenco di tutte le riunioni attualmente esistenti sul server BigBlueButton, inclusi i dettagli dei partecipanti e i metadati. È lo strumento principale per creare dashboard di amministrazione, monitorare il carico del server ed effettuare pianificazione della capacità nella tua infrastruttura.

Endpoint

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

Questo endpoint non richiede parametri aggiuntivi oltre al checksum. Restituisce tutte le riunioni sul server in un'unica risposta.

Parametri

Parametro Tipo Obbligatorio Predefinito Descrizione
checksum String Sì — checksum di sicurezza calcolato dal nome della chiamata API e dal segreto condiviso.

Esempio di richiesta

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

Risposta di esempio

Riunioni trovate

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

Nessuna riunione trovata

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

Campi di risposta per riunione

Campo Tipo Descrizione
meetingName String Nome visualizzato della riunione.
meetingID String ID riunione esterno come specificato durante la creazione.
internalMeetingID String ID univoco interno generato dal server.
createTime Number Timestamp di creazione in millisecondi dall'epoca Unix.
createDate String Stringa della data di creazione leggibile dall'uomo.
voiceBridge String Numero del voice bridge per la conferenza audio.
dialNumber String Numero di accesso telefonico per la riunione.
attendeePW String Password del partecipante. Generata casualmente se non ne è stata passata alcuna a create. Deprecata in BBB 3.0.
moderatorPW String Password del moderatore. Generata casualmente se non ne è stata passata alcuna a create. Deprecata in BBB 3.0.
running Boolean Indica se la riunione è attualmente attiva.
duration Number Durata massima in minuti. 0 significa illimitata.
hasUserJoined Boolean Indica se almeno un utente ha partecipato alla riunione.
recording Boolean Indica se la registrazione è abilitata per questa riunione.
hasBeenForciblyEnded Boolean Impostato su true al termine della riunione, indipendentemente da come è stata terminata. Poiché BigBlueButton rimuove immediatamente dalla memoria una riunione terminata, le risposte contengono praticamente sempre false.
startTime Number Timestamp di inizio in millisecondi dall'epoca Unix.
endTime Number Timestamp di fine. 0 se la riunione è ancora in corso.
participantCount Number Numero attuale di partecipanti nella riunione.
listenerCount Number Numero di partecipanti in modalità solo ascolto.
voiceParticipantCount Number Numero di partecipanti con audio attivo.
videoCount Number Numero di webcam attive.
maxUsers Number Numero massimo di partecipanti consentiti. 0 significa illimitato.
moderatorCount Number Numero di moderatori attualmente presenti nella riunione.
attendees List Elenco di tutti i partecipanti con dettagli come userID, fullName, role e stato dei media.
metadata Object Tutti i parametri di metadati personalizzati passati durante la chiamata create.
isBreakout Boolean Indica se questa è una stanza per sottogruppi.
parentMeetingID String L'ID interno della riunione (internalMeetingID) della riunione principale. Presente solo per le stanze per gruppi di lavoro.
sequence Number Numero di sequenza della stanza per sottogruppi. Presente solo per le stanze per sottogruppi.
freeJoin Boolean Indica se i partecipanti possono scegliere liberamente questa stanza per sottogruppi. Presente solo per le stanze per sottogruppi.
breakoutRooms List Elenco degli ID delle stanze per gruppi di lavoro. Presente solo quando sono state create stanze per gruppi di lavoro per la riunione.

Dettagli del partecipante

Ogni voce nell'elenco attendees contiene i seguenti campi:

Campo Tipo Descrizione
userID String L'ID utente esterno passato come userID a join. Se non ne è stato passato alcuno, viene restituito l'ID utente interno generato da BigBlueButton (formato w_xxxxxxxxxxxx).
fullName String Nome visualizzato del partecipante.
role String Il ruolo del partecipante: MODERATOR o VIEWER. Gli utenti che accedono telefonicamente sono elencati con DIAL-IN-USER.
isPresenter Boolean Indica se il partecipante è attualmente il presentatore.
isListeningOnly Boolean Indica se il partecipante è entrato in modalità solo ascolto.
hasJoinedVoice Boolean Indica se il partecipante è entrato nella conferenza vocale.
hasVideo Boolean Indica se il partecipante ha una webcam attiva.
clientType String Tipo di client usato dal partecipante (ad es. HTML5).

L'elenco dei partecipanti restituito da getMeetings include anche gli utenti che hanno abbandonato la riunione di recente: rimangono nell'elenco finché BigBlueButton non li rimuove, per impostazione predefinita 60 secondi dopo l'uscita. Questo comportamento è diverso da quello di getMeetingInfo, che restituisce solo gli utenti attualmente connessi. Tienine conto quando calcoli il numero di partecipanti attivi.

Casi d’uso comuni

  • Dashboard di amministrazione — mostra una panoramica di tutte le riunioni in corso e del numero dei loro partecipanti.
  • Pianificazione della capacità — calcola il numero totale di partecipanti attivi in tutte le riunioni sul server.
  • Monitoraggio — identifica riunioni senza moderatore o riunioni che presentano problemi.
  • Pulizia automatica — trova riunioni che esistono da molto tempo senza alcun partecipante.

Suggerimenti e buone pratiche

Poiché getMeetings restituisce tutte le riunioni sul server (non solo quelle in esecuzione), filtra i risultati in base al campo running se hai bisogno solo delle riunioni attive.

La risposta contiene informazioni sensibili come nomi dei partecipanti, ID utente e password. Chiama sempre questo endpoint solo da codice lato server. Non esporlo mai ad applicazioni lato client o agli utenti finali.

Non è previsto il supporto alla paginazione per questo endpoint. Su server con molte riunioni simultanee, la risposta può diventare molto grande e influire sulle prestazioni. Valuta di memorizzare nella cache i risultati se interroghi frequentemente.

Domande frequenti

No. Restituisce tutte le riunioni che attualmente esistono sul server, incluse quelle che sono state create ma non hanno ancora partecipanti. Filtra in base al campo running se hai bisogno solo delle riunioni attive.

getMeetings restituisce un riepilogo di tutte le riunioni sul server, mentre getMeetingInfo restituisce informazioni dettagliate su una singola riunione specifica. Inoltre, l'elenco dei partecipanti in getMeetings include anche gli utenti che hanno abbandonato la riunione di recente (per impostazione predefinita, negli ultimi 60 secondi), mentre getMeetingInfo elenca solo gli utenti attualmente connessi.

Sì. Se non è stata passata alcuna password a create, BigBlueButton ne genera una casuale, quindi entrambi i campi sono inclusi per ogni riunione.

Controlla il campo isBreakout. Se è true, la riunione è una stanza per sottogruppi e includerà campi aggiuntivi come parentMeetingID, sequence e freeJoin. La riunione principale avrà un elenco breakoutRooms contenente gli ID delle sue stanze per sottogruppi.

No. L'API BigBlueButton non supporta la paginazione per getMeetings. Tutte le riunioni vengono restituite in un'unica risposta. Per i server con un numero molto elevato di riunioni, valuta l'implementazione della cache o chiama l'endpoint meno frequentemente per ridurre il carico sul server.