Kapitel 20 POST

insertDocument – Indsæt præsentation

insertDocument-endpointet gør det muligt at uploade én eller flere præsentationer til et allerede kørende BigBlueButton-møde uden at afbryde den nuværende præsentator. Dokumenter behandles i baggrunden og bliver tilgængelige som yderligere præsentationer, som præsentatoren til enhver tid kan skifte til.

Dette endpoint er kun sparsomt dokumenteret i den officielle BigBlueButton-API-dokumentation. Detaljer om fejlkoder, filstørrelsesgrænser og det præcise svar-XML er ikke officielt specificeret. undocumented

Endepunkt

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

Dette endpoint kræver en POST-anmodning med en XML-body. Dokumentdataene sendes i request-bodyen, ikke som URL-parametre.

URL-parametre

Parameter Type Påkrævet Standard Beskrivelse
meetingID String Ja — Mødeidentifikatoren for det kørende møde, som skal modtage dokumentet.

XML-body — dokumentattributter

Request-bodyen skal indeholde en XML-struktur med et <module name="presentation">-element, der omslutter et eller flere <document>-elementer. Hvert dokument kan uploades enten via URL eller som inline-Base64-indhold.

Attribut Type Påkrævet Standard Beskrivelse
url String Nej — URL, der peger på præsentationsfilen. Bruges til URL-baserede uploads. Serveren henter filen fra denne URL.
filename String Nej — Filnavn til URL-baserede uploads. Hjælper med registrering af filtype, når URL'en ikke indeholder en filendelse.
name String Nej — Filnavn til Base64-inline-upload. Når denne attribut bruges, skal elementteksten indeholde det Base64-kodede filindhold.
current Boolean Nej false Når den er sat til true, aktiveres denne præsentation straks som den aktuelle præsentation efter upload.
downloadable Boolean Nej false Når den er sat til true, må deltagere downloade præsentationsfilen.
removable Boolean Nej true Når den er sat til true, må præsentatoren fjerne præsentationen fra mødet.

Eksempelanmodning — URL-baseret upload

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>'

Eksempelanmodning — Base64-inline-upload

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>'

Eksempelsvar

Et vellykket kald returnerer følgende XML: 

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

Et SUCCESS-svar bekræfter, at dokumentet blev accepteret til behandling. Det garanterer ikke, at filkonverteringen blev gennemført med succes. Om konverteringsfejl rapporteres tilbage via API-svaret, er ikke officielt dokumenteret. undocumented

Sammenligning med create-præsentationsupload

Du kan også uploade præsentationer under oprettelse af mødet ved hjælp af create-endpointet. Følgende tabel fremhæver forskellene mellem de to tilgange:

Aspekt create insertDocument
Tidspunkt Før mødet starter Mens mødet kører
Afbrydelse Ingen (første slide indlæses ved tilslutning) Ingen (baggrundsupload)
current attribut Understøttet Understøttet
Flere dokumenter Understøttet Understøttet

Tips

Hvis du vil have, at den nye præsentation skal blive aktiv med det samme, skal du sætte current="true" på dokumentelementet. Ellers skal præsentatøren manuelt skifte til den ved hjælp af præsentationsvælgeren i mødegrænsefladen.

  • De samme filformater, som understøttes af den almindelige præsentationsupload, understøttes også her (PDF, PPTX, DOCX, billeder osv.).
  • Du kan indsætte flere dokumenter i én enkelt anmodning ved at tilføje flere dokumentelementer inde i modulblokken.
  • Ved URL-baserede uploads skal du altid sætte attributten filename, når URL'en ikke indeholder en genkendelig filendelse. Dette hjælper BigBlueButton med at bestemme den korrekte filtype.
  • Til store filer anbefales URL-baseret upload frem for Base64-inline-upload for at holde request-payloaden lille.

Anvendelsesområder

  • Lever slides dynamisk fra et LMS eller et content management-system under en live-session.
  • Tilføj supplerende materiale til et møde, efter at det allerede er startet.
  • Byg automatiserede bots, der indsætter dagsordener, mødenoter eller rapporter i kørende møder.
  • Tillad eksterne systemer at sende opdateret indhold uden at kræve, at præsentatøren forlader mødet.
På bbbserver.de er dette endpoint tilgængeligt på alle planer. Du kan kalde det ved hjælp af dine API-legitimationsoplysninger, som findes i dashboardet til serveradministration. De samme filstørrelsesgrænser som ved almindelige præsentationsuploads gælder.

Ofte stillede spørgsmål

insertDocument-endpointet er tilgængeligt i BigBlueButton 2.5 og nyere. Det er ikke tilgængeligt i ældre versioner såsom 2.4 eller tidligere.

Ja, hvis attributten removable var sat til true (hvilket er standard). Præsentatoren kan fjerne præsentationen via mødegrænsefladen. Der findes ikke noget dedikeret API-endpoint til at fjerne en præsentation fra et kørende møde.

API'et vil returnere et FAILED-svar, der angiver, at mødet ikke blev fundet. Dokumenter kan kun indsættes i møder, der kører i øjeblikket.

De samme formater som ved almindelig præsentationsupload understøttes, herunder PDF, PPTX, DOCX, ODT og almindelige billedformater. Serveren konverterer filer, der ikke er PDF, til PDF internt ved hjælp af LibreOffice.

Filstørrelsesgrænser bestemmes af BigBlueButton-serverkonfigurationen. De præcise grænser specificeres ikke via API'et og afhænger af indstillinger på serversiden. Kontakt din serveradministrator for detaljer.

Du kan målrette et grupperum ved at bruge dets specifikke meetingID. Hvert grupperum har sit eget unikke møde-ID, som kan hentes via getMeetings- eller getMeetingInfo-endpointet.

Nej. Et SUCCESS-svar bekræfter kun, at serveren accepterede dokumentet til behandling. Om konverteringen lykkedes, rapporteres ikke pålideligt i API-svaret. Denne adfærd er ikke officielt dokumenteret.