Rozdział 20 POST

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 dla przesyłania opartego na URL. Pomaga w wykrywaniu typu pliku, gdy adres URL nie zawiera rozszerzenia pliku.
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>
</response>

Odpowiedź SUCCESS potwierdza, że dokument został przyjęty do przetwarzania. Nie gwarantuje to, że konwersja pliku zakończyła się pomyślnie. To, czy błędy konwersji są zwracane przez odpowiedź API, nie jest oficjalnie udokumentowane. undocumented

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.
W bbbserver.de ten endpoint jest dostępny we wszystkich planach. Możesz go wywołać przy użyciu swoich danych uwierzytelniających API dostępnych w panelu zarządzania serwerem. Obowiązują te same limity rozmiaru plików co przy standardowym przesyłaniu prezentacji.

Najczęściej zadawane pytania

Punkt końcowy 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.

Tak, jeśli atrybut 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.

API zwróci odpowiedź FAILED wskazującą, że spotkanie nie zostało znalezione. Dokumenty można wstawiać tylko do spotkań, które aktualnie trwają.

Obsługiwane są te same formaty co przy zwykłym przesyłaniu prezentacji, w tym PDF, PPTX, DOCX, ODT oraz popularne formaty obrazów. Serwer konwertuje pliki inne niż PDF wewnętrznie do PDF przy użyciu LibreOffice.

Limity rozmiaru plików są określane przez konfigurację serwera BigBlueButton. Dokładne limity nie są określone przez API i zależą od ustawień po stronie serwera. Aby uzyskać szczegóły, skontaktuj się z administratorem serwera.

Możesz wskazać pokój breakout, używając jego konkretnego 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.

Nie. Odpowiedź SUCCESS potwierdza jedynie, że serwer przyjął dokument do przetwarzania. To, czy konwersja się powiodła, nie jest wiarygodnie raportowane w odpowiedzi API. To zachowanie nie jest oficjalnie udokumentowane.