Capitolo 20 POST

insertDocument – Inserisci presentazione

L'endpoint insertDocument ti consente di caricare una o più presentazioni in una riunione BigBlueButton già in esecuzione senza interrompere il presentatore corrente. I documenti vengono elaborati in background e diventano disponibili come presentazioni aggiuntive alle quali il presentatore può passare in qualsiasi momento.

Questo endpoint è documentato solo in modo leggero nella documentazione ufficiale dell'API BigBlueButton. I dettagli su codici di errore, limiti di dimensione dei file e il formato esatto della risposta XML non sono specificati ufficialmente. undocumented

Endpoint

POST https://api-guide.bbbserver.com/bigbluebutton/api/insertDocument?meetingID=replace-with-meeting-id&checksum=replace-with-checksum
Content-Type: application/xml

Questo endpoint richiede una richiesta POST con un body XML. I dati del documento vengono inviati nel body della richiesta, non come parametri URL.

Parametri URL

Parametro Tipo Obbligatorio Predefinito Descrizione
meetingID String Sì — L'identificatore della riunione in esecuzione che deve ricevere il documento.

Body XML — Attributi del documento

Il body della richiesta deve contenere una struttura XML con un elemento <module name="presentation"> che racchiude uno o più elementi <document>. Ogni documento può essere caricato tramite URL oppure come contenuto Base64 inline.

Attributo Tipo Obbligatorio Predefinito Descrizione
url String No — URL che punta al file della presentazione. Utilizzato per i caricamenti basati su URL. Il server recupera il file da questo URL.
filename String No — Nome file per i caricamenti basati su URL. Aiuta a rilevare il tipo di file quando l'URL non contiene un'estensione del file.
name String No — Nome file per caricamenti inline Base64. Quando si usa questo attributo, il testo dell'elemento deve contenere il contenuto del file codificato in Base64.
current Boolean No false Se impostato su true, questa presentazione viene attivata immediatamente come presentazione corrente dopo il caricamento.
downloadable Boolean No false Se impostato su true, i partecipanti sono autorizzati a scaricare il file della presentazione.
removable Boolean No true Se impostato su true, il presentatore è autorizzato a rimuovere la presentazione dalla riunione.

Esempio di richiesta — Caricamento basato su URL

curl --request POST \
    --url "https://api-guide.bbbserver.com/bigbluebutton/api/insertDocument?meetingID=replace-with-meeting-id&checksum=replace-with-checksum" \
  --header "Content-Type: application/xml" \
  --data '<?xml version="1.0" encoding="UTF-8"?>
<modules>
  <module name="presentation">
        <document url="https://api-guide.bbbserver.com/files/slides.pdf" filename="slides.pdf"
              downloadable="true" removable="true" current="true"/>
  </module>
</modules>'

Richiesta di esempio — Caricamento inline Base64

curl --request POST \
    --url "https://api-guide.bbbserver.com/bigbluebutton/api/insertDocument?meetingID=replace-with-meeting-id&checksum=replace-with-checksum" \
  --header "Content-Type: application/xml" \
  --data '<?xml version="1.0" encoding="UTF-8"?>
<modules>
  <module name="presentation">
    <document name="inline-slides.pdf">
      JVBERi0xLjQK... (Base64-encoded content)
    </document>
  </module>
</modules>'

Risposta di esempio

Una chiamata riuscita restituisce il seguente XML: 

<response>
  <returncode>SUCCESS</returncode>
</response>

Una risposta SUCCESS conferma che il documento è stato accettato per l'elaborazione. Non garantisce che la conversione del file sia stata completata con successo. Se gli errori di conversione vengano riportati tramite la risposta API non è documentato ufficialmente. undocumented

Confronto con il caricamento della presentazione create

Puoi anche caricare presentazioni durante la creazione della riunione utilizzando l'endpoint create. La tabella seguente evidenzia le differenze tra i due approcci:

Aspetto create insertDocument
Tempistica Prima dell'inizio della riunione Mentre la riunione è in corso
Interruzione Nessuna (la prima diapositiva viene caricata all'accesso) Nessuna (caricamento in background)
current attributo Supportato Supportato
Documenti multipli Supportato Supportato

Suggerimenti

Se vuoi che la nuova presentazione diventi attiva immediatamente, imposta current="true" sull'elemento document. Altrimenti il presentatore dovrà passare manualmente ad essa usando il selettore delle presentazioni nell'interfaccia della riunione.

  • Gli stessi formati di file supportati dal normale caricamento delle presentazioni sono supportati anche qui (PDF, PPTX, DOCX, immagini, ecc.).
  • Puoi inserire più documenti in una singola richiesta aggiungendo altri elementi document all'interno del blocco module.
  • Per i caricamenti basati su URL, imposta sempre l'attributo filename quando l'URL non contiene un'estensione di file riconoscibile. Questo aiuta BigBlueButton a determinare il tipo di file corretto.
  • Per file di grandi dimensioni, è consigliato il caricamento tramite URL invece del caricamento inline Base64 per mantenere ridotto il payload della richiesta.

Casi d’uso

  • Distribuisci dinamicamente diapositive da un LMS o da un sistema di gestione dei contenuti durante una sessione dal vivo.
  • Aggiungi materiale supplementare a una riunione dopo che è già iniziata.
  • Crea bot automatizzati che inseriscono ordini del giorno, note della riunione o report nelle riunioni in corso.
  • Consenti ai sistemi esterni di inviare contenuti aggiornati senza richiedere al presentatore di lasciare la riunione.
Su bbbserver.de, questo endpoint è disponibile in tutti i piani. Puoi chiamarlo usando le credenziali API che trovi nel pannello di gestione del server. Si applicano gli stessi limiti di dimensione dei file del normale caricamento delle presentazioni.

Domande frequenti

L'endpoint insertDocument è disponibile in BigBlueButton 2.5 e versioni successive. Non è disponibile nelle versioni precedenti come 2.4 o antecedenti.

Sì, se l'attributo removable è stato impostato su true (che è il valore predefinito). Il presentatore può rimuovere la presentazione tramite l'interfaccia della riunione. Non esiste un endpoint API dedicato per rimuovere una presentazione da una riunione in corso.

L'API restituirà una risposta FAILED che indica che la riunione non è stata trovata. I documenti possono essere inseriti solo nelle riunioni attualmente in esecuzione.

Sono supportati gli stessi formati del normale caricamento delle presentazioni, inclusi PDF, PPTX, DOCX, ODT e i formati immagine comuni. Il server converte internamente i file non-PDF in PDF usando LibreOffice.

I limiti di dimensione dei file sono determinati dalla configurazione del server BigBlueButton. I limiti esatti non sono specificati tramite l'API e dipendono dalle impostazioni lato server. Contatta l'amministratore del tuo server per i dettagli.

Puoi indirizzare una breakout room usando il suo specifico meetingID. Ogni breakout room ha il proprio identificatore univoco della riunione che può essere ottenuto tramite l'endpoint getMeetings o getMeetingInfo.

No. Una risposta SUCCESS conferma solo che il server ha accettato il documento per l'elaborazione. Il fatto che la conversione sia riuscita non viene riportato in modo affidabile nella risposta API. Questo comportamento non è documentato ufficialmente.