Kapitel 1

API-overblik

BigBlueButton-API'et er en HTTP-baseret grænseflade, der gør det muligt for eksterne applikationer — såsom læringsplatforme, webportaler og brugerdefinerede integrationer — programmæssigt at oprette, styre og overvåge møder. Alle API-kald sikres ved hjælp af en checksum-mekanisme baseret på en shared secret.

Sådan fungerer API'et

BBB-API'et følger en simpel request-response-model. Du sender en HTTPS-anmodning til et bestemt endepunkt på din BigBlueButton-server, og serveren svarer med et XML-dokument, der angiver succes eller fejl.

  • Protokol: HTTPS (GET eller POST)
  • Basis-URL: https://<server>/bigbluebutton/api/<endpoint>?<parameters>&checksum=<hash>
  • Svarformat: XML (med nogle få undtagelser, der returnerer JSON)
  • Godkendelse: Shared-secret-baseret checksum (ingen OAuth, ingen API-nøgle)

Endpoint-kategorier

API-endpoints er organiseret i følgende kategorier:

Kategori Endpoints Beskrivelse
Administration create, join, end Opret, deltag i og afslut møder
Overvågning isMeetingRunning, getMeetings, getMeetingInfo Overvåg igangværende møder
Optagelser getRecordings, publishRecordings, deleteRecordings, updateRecordings, getRecordingTextTracks, putRecordingTextTrack Administrer mødeoptagelser
Webhooks hooks/create, hooks/list, hooks/destroy Hændelsesnotifikationer i realtid
Beskeder sendChatMessage Send chatbeskeder BBB 3.0+
Session getJoinUrl, feedback Sessionsstyring BBB 3.0+

HTTP-metoder

De fleste endepunkter accepterer både GET- og POST-anmodninger. Når du bruger POST, skal du bemærke, at checksum beregnes ud fra URL'ens query string, ikke ud fra request bodyen. POST-bodyen kan indeholde yderligere data såsom præsentations-XML eller tilsidesættelser af klientindstillinger.

Selv når du sender en POST-anmodning, skal checksum beregnes ud fra query string-parametrene i URL'en. Body-indholdet indgår ikke i beregningen af checksum.

Svarformat

Hvert API-svar indeholder mindst følgende felter: 

<response>
  <returncode>SUCCESS</returncode>
  <!-- or -->
  <returncode>FAILED</returncode>
  <messageKey>errorKey</messageKey>
  <message>Human-readable error message</message>
</response>
Felt Beskrivelse
returncode Altid SUCCESS eller FAILED
messageKey Maskinlæsbar fejlkode (findes kun ved fejl eller advarsler)
message Menneskelæsbar beskrivelse af fejlen eller advarslen

API-versionering

BigBlueButton-API'et bruger ikke traditionel URL-baseret versionsstyring (ingen stier som /v1/, /v2/). I stedet tilføjes nye parametre på en bagudkompatibel måde, og forældede parametre markeres tilsvarende, men fjernes ikke med det samme.

BBB-version Bemærkelsesværdige API-ændringer
2.2 Lock-indstillinger, allowModsToUnmuteUsers
2.4 logo, meetingLayout, allowModsToEjectCameras, Læringsdashboard
2.5 disabledFeatures, SHA-384/SHA-512-understøttelse, webhook eventID filter
2.6 notifyRecordingIsOn, presentationUploadExternalUrl, mørk tilstand
2.7 preUploadedPresentation (enkelt URL), optagelses-pagination
3.0 sendChatMessage, getJoinUrl, feedback, pluginManifests, clientSettingsOverride, role erstatter password på join

Udokumenterede endepunkter

Følgende endepunkter findes i BigBlueButton-kildekoden, men er ikke dækket af den officielle dokumentation. De bruges internt og kan ændres uden varsel.

Endepunkt Metode Beskrivelse Status
/api/stuns GET POST Returnerer STUN/TURN-serverkonfiguration for WebRTC-forbindelser Undocumented
/api/signOut GET POST Afslut session / log bruger ud Undocumented
/api/guestWait GET Forespørg lobbystatus for gæster, der venter på moderatorgodkendelse Undocumented
/api/getSessions GET POST Hent sessionsoplysninger Undocumented
/api/learningDashboard GET POST Hent data for læringsanalyse Undocumented

GraphQL-mutationer (handlinger i mødet)

Siden BBB 3.0 håndteres de fleste realtidshandlinger i et møde via GraphQL-mutationer over WebSocket. Disse bruges internt af BBB HTML5-klienten og er ikke en del af det klassiske REST-API.

Kategori Antal Eksempler
Chat 9 chatSendMessage, chatDeleteMessage, chatEditMessage
Brugeradministration 26 userSetMuted, userSetRole, userEjectFromMeeting
Præsentation 11 presentationSetCurrent, presentationSetPage
Mødestyring 8 meetingEnd, meetingRecordingSetStatus
Grupperum 7 breakoutRoomCreate, breakoutRoomEndAll
Afstemninger 4 pollCreate, pollSubmitUserVote, pollPublishResult
Timer 8 timerStart, timerStop, timerReset
Udvidelser 8 pluginDataChannelPushEntry, pluginPersistEvent

GraphQL-laget er beregnet til intern klientbrug og giver ikke et stabilt offentligt API. Mutationer og deres parametre kan ændres mellem BBB-versioner uden varsel.

Forudsætninger

Før du kan begynde at bruge BigBlueButton-API'et, skal du sikre dig, at du har følgende på plads:

En kørende BigBlueButton-server (version 3.0 anbefales)

Den delte hemmelighed (også kaldet "security salt"), konfigureret i /etc/bigbluebutton/bbb-web.properties

HTTPS-adgang til serveren

En server-sideapplikation, der genererer API-kaldene — shared secret må aldrig eksponeres på klientsiden

Eksponér aldrig shared secret i klient-sidekode (JavaScript, mobilapps). Alle API-kald skal genereres på serversiden for at forhindre uautoriseret adgang til din BigBlueButton-server.

bbbserver.de — IntegrationAPI

Din API-URL og shared secret er tilgængelige i administrationspanelet bbbserver under Customer Settings → IntegrationAPI. IntegrationAPI kan aktiveres eller deaktiveres derfra.

Plugin-kompatibilitet

Følgende platforme fungerer umiddelbart — indtast blot API-URL'en og shared secret:

  • Moodle (BigBlueButtonBN)
  • ILIAS
  • Nextcloud
  • WordPress
  • Greenlight

Forskelle i forhold til standard-API'et

Emne Detalje
maxParticipants / duration Bruges til kapacitetsreservation, ikke kun som grænser. Standardværdier, hvis ikke angivet: 5 deltagere, 60 minutter.
duration adfærd Afslutter IKKE møder automatisk — bruges kun til kapacitetsplanlægning.
Ekstra parameter deactivateBbbserverDefaultChatTexts — til white-labeling-formål.
Utilgængelige endpoints updateRecordings, getDefaultConfigXML, setConfigXML, getRecordingTextTracks, putRecordingTextTracks
Webhooks Kun mødespecifikt, med privatlivs-obfuskering.
Rate limits Ingen hastighedsbegrænsninger på IntegrationAPI.

Ud over IntegrationAPI tilbyder bbbserver.de et separat System API med platformspecifikke funktioner såsom kontoadministration og brugsstatistik. System API er ikke BBB-kompatibelt og er ikke dækket af denne vejledning.

Ofte stillede spørgsmål

API'et bruger en shared-secret-baseret checksum-mekanisme. Hver anmodning skal indeholde en parameter checksum, der beregnes ved at hashe API-kaldets navn, query string og shared secret. Der er ingen OAuth- eller API-nøglegodkendelse.

Standardformatet for svar er XML. Nogle få specifikke endepunkter kan returnere JSON, men langt de fleste API-kald returnerer XML-dokumenter med et felt returncode, der angiver SUCCESS eller FAILED.

Nej, BigBlueButton-API'et bruger ikke URL-baseret versionsstyring. Nye parametre tilføjes på en bagudkompatibel måde, og forældede parametre markeres, men fjernes ikke med det samme. Du bør altid kontrollere ændringsloggen for din BBB-version.

Nej. GraphQL-laget er designet til intern brug af BBB HTML5-klienten. Det giver ikke et stabilt offentligt API, og mutationer kan ændres mellem versioner uden varsel. Brug REST-API'et til alle eksterne integrationer.

bbbserver.de IntegrationAPI er en proxy, der fuldt ud replikerer standard-BBB-API'et. Eksterne applikationer forbinder til den, som om de kommunikerer med en enkelt BBB-server. De væsentligste forskelle er kapacitetsreservation via maxParticipants/duration, nogle få utilgængelige endepunkter og mødespecifikke webhook-begrænsninger.

BigBlueButton 2.5 og senere understøtter SHA-256, SHA-384 og SHA-512 til beregning af checksum. Tidligere versioner bruger SHA-1 eller SHA-256. Af sikkerhedshensyn anbefales det at bruge SHA-256 eller højere.