Chapitre 20 POST

insertDocument – Insérer une présentation

Le point de terminaison insertDocument vous permet de téléverser une ou plusieurs présentations dans une réunion BigBlueButton déjà en cours sans interrompre le présentateur actuel. Les documents sont traités en arrière-plan et deviennent disponibles comme présentations supplémentaires vers lesquelles le présentateur peut basculer à tout moment.

Ce point de terminaison n’est que légèrement documenté dans la documentation officielle de l’API BigBlueButton. Les détails sur les codes d’erreur, les limites de taille de fichier et le XML exact de la réponse ne sont pas officiellement spécifiés. undocumented

Point de terminaison

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

Ce point de terminaison nécessite une requête POST avec un corps XML. Les données du document sont envoyées dans le corps de la requête, et non comme paramètres d’URL.

Paramètres d’URL

Paramètre Type Obligatoire Par défaut Description
meetingID String Oui — L’identifiant de la réunion en cours qui doit recevoir le document.

Corps XML — Attributs du document

Le corps de la requête doit contenir une structure XML avec un élément <module name="presentation"> englobant un ou plusieurs éléments <document>. Chaque document peut être téléversé soit par URL, soit comme contenu Base64 intégré.

Attribut Type Obligatoire Par défaut Description
url String Non — URL pointant vers le fichier de présentation. Utilisée pour les téléversements basés sur une URL. Le serveur récupère le fichier depuis cette URL.
filename String Non — Nom de fichier pour les téléversements basés sur une URL. Aide à détecter le type de fichier lorsque l’URL ne contient pas d’extension de fichier.
name String Non — Nom de fichier pour les téléversements intégrés Base64. Lors de l’utilisation de cet attribut, le texte de l’élément doit contenir le contenu du fichier encodé en Base64.
current Boolean Non false Lorsqu’elle est définie sur true, cette présentation est immédiatement activée comme présentation actuelle après le téléversement.
downloadable Boolean Non false Lorsqu’elle est définie sur true, les participants sont autorisés à télécharger le fichier de présentation.
removable Boolean Non true Lorsqu’elle est définie sur true, le présentateur est autorisé à supprimer la présentation de la réunion.

Exemple de requête — Téléversement basé sur une 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>'

Exemple de requête — Téléversement intégré 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>'

Exemple de réponse

Un appel réussi renvoie le XML suivant : 

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

Une réponse SUCCESS confirme que le document a été accepté pour traitement. Elle ne garantit pas que la conversion du fichier s’est terminée avec succès. Le fait que les erreurs de conversion soient signalées via la réponse API n’est pas officiellement documenté. undocumented

Comparaison avec le téléversement de présentation create

Vous pouvez également téléverser des présentations lors de la création de la réunion à l’aide du point de terminaison create. Le tableau suivant met en évidence les différences entre les deux approches :

Aspect create insertDocument
Moment Avant le début de la réunion Pendant que la réunion est en cours
Interruption Aucune (la première diapositive est chargée à la connexion) Aucune (téléversement en arrière-plan)
current attribut Pris en charge Pris en charge
Documents multiples Pris en charge Pris en charge

Conseils

Si vous voulez que la nouvelle présentation devienne active immédiatement, définissez current="true" sur l’élément document. Sinon, le présentateur devra y basculer manuellement à l’aide du sélecteur de présentation dans l’interface de réunion.

  • Les mêmes formats de fichier pris en charge par le téléversement de présentation classique sont également pris en charge ici (PDF, PPTX, DOCX, images, etc.).
  • Vous pouvez insérer plusieurs documents dans une seule requête en ajoutant davantage d’éléments document à l’intérieur du bloc module.
  • Pour les téléversements basés sur une URL, définissez toujours l’attribut filename lorsque l’URL ne contient pas une extension de fichier reconnaissable. Cela aide BigBlueButton à déterminer le type de fichier correct.
  • Pour les fichiers volumineux, le téléversement par URL est recommandé plutôt que le téléversement intégré Base64 afin de garder une petite charge utile de requête.

Cas d’usage

  • Fournissez dynamiquement des diapositives depuis un LMS ou un système de gestion de contenu pendant une session en direct.
  • Ajoutez du matériel complémentaire à une réunion après qu’elle a déjà commencé.
  • Créez des bots automatisés qui insèrent des ordres du jour, des notes de réunion ou des rapports dans des réunions en cours.
  • Permettez à des systèmes externes de pousser du contenu mis à jour sans obliger le présentateur à quitter la réunion.
Sur bbbserver.de, ce point de terminaison est disponible sur toutes les offres. Vous pouvez l’appeler à l’aide de vos identifiants API disponibles dans le tableau de bord de gestion du serveur. Les mêmes limites de taille de fichier que pour les téléversements de présentation classiques s’appliquent.

Foire aux questions

Le point de terminaison insertDocument est disponible dans BigBlueButton 2.5 et les versions ultérieures. Il n’est pas disponible dans les anciennes versions telles que 2.4 ou antérieures.

Oui, si l’attribut removable a été défini sur true (ce qui est la valeur par défaut). Le présentateur peut supprimer la présentation via l’interface de réunion. Il n’existe pas de point de terminaison API dédié pour supprimer une présentation d’une réunion en cours.

L’API renverra une réponse FAILED indiquant que la réunion est introuvable. Les documents ne peuvent être insérés que dans des réunions actuellement en cours.

Les mêmes formats que pour le téléversement de présentation classique sont pris en charge, notamment PDF, PPTX, DOCX, ODT et les formats d’image courants. Le serveur convertit en interne les fichiers non-PDF en PDF à l’aide de LibreOffice.

Les limites de taille de fichier sont déterminées par la configuration du serveur BigBlueButton. Les limites exactes ne sont pas spécifiées via l’API et dépendent des paramètres côté serveur. Contactez l’administrateur de votre serveur pour plus de détails.

Vous pouvez cibler une salle de sous-commission en utilisant son meetingID spécifique. Chaque salle de sous-commission possède son propre identifiant de réunion unique, qui peut être obtenu via le point de terminaison getMeetings ou getMeetingInfo.

Non. Une réponse SUCCESS confirme seulement que le serveur a accepté le document pour traitement. Le succès de la conversion n’est pas signalé de manière fiable dans la réponse API. Ce comportement n’est pas officiellement documenté.