API-Version: 4.x neueste 3.x

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.

Kapitel 7 GET POST

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 enforceLayout ist 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.

Häufig gestellte Fragen

Nein. Anders als die meisten BigBlueButton-API-Endpunkte verwendet getJoinUrl session-token-Authentifizierung. Sie übergeben den Parameter sessionToken, anstatt eine Prüfsumme mit dem Shared Secret zu berechnen.

Nein. Der Benutzer muss bereits über den normalen Endpunkt join beigetreten sein und ein gültiges, aktives sessionToken besitzen. Der Endpunkt kann nicht verwendet werden, um initiale Join-URLs zu erzeugen.

Beide Sitzungen — die ursprüngliche und die neue — existieren parallel. Der Benutzer erscheint nur einmal in der Teilnehmerliste, aber beide Browserfenster oder Geräte bleiben aktiv.

Wie die anderen sitzungstokenbasierten Endpunkte, die intern vom Client verwendet werden (stuns, learningDashboard), gibt getJoinUrl den Wert JSON zurück. Die durch Prüfsummen geschützten API-Endpunkte geben XML zurück.

Der Endpunkt getJoinUrl wurde in BigBlueButton 3.0 eingeführt. Er ist in früheren Versionen nicht verfügbar.

Nicht unbedingt. Eine konfigurierbare Blockliste kann bestimmte userdata-Schlüssel für Nicht-Moderator-Benutzer einschränken. Wenn die Blockliste auf "all" gesetzt ist, werden für Zuschauer keine userdata-Parameter übergeben. Moderatoren umgehen die Blockliste außer in breakout rooms.