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 24

bbbserver.de IntegrationAPI

Il IntegrationAPI su bbbserver.de è un proxy che rispecchia l'API standard di BigBlueButton distribuendo al contempo le conferenze su più server con capacità sufficiente in background.

Dove trovare l'URL API e il segreto condiviso

L'URL della tua API e shared secret sono disponibili nel pannello di amministrazione di bbbserver, nella sezione Integrazioni e API → API di integrazione. Qui puoi anche abilitare o disabilitare IntegrationAPI.

Non hai bisogno dell'accesso shell o dei comandi bbb-conf per recuperare le credenziali quando utilizzi bbbserver.de.

Compatibilità Plugin

Le seguenti piattaforme funzionano subito. Nella maggior parte dei casi, devi solo inserire l'URL API e il shared secret nell'integrazione standard di BigBlueButton.

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

Differenze rispetto all'API standard

Il IntegrationAPI rispecchia fedelmente l'API standard di BBB, ma diversi comportamenti su bbbserver.de sono abbastanza diversi da dover essere compresi esplicitamente durante l'integrazione.

Riserva di capacità

Quando crei una conferenza tramite il IntegrationAPI, bbbserver.de deve assegnarla a un server backend con risorse residue sufficienti. Per questo motivo, maxParticipants e duration agiscono come una richiesta di prenotazione per la capacità di connessione e di esecuzione, anziché limitarsi a documentare l'utilizzo previsto.

Entrambi i valori devono quindi essere forniti nelle chiamate create. Se vengono omessi, vengono utilizzati i valori predefiniti della sezione Integrazioni e API → API di integrazione.

Esempio di prenotazione della capacità

L'esempio seguente mostra come la pianificazione della capacità basata sulla prenotazione cambia il comportamento rispetto alla normale ipotesi di un singolo server:

Situazione Effetto sulla capacità
Il tuo account consente 20 connessioni simultanee Questo è il pool totale di connessioni disponibile per le prenotazioni attive.
La conferenza A viene creata con maxParticipants = 15 e duration = 120 minutes La conferenza A riserva 15 delle 20 connessioni disponibili per l'intera finestra di prenotazione di due ore.
Un'altra conferenza viene creata durante queste due ore Non può riservare più delle 5 connessioni rimanenti finché la conferenza A si trova ancora nella sua finestra temporale riservata.
Le due ore sono trascorse e la conferenza A è ancora in corso La conferenza A può continuare, ma la sua capacità riservata non è più garantita né protetta.
La conferenza B viene creata successivamente con maxParticipants = 10 Il sistema può terminare automaticamente la conferenza A a favore della conferenza B perché la conferenza A non è più protetta da una prenotazione attiva.

Comportamento del parametro "duration"

Su bbbserver.de, duration fa parte della pianificazione della capacità. La riunione non termina esattamente quando viene superato il tempo configurato. Invece, bbbserver.de termina automaticamente una riunione nei seguenti casi:

  • 10 minuti dopo l'orario di fine previsto, se non ci sono più partecipanti connessi.
  • Per gli abbonamenti di prova: all'orario di fine previsto.
  • Al più tardi 24 ore dopo l'inizio.
  • Quando la capacità è necessaria per un'altra riunione e la riunione non è più protetta dalla sua prenotazione (vedi l'esempio sopra).

Se il tuo flusso di lavoro richiede un orario di fine fisso, pianifica una chiamata API end esplicita.

Parametro aggiuntivo per il white-labeling

deactivateBbbserverDefaultChatTexts accetta true o false e il valore predefinito è false.

Finché rimane false, bbbserver.de inserisce un proprio testo prima del tuo testo welcome: un link a bbbserver.de, istruzioni per l'accesso telefonico e un avviso sull'hosting. I moderatori vedono inoltre un testo con il numero massimo di partecipanti, la fascia oraria prevista e una nota che avverte che la riunione potrebbe essere terminata quando la capacità è necessaria. Imposta il parametro su true se vuoi disabilitare questi testi predefiniti per la personalizzazione white-label.

I testi predefiniti possono anche essere nascosti nelle impostazioni del cliente. In tal caso, il testo per i moderatori viene sempre omesso e il testo di benvenuto viene omesso se passi un tuo testo welcome.

Endpoint non disponibili

Le seguenti chiamate API esistono nell'API standard, ma non sono implementate dalla IntegrationAPI:

getJoinUrl, sendChatMessage, updateRecordings, getRecordingTextTracks, putRecordingTextTrack, hooks/ping

Registrazioni non pubblicate

Se annulli la pubblicazione di una registrazione, questa viene indicata come unpublished nell'API e i servizi esterni la gestiscono di conseguenza. Tuttavia, la registrazione stessa può ancora essere aperta se si conosce il link di riproduzione.

Webhook

Gli hook devono essere registrati per ID riunione specifici. La registrazione per tutte le riunioni senza specificare un ID riunione non è supportata.

Gli eventi webhook vengono filtrati prima di essere inoltrati: vengono trasmessi solo i campi selezionati. I dati dei partecipanti, come il nome, external-user-id, lo user agent e i parametri userdata, sono inclusi in chiaro. Tutti gli altri campi, come gli indirizzi IP dei partecipanti, i messaggi della chat e i dati dei sondaggi, vengono rimossi.

Limiti di frequenza

Non ci sono limiti di frequenza sul IntegrationAPI.

Oltre al IntegrationAPI, bbbserver.de offre un System API separato con funzionalità specifiche della piattaforma come gestione dell'account e statistiche di utilizzo. Il System API non è compatibile con BBB e non è trattato in questa guida.

Domande frequenti

Apri il pannello di amministrazione di bbbserver e vai a Integrazioni e API → API di integrazione. Qui puoi visualizzare l'URL dell'API, copiare shared secret e abilitare o disabilitare IntegrationAPI.

Il IntegrationAPI è progettato per funzionare con integrazioni standard di BigBlueButton come Moodle, ILIAS, Nextcloud, WordPress e Greenlight.

bbbserver.de IntegrationAPI rispecchia l'API standard di BBB, ma maxParticipants e duration riservano capacità, le riunioni non terminano esattamente allo scadere della durata configurata, deactivateBbbserverDefaultChatTexts controlla i testi della piattaforma nella chat, alcuni endpoint non sono disponibili e i webhook sono specifici per ogni riunione.

Gli amministratori possono abilitare temporaneamente il registro delle richieste (modalità sviluppatore) nella pagina Integrations & API → Integration API. Rimane attivo per un giorno e conserva fino a 300 voci, ciascuna per 24 ore. Non vengono registrate le richieste senza autenticazione valida, le richieste che ricevono una risposta 404 e le risposte inoltrate senza modifiche di getMeetingInfo, insertDocument e hooks/list. Il registro delle richieste consente di testare l'API stessa, testare la propria integrazione e analizzare il comportamento dell'API nella pratica.