Kapitel 18

Meta-parametre & callbacks

Metaparametre er frit definerbare nøgle-værdi-par, som du sender, når du opretter et møde. De gør det muligt at tilføje brugerdefinerede metadata, udløse automatiserede callbacks ved bestemte hændelser, styre anonymisering af optagelser og dokumentere oprindelsen af et møde for LMS-integrationer.

Sådan fungerer meta-parametre

Meta-parametre sendes i API-kaldet create ved hjælp af navngivningskonventionen meta_=. Du kan knytte et vilkårligt antal meta-parametre til et enkelt møde. 

create?meetingID=replace-with-meeting-id&meta_coursename=Computer+Science+101&meta_instructor=Prof.+Mueller&checksum=replace-with-checksum
  • Meta-parametre returneres i svarene fra getMeetingInfo og getRecordings.
  • Optagelser kan filtreres efter meta-værdier ved hjælp af getRecordings?meta_=.
  • Metadata for optagelser kan opdateres efterfølgende via updateRecordings.

Callback-meta-parametre

Visse metaparametre har en særlig betydning og udløser HTTP-callbacks, når bestemte hændelser opstår. De gør det muligt for din applikation automatisk at reagere på hændelser i mødelivscyklussen.

meta_endCallbackUrl

Udløser en HTTP GET-anmodning til den angivne URL, når mødet slutter. 

meta_endCallbackUrl=https://api-guide.bbbserver.com/callbacks/meeting-ended
Egenskab Værdi
HTTP-metode GET
Udløser Når mødet slutter
Callback-parametre meetingID — møde-id'et
recordingmarks — true hvis optagelsen indeholder markeringer, ellers false

Eksempel på callback-anmodning: 

GET https://api-guide.bbbserver.com/callbacks/meeting-ended?meetingID=replace-with-meeting-id&recordingmarks=true

meta_bbb-recording-ready-url

Udløser en HTTP POST-anmodning, når optagelsen er fuldt behandlet og publiceret. 

meta_bbb-recording-ready-url=https://api-guide.bbbserver.com/callbacks/recording-ready
Egenskab Værdi
HTTP-metode POST
Udløser Når optagelsen er fuldt behandlet og publiceret
Sikkerhed Parametre er JWT-signerede (JSON Web Token)
POST-body Indeholder signerede data med oplysninger om optagelsen

Forveksl ikke dette callback med endCallbackUrl. Behandling af optagelser kan tage betydelig tid, efter at mødet er afsluttet. recording-ready-callbacket udløses først, når behandlingen er fuldført.

meta_analytics-callback-url

Udløser en HTTP POST-anmodning med aggregerede analysedata, efter at mødet er afsluttet. 

meta_analytics-callback-url=https://api-guide.bbbserver.com/callbacks/analytics
Egenskab Værdi
HTTP-metode POST
Udløser Efter mødet slutter (post-events hook)
Godkendelse JWT-token sendt som Authorization: Bearer-header (HS512, signeret med den delte BBB-hemmelighed, gyldig i 24 timer)
Body-format JSON-objekt indeholdende version, meeting_id, internal_meeting_id, data
Dataindhold Varighed af deltagelse, aktivitetsstatistik, chatbrug og andre aggregerede mødehændelser

Analytics-callback-URL'en stammer fra BigBlueButton-kodebasen og er ikke fuldt dokumenteret i den officielle API-dokumentation. Det præcise schema for analytics-dataobjektet er ikke standardiseret og kan ændre sig mellem versioner. undocumented

Bemærk forskellen i levering af JWT: analytics-callback-url sender JWT som en HTTP Authorization-header, mens bbb-recording-ready-url inkluderer JWT direkte i POST-bodyen.

Parametre til anonymisering af optagelser

Disse meta-parametre styrer, om navnene på afsendere af chatbeskeder anonymiseres i behandlede optagelser. De er nyttige til overholdelse af privatlivskrav og databeskyttelseskrav.

Parameter Type Standard Beskrivelse
meta_bbb-anonymize-chat Boolean false Anonymiserer afsendere af chatbeskeder i behandlede optagelser. Påvirker kun beskeder fra seere (ikke-moderatorer). Moderatornavne forbliver synlige.
meta_bbb-anonymize-chat-moderators Boolean false Anonymiserer desuden afsendere af moderatorers chatbeskeder i optagelser. Kræver typisk også, at meta_bbb-anonymize-chat=true er sat.
create?meetingID=replace-with-meeting-id&meta_bbb-anonymize-chat=true&meta_bbb-anonymize-chat-moderators=true&checksum=replace-with-checksum

Anonymiseringsparametrene er kun kort nævnt i den officielle API-dokumentation. Deres adfærd er udledt af BigBlueButton-kildekoden. undocumented

LMS-integrationsparametre

Mange LMS-plugins sætter automatisk metaparametre for at dokumentere oprindelsen af et møde. Disse er informative og påvirker ikke mødeadfærden, men de er nyttige til revision og rapportering.

Parameter Eksempel Beskrivelse
meta_bbb-origin greenlight, moodle Kildeapplikationen, der oprettede mødet.
meta_bbb-origin-version v3.1.0 Version af kildeapplikationen.
meta_bbb-origin-server-name api-guide.bbbserver.com Værtsnavn for kildeapplikationen.
meta_bbb-context Course: Computer Science Kontekstinformation såsom kursusnavn.
meta_bbb-context-id course-42 Kontekstidentifikator til programmatisk brug.

Bedste praksis for brugerdefinerede meta-parametre

  • Brug beskrivende nøglenavne (f.eks. meta_department, meta_project), der tydeligt angiver værdien formål.
  • URL-kod værdier, der indeholder specialtegn, mellemrum eller ikke-ASCII-tegn.
  • Brug metaparametre til integration med eksterne systemer såsom CRMs, læringsplatforme eller analytics-dashboards.
  • Opdater optagelsesmetadata efterfølgende ved hjælp af endpointet updateRecordings for at tilføje eller rette metadata.

Kombinér meta-parametre med filtrering i getRecordings for at opbygge effektive søge- og kategoriseringsarbejdsgange for dine optagelser. Du kan for eksempel filtrere efter meta_department=engineering for kun at hente optagelser fra ingeniørmøder.

Ofte stillede spørgsmål

Der er ingen fast grænse for antallet af meta-parametre. Da de dog sendes som URL-forespørgselsparametre, bør du holde dig inden for praktiske grænser for URL-længde (typisk 2.000 til 8.000 tegn afhængigt af webserverens konfiguration).

Metaparametre, der sættes under create-kaldet, kan ikke ændres, mens mødet kører. Optagelsesmetadata kan dog opdateres efter behandling ved hjælp af updateRecordings-endpointet.

endCallbackUrl udløses straks, når mødet slutter, ved hjælp af en simpel GET-anmodning. bbb-recording-ready-url udløses langt senere, først efter at optagelsen er fuldt behandlet og publiceret, og bruger en JWT-signeret POST-anmodning.

Detaljerne om JWT-signeringen er ikke fuldt specificeret i den officielle dokumentation. Baseret på BigBlueButton-kildekoden signeres JWT med serverens delte hemmelighed. De præcise claims og algoritmen bør verificeres i forhold til din specifikke BigBlueButton-version.

De fleste metaparametre er rent informative og ændrer ikke, hvordan mødet fungerer. Undtagelserne er callback-URL'er, som udløser HTTP-anmodninger ved hændelser, og anonymiseringsparametre, som påvirker, hvordan optagelser behandles.

Ja. Nøgler til metaparametre behandles som strenge, der skelner mellem store og små bogstaver. For eksempel vil meta_Department og meta_department blive gemt som to separate parametre. Brug konsekvent store og små bogstaver i din integration for at undgå dubletter.