Sie sehen die API-Dokumentation für BigBlueButton 3.x. Die aktuelle Version ist BigBlueButton 4.x. Planen Sie ein Upgrade? Der Migrationsleitfaden listet alle erforderlichen Änderungen an Ihren API-Aufrufen auf.
getJoinUrl – Beitritts-URL generieren
Der Endpunkt getJoinUrl erzeugt eine neue Join-URL für einen Benutzer, der bereits einem Meeting beigetreten ist. Dadurch kann derselbe Benutzer zusätzliche Sitzungen öffnen — zum Beispiel auf einem zweiten Bildschirm oder nach einem Gerätewechsel — ohne sich erneut über den normalen Ablauf von join authentifizieren zu müssen. BBB 3.0+
Endpunkt
GET/POST https://api-guide.bbbserver.com/bigbluebutton/api/getJoinUrl?<parameters> Dieser Endpunkt verwendet session-token-Authentifizierung anstelle des standardmäßigen shared-secret-Prüfsummenmechanismus. Der Benutzer muss bereits über den Endpunkt join beigetreten sein und ein gültiges sessionToken besitzen.
Im Gegensatz zu den durch Prüfsummen geschützten BigBlueButton-API-Endpunkten, die XML zurückgeben, gibt dieser Endpunkt JSON zurück.
Erforderliche Parameter
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
sessionToken | String | Ja | — | Das sessionToken des Benutzers, für den eine neue Join-URL erzeugt werden soll. |
Optionale Parameter
| Parameter | Typ | Erforderlich | Standard | Beschreibung |
|---|---|---|---|---|
replaceSession | Boolean | Nein | false | Wenn auf true gesetzt, wird die ursprüngliche Sitzung ungültig gemacht und durch die neue ersetzt (Sitzungsübertragung). |
sessionName | String | Nein | — | Ein beschreibender Name für die neue Sitzung. |
enforceLayout | String | Nein | — | Das Layout für die neue Sitzung überschreiben. |
userdata-* | String | Nein | — | Benutzerdefinierte Nutzerdaten für die neue Sitzung. Schlüssel müssen mit userdata- beginnen. |
Anwendungsfälle
- Hybride Szenarien — ein Moderator verwendet einen Bildschirm für die Präsentation und einen zweiten Bildschirm für die Teilnehmeransicht.
- Gerätewechsel — ein Benutzer wechselt während eines Meetings von seinem Desktop zu einem Tablet.
- Mehrbildschirm-Setups — ein Konferenzraum mit mehreren Displays, die unterschiedliche Layouts anzeigen.
Verhalten
Die neue Sitzung teilt die Benutzeridentität mit der ursprünglichen Sitzung. Der Benutzer erscheint nur einmal in der Teilnehmerliste.
Ohne replaceSession existieren beide Sitzungen parallel.
Mit replaceSession=true wird die ursprüngliche Sitzung ungültig gemacht und der Benutzer nahtlos in die neue Sitzung übertragen.
Beispielanfrage
GET https://api-guide.bbbserver.com/bigbluebutton/api/getJoinUrl?sessionToken=replace-with-session-token&sessionName=SecondScreen&enforceLayout=PRESENTATION_FOCUS Beispielantwort (Erfolg)
{
"response": {
"returncode": "SUCCESS",
"message": "Join URL provided successfully.",
"url": "https://api-guide.bbbserver.com/bigbluebutton/api/join?...&checksum=replace-with-checksum"
}
} Fehlerantworten
Wenn eine Anfrage fehlschlägt, gibt der Endpunkt ein JSON-Objekt mit einer beschreibenden Fehlermeldung zurück:
{
"response": {
"returncode": "FAILED",
"message": "<error message>"
}
} | Nachricht | Bedeutung |
|---|---|
You must provide a session token | Der Parameter sessionToken fehlt. |
Invalid session token | Das sessionToken ist ungültig oder abgelaufen. |
Invalid Session | Die Anfrage enthält nicht das von join erstellte HTTP-Sitzungscookie, und das Meeting erlaubt keine Anfragen ohne Sitzung (allowRequestsWithoutSession, Standardwert false). |
Access denied | Der Benutzer wurde nicht gefunden oder hat keine Berechtigung. |
Meeting not found | Das Meeting existiert nicht oder läuft nicht mehr. |
In BigBlueButton 3.0 wird nur Meeting not found als JSON-Fehler zurückgegeben. Bei den anderen oben aufgeführten Fehlern sendet der Endpunkt keine JSON-Antwort.
Userdata Blockliste
Bei der Verwendung von userdata-*-Parametern mit getJoinUrl schränkt eine konfigurierbare Blockliste (getJoinUrlUserdataBlocklist) bestimmte userdata-Schlüssel für Nicht-Moderator-Benutzer ein:
- Wenn die Blockliste den Wert
"all"enthält, werden alle userdata-Parameter für Zuschauer blockiert. - Moderatoren umgehen die Blockliste, ausgenommen in breakout rooms.
- Der Parameter
enforceLayoutist unabhängig von der Blockliste immer erlaubt.
Der Endpunkt ist nur verfügbar, wenn der Benutzer bereits ein gültiges sessionToken besitzt — das heißt, er muss dem Meeting zuerst über den normalen Endpunkt join beigetreten sein. Abgelaufene Tokens werden abgelehnt.
Für Gerätewechsel-Anwendungsfälle setzen Sie replaceSession=true, um die Sitzung nahtlos auf das neue Gerät zu übertragen. Dadurch wird vermieden, dass auf dem alten Gerät eine veraltete Sitzung bestehen bleibt, die in der Teilnehmerliste für Verwirrung sorgen könnte.