Przeglądasz dokumentację API dla BigBlueButton 3.x. Aktualna wersja to BigBlueButton 4.x. Planujesz aktualizację? Przewodnik migracji zawiera wszystkie zmiany wymagane w wywołaniach API.
insertDocument – Wstaw prezentację
Punkt końcowy insertDocument umożliwia przesłanie jednej lub wielu prezentacji do już trwającego spotkania BigBlueButton bez przerywania pracy bieżącego prezentera. Dokumenty są przetwarzane w tle i stają się dostępne jako dodatkowe prezentacje, między którymi prezenter może przełączać się w dowolnym momencie.
Ten punkt końcowy jest tylko pobieżnie opisany w oficjalnej dokumentacji API BigBlueButton. Szczegóły dotyczące kodów błędów, limitów rozmiaru plików i dokładnej odpowiedzi XML nie są oficjalnie określone. undocumented
Punkt końcowy
POST https://api-guide.bbbserver.com/bigbluebutton/api/insertDocument?meetingID=replace-with-meeting-id&checksum=replace-with-checksum
Content-Type: application/xml Ten punkt końcowy wymaga żądania POST z treścią XML. Dane dokumentu są wysyłane w treści żądania, a nie jako parametry URL.
Parametry URL
| Parametr | Typ | Wymagane | Domyślnie | Opis |
|---|---|---|---|---|
meetingID | String | Tak | — | Identyfikator uruchomionego spotkania, które ma otrzymać dokument. |
Treść XML — atrybuty dokumentu
Treść żądania musi zawierać strukturę XML z elementem <module name="presentation"> obejmującym co najmniej jeden element <document>. Każdy dokument można przesłać albo przez URL, albo jako osadzoną treść Base64.
| Atrybut | Typ | Wymagane | Domyślnie | Opis |
|---|---|---|---|---|
url | String | Nie | — | Adres URL wskazujący plik prezentacji. Używany do przesyłania opartego na URL. Serwer pobiera plik z tego adresu URL. |
filename | String | Nie | — | Nazwa pliku wraz z rozszerzeniem, używana przy przesyłaniu plików na podstawie adresu URL. Wymagana, gdy ścieżka adresu URL nie kończy się nazwą pliku z rozszerzeniem; w przeciwnym razie żądanie kończy się niepowodzeniem. |
name | String | Nie | — | Nazwa pliku dla osadzonych przesłań Base64. Przy użyciu tego atrybutu tekst elementu musi zawierać zawartość pliku zakodowaną w Base64. |
current | Boolean | Nie | false | Po ustawieniu na true ta prezentacja jest natychmiast aktywowana jako bieżąca prezentacja po przesłaniu. |
downloadable | Boolean | Nie | false | Po ustawieniu na true uczestnicy mogą pobierać plik prezentacji. |
removable | Boolean | Nie | true | Po ustawieniu na true prezenter może usunąć prezentację ze spotkania. |
Przykładowe żądanie — przesyłanie oparte na 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>' Przykładowe żądanie — osadzone przesłanie 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>' Przykładowa odpowiedź
Pomyślne wywołanie zwraca następujący XML:
<response>
<returncode>SUCCESS</returncode>
<message>Presentation is being uploaded</message>
</response> Odpowiedź SUCCESS potwierdza jedynie, że serwer przyjął żądanie. Pobieranie i konwersja odbywają się w tle; błędy są zgłaszane klientom spotkania i zapisywane w dzienniku serwera, a nie w odpowiedzi API.
Porównanie z przesyłaniem prezentacji create
Możesz również przesyłać prezentacje podczas tworzenia spotkania, używając endpointu create. Poniższa tabela przedstawia różnice między tymi dwoma podejściami:
| Aspekt | create | insertDocument |
|---|---|---|
| Czas | Przed rozpoczęciem spotkania | Podczas trwania spotkania |
| Przerwanie | Brak (pierwszy slajd jest ładowany przy dołączeniu) | Brak (przesyłanie w tle) |
current atrybut | Obsługiwane | Obsługiwane |
| Wiele dokumentów | Obsługiwane | Obsługiwane |
Wskazówki
Jeśli chcesz, aby nowa prezentacja stała się aktywna natychmiast, ustaw current="true" na elemencie document. W przeciwnym razie prezenter musi ręcznie przełączyć się na nią za pomocą selektora prezentacji w interfejsie spotkania.
- Obsługiwane są tutaj te same formaty plików co przy zwykłym przesyłaniu prezentacji (PDF, PPTX, DOCX, obrazy itd.).
- Możesz wstawić wiele dokumentów w jednym żądaniu, dodając więcej elementów document wewnątrz bloku module.
- W przypadku przesyłania opartego na URL zawsze ustawiaj atrybut
filename, gdy adres URL nie zawiera rozpoznawalnego rozszerzenia pliku. Pomaga to BigBlueButton określić prawidłowy typ pliku. - W przypadku dużych plików zaleca się przesyłanie przez URL zamiast osadzonego przesyłania Base64, aby utrzymać niewielki rozmiar ładunku żądania.
Zastosowania
- Dynamicznie dostarczaj slajdy z LMS lub systemu zarządzania treścią podczas sesji na żywo.
- Dodawaj materiały uzupełniające do spotkania po jego rozpoczęciu.
- Twórz zautomatyzowane boty, które wstawiają agendy, notatki ze spotkań lub raporty do trwających spotkań.
- Pozwól systemom zewnętrznym przesyłać zaktualizowane treści bez konieczności opuszczania spotkania przez prezentera.
Najczęściej zadawane pytania
insertDocument jest dostępny w wersji BigBlueButton 2.5 i nowszych. Nie jest dostępny w starszych wersjach, takich jak 2.4 i wcześniejsze.removable został ustawiony na true (co jest wartością domyślną). Prezenter może usunąć prezentację przez interfejs spotkania. Nie ma dedykowanego punktu końcowego API do usuwania prezentacji z trwającego spotkania.FAILED, jeśli na serwerze nie istnieje spotkanie o podanym identyfikatorze. Sprawdzane jest istnienie spotkania, a nie to, czy jest ono w toku: spotkanie, które zostało utworzone, ale do którego nikt jeszcze nie dołączył, również przyjmuje dokumenty.meetingID. Każdy pokój breakout ma własny unikalny identyfikator spotkania, który można uzyskać za pomocą punktu końcowego getMeetings lub getMeetingInfo.SUCCESS potwierdza jedynie, że serwer przyjął żądanie. Pobieranie i konwersja odbywają się w tle; błędy są zgłaszane klientom spotkania i zapisywane w dzienniku serwera, a nie w odpowiedzi API.