insertDocument – Вставити презентацію
Ендпойнт insertDocument дає змогу завантажити одну або кілька презентацій у вже запущену зустріч BigBlueButton без переривання поточного доповідача. Документи обробляються у фоновому режимі та стають доступними як додаткові презентації, на які доповідач може перемкнутися будь-коли.
Цей ендпойнт лише побіжно задокументований в офіційній документації API BigBlueButton. Деталі щодо кодів помилок, обмежень розміру файлів і точної XML відповіді офіційно не визначені. undocumented
Ендпоінт
POST https://api-guide.bbbserver.com/bigbluebutton/api/insertDocument?meetingID=replace-with-meeting-id&checksum=replace-with-checksum
Content-Type: application/xmlЦей ендпойнт вимагає запит POST із тілом XML. Дані документа надсилаються в тілі запиту, а не як параметри URL.
Параметри URL
| Параметр | Тип | Обов’язково | За замовчуванням | Опис |
|---|---|---|---|---|
meetingID | String | Так | — | Ідентифікатор активної зустрічі, яка має отримати документ. |
Тіло XML — атрибути документа
Тіло запиту має містити структуру XML з елементом <module name="presentation">, що обгортає один або кілька елементів <document>. Кожен документ можна завантажити або за URL, або як вбудований вміст Base64.
| Атрибут | Тип | Обов’язково | За замовчуванням | Опис |
|---|---|---|---|---|
url | String | Ні | — | URL, що вказує на файл презентації. Використовується для завантаження за URL. Сервер отримує файл за цією URL-адресою. |
filename | String | Ні | — | Ім’я файлу для завантажень за URL. Допомагає визначити тип файлу, коли URL не містить розширення файлу. |
name | String | Ні | — | Ім’я файлу для вбудованих завантажень Base64. При використанні цього атрибута текст елемента має містити вміст файлу, закодований у Base64. |
current | Boolean | Ні | false | Якщо встановлено значення true, цю презентацію буде негайно активовано як поточну після завантаження. |
downloadable | Boolean | Ні | false | Якщо встановлено значення true, учасникам дозволяється завантажувати файл презентації. |
removable | Boolean | Ні | true | Якщо встановлено значення true, доповідачу дозволяється видаляти презентацію із зустрічі. |
Приклад запиту — завантаження за 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>'Приклад запиту — вбудоване завантаження 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>'Приклад відповіді
Успішний виклик повертає такий XML:
<response>
<returncode>SUCCESS</returncode>
</response>Відповідь SUCCESS підтверджує, що документ було прийнято до обробки. Вона не гарантує, що перетворення файлу успішно завершилося. Чи повідомляються помилки перетворення назад через відповідь API, офіційно не задокументовано. undocumented
Порівняння із завантаженням презентації create
Ви також можете завантажувати презентації під час створення зустрічі за допомогою кінцевої точки create. Наступна таблиця підкреслює відмінності між двома підходами:
| Аспект | create | insertDocument |
|---|---|---|
| Час | До початку зустрічі | Поки зустріч триває |
| Переривання | Немає (перший слайд завантажується під час приєднання) | Немає (фонове завантаження) |
current атрибут | Підтримується | Підтримується |
| Кілька документів | Підтримується | Підтримується |
Поради
Якщо ви хочете, щоб нова презентація стала активною негайно, встановіть current="true" в елементі document. Інакше доповідач повинен буде вручну перемкнутися на неї за допомогою селектора презентації в інтерфейсі зустрічі.
- Тут також підтримуються ті самі формати файлів, що й для звичайного завантаження презентацій (PDF, PPTX, DOCX, зображення тощо).
- Ви можете вставити кілька документів в одному запиті, додавши більше елементів document усередині блоку module.
- Для завантажень за URL завжди встановлюйте атрибут
filename, якщо URL не містить розпізнаваного розширення файлу. Це допомагає BigBlueButton визначити правильний тип файлу. - Для великих файлів рекомендується завантаження за URL замість вбудованого завантаження Base64, щоб зменшити розмір payload запиту.
Випадки використання
- Динамічно надавайте слайди з LMS або системи керування контентом під час живої сесії.
- Додавайте допоміжні матеріали до зустрічі після того, як вона вже почалася.
- Створюйте автоматизованих ботів, які вставляють порядки денні, нотатки зустрічі або звіти в поточні зустрічі.
- Дозвольте зовнішнім системам надсилати оновлений вміст без потреби для доповідача залишати зустріч.
Поширені запитання
insertDocument доступний у BigBlueButton 2.5 і новіших версіях. У старіших версіях, таких як 2.4 або раніше, він недоступний.removable було встановлено в true (це значення за замовчуванням). Доповідач може видалити презентацію через інтерфейс зустрічі. Окремого API-ендпойнта для видалення презентації із запущеної зустрічі немає.FAILED, яка вказує, що зустріч не знайдено. Документи можна вставляти лише в зустрічі, які зараз виконуються.meetingID. Кожна breakout room має власний унікальний ідентифікатор зустрічі, який можна отримати через ендпойнт getMeetings або getMeetingInfo.SUCCESS лише підтверджує, що сервер прийняв документ до обробки. Чи було перетворення успішним, у відповіді API надійно не повідомляється. Ця поведінка офіційно не задокументована.