Версия API: 4.x последняя 3.x

Вы просматриваете документацию API для BigBlueButton 3.x. Текущая версия — BigBlueButton 4.x. Планируете обновление? В руководстве по миграции перечислены все изменения, которые необходимо внести в ваши вызовы API.

Глава 20 POST

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>
  <message>Presentation is being uploaded</message>
</response>

Ответ SUCCESS подтверждает лишь то, что сервер принял запрос. Скачивание и преобразование выполняются в фоновом режиме; ошибки передаются клиентам конференции и записываются в журнал сервера, а не возвращаются в ответе API.

Сравнение с загрузкой презентации create

Вы также можете загружать презентации во время создания встречи, используя endpoint create. Следующая таблица подчёркивает различия между двумя подходами:

Аспект create insertDocument
Время До начала встречи Во время выполнения встречи
Прерывание Нет (первый слайд загружается при присоединении) Нет (фоновая загрузка)
current атрибут Поддерживается Поддерживается
Несколько документов Поддерживается Поддерживается

Советы

Если вы хотите, чтобы новая презентация стала активной немедленно, установите current="true" в элементе document. В противном случае ведущему придется вручную переключиться на нее с помощью селектора презентаций в интерфейсе встречи.

  • Здесь также поддерживаются те же форматы файлов, что и при обычной загрузке презентаций (PDF, PPTX, DOCX, изображения и т. д.).
  • Вы можете вставить несколько документов в одном запросе, добавив больше элементов document внутри блока module.
  • Для загрузок по URL всегда задавайте атрибут filename, если URL не содержит распознаваемого расширения файла. Это помогает BigBlueButton определить правильный тип файла.
  • Для больших файлов рекомендуется загрузка по URL вместо встроенной загрузки Base64, чтобы сохранить небольшой размер полезной нагрузки запроса.

Сценарии использования

  • Динамически предоставляйте слайды из LMS или системы управления контентом во время живой сессии.
  • Добавляйте дополнительные материалы во встречу уже после ее начала.
  • Создавайте автоматизированных ботов, которые вставляют повестки, заметки встречи или отчеты в уже идущие встречи.
  • Позвольте внешним системам отправлять обновленный контент без необходимости для ведущего покидать встречу.
На bbbserver.de этот endpoint доступен на всех тарифах. Вы можете вызывать его, используя свои учетные данные API, найденные в панели управления сервером. Применяются те же ограничения на размер файлов, что и при обычной загрузке презентаций.

Часто задаваемые вопросы

Эндпоинт insertDocument доступен в BigBlueButton 2.5 и более поздних версиях. Он недоступен в более старых версиях, таких как 2.4 и более ранние.

Да, если атрибут removable был установлен в true (что является значением по умолчанию). Докладчик может удалить презентацию через интерфейс встречи. Отдельного API-эндпоинта для удаления презентации из запущенной встречи не существует.

API возвращает ответ FAILED, если на сервере нет конференции с указанным идентификатором. Проверяется существование конференции, а не то, идёт ли она: конференция, которая уже создана, но к которой ещё никто не присоединился, также принимает документы.

Поддерживаются те же форматы, что и при обычной загрузке презентаций, включая PDF, PPTX, DOCX, ODT и распространённые форматы изображений. Офисные документы преобразуются в PDF с помощью LibreOffice; файлы PDF и изображения обрабатываются напрямую.

Ограничения размера файлов определяются конфигурацией сервера BigBlueButton. Точные лимиты не указываются через API и зависят от настроек на стороне сервера. За подробностями обратитесь к администратору сервера.

Вы можете выбрать сессионную комнату, используя её конкретный meetingID. У каждой сессионной комнаты есть собственный уникальный идентификатор встречи, который можно получить через эндпоинт getMeetings или getMeetingInfo.

Ответ SUCCESS подтверждает лишь то, что сервер принял запрос. Скачивание и преобразование выполняются в фоновом режиме; ошибки передаются клиентам конференции и записываются в журнал сервера, а не возвращаются в ответе API.
Руководство по API BigBlueButton