Rozdział 11 GET POST

getRecordings – Pobierz nagrania

Punkt końcowy getRecordings zwraca listę nagrań z serwera BigBlueButton, filtrowaną według identyfikatora spotkania, identyfikatora nagrania lub stanu. Obsługuje paginację od wersji BBB 2.7, co ułatwia pobieranie dużych zestawów nagrań w wygodnych partiach.

Punkt końcowy

GET/POST https://api-guide.bbbserver.com/bigbluebutton/api/getRecordings?<parameters>&checksum=replace-with-checksum

Parametry

Parametr Typ Wymagane Domyślnie Opis
meetingID String — — Lista identyfikatorów spotkań rozdzielonych przecinkami. Ignorowana, gdy podano recordID. Jeśli pominięta, zwracane są wszystkie nagrania.
recordID String — — Lista identyfikatorów nagrań oddzielonych przecinkami. Ma pierwszeństwo przed meetingID. Obsługuje dopasowanie prefiksowe — na przykład 652c9eb4 pasuje do wszystkich nagrań, których identyfikator zaczyna się od tego prefiksu.
state String — published,unpublished Filtr stanu oddzielony przecinkami. Prawidłowe wartości: processing, processed, published, unpublished, deleted. Użyj any, aby zwrócić wszystkie stany.
meta String — — Filtr metadanych w tym samym formacie co w wywołaniu create (np. meta_presenter=John).
offset Integer — 0 Indeks początkowy dla paginacji. Działa tylko wtedy, gdy podano również limit. BBB 2.7+
limit Integer — — Maksymalna liczba nagrań w jednej odpowiedzi (od 1 do 100). Wartości spoza tego zakresu są automatycznie ograniczane. BBB 2.7+

Żaden z parametrów nie jest wymagany. Wywołanie getRecordings bez żadnego filtra zwraca wszystkie nagrania published i unpublished na serwerze.

Stany nagrań

Stan Opis
processing Nagranie jest obecnie przetwarzane.
processed Przetwarzanie zostało zakończone, ale nagranie nie zostało jeszcze opublikowane.
published Nagranie jest opublikowane i dostępne dla użytkowników.
unpublished Nagranie istnieje, ale nie jest dostępne dla użytkowników.
deleted Nagranie zostało oznaczone do usunięcia.

Domyślny filtr stanu obejmuje tylko nagrania published i unpublished. Aby zobaczyć nagrania, które są nadal przetwarzane lub zostały usunięte, musisz jawnie ustawić parametr state.

Pola odpowiedzi

Pole Typ Opis
recordID String Unikalny identyfikator nagrania.
meetingID String Zewnętrzny identyfikator spotkania powiązany z tym nagraniem.
internalMeetingID String Wewnętrzny identyfikator spotkania używany przez BigBlueButton.
name String Nazwa spotkania w momencie jego nagrania.
isBreakout Boolean Czy to nagranie pochodzi z pokoju grupowego.
published Boolean Czy nagranie jest obecnie opublikowane.
state String Bieżący stan nagrania (processing, processed, published, unpublished, deleted).
startTime Long Znacznik czasu Unix w milisekundach określający moment rozpoczęcia spotkania.
endTime Long Znacznik czasu Unix w milisekundach określający moment zakończenia spotkania.
participants Integer Liczba uczestników spotkania.
rawSize Long Rozmiar surowych danych nagrania w bajtach.
size Long Rozmiar przetworzonego nagrania w bajtach.
metadata Object Niestandardowe pary klucz-wartość metadanych powiązane z nagraniem.
playback Object Szczegóły formatu odtwarzania, w tym URL, czas przetwarzania, długość, rozmiar i miniatury podglądu.
totalElements Integer Łączna liczba pasujących nagrań. Obecne tylko wtedy, gdy używane są parametry stronicowania. BBB 2.7+

Przykładowe żądanie

Wszystkie opublikowane nagrania

getRecordings?checksum=replace-with-checksum

Nagrania dla konkretnego spotkania

getRecordings?meetingID=replace-with-meeting-id&checksum=replace-with-checksum

Wiele spotkań

getRecordings?meetingID=replace-with-meeting-id-1,replace-with-meeting-id-2&checksum=replace-with-checksum

Według ID nagrania

getRecordings?recordID=replace-with-recording-id&checksum=replace-with-checksum

Wszystkie stany

getRecordings?state=any&checksum=replace-with-checksum

Żądanie stronicowane (nagrania od 21 do 30)

getRecordings?state=published&offset=20&limit=10&checksum=replace-with-checksum

Przykładowa odpowiedź

<response>
  <returncode>SUCCESS</returncode>
  <recordings>
    <recording>
    <recordID>replace-with-recording-id</recordID>
    <meetingID>replace-with-meeting-id</meetingID>
    <internalMeetingID>replace-with-internal-meeting-id</internalMeetingID>
      <name>Project Meeting</name>
      <isBreakout>false</isBreakout>
      <published>true</published>
      <state>published</state>
      <startTime>1462283509434</startTime>
      <endTime>1462284509434</endTime>
      <participants>5</participants>
      <metadata>
        <bbb-origin>greenlight</bbb-origin>
      </metadata>
      <rawSize>123456789</rawSize>
      <size>98765432</size>
      <playback>
        <format>
          <type>presentation</type>
                    <url>https://api-guide.bbbserver.com/playback/presentation/2.3/replace-with-recording-id</url>
          <processingTime>62890</processingTime>
          <length>45</length>
          <size>98765432</size>
          <preview>
            <images>
              <image width="176" height="136" alt="Welcome">
                                https://api-guide.bbbserver.com/presentation/replace-with-recording-id/thumbnail_0.png
              </image>
            </images>
          </preview>
        </format>
      </playback>
    </recording>
  </recordings>
</response>

Stronicowanie BBB 2.7+

Jeśli uwzględnisz parametry offset i/lub limit, odpowiedź będzie zawierać dodatkowe pole totalElements wskazujące łączną liczbę pasujących nagrań. Pozwala to obliczyć całkowitą liczbę stron i zbudować mechanizmy stronicowania w aplikacji. 

<response>
  <returncode>SUCCESS</returncode>
  <totalElements>42</totalElements>
  <recordings>
    <!-- recording elements -->
  </recordings>
</response>
bbbserver.de — Na bbbserver.de punkt końcowy getRecordings jest w pełni dostępny przez API. Paginacja jest obsługiwana we wszystkich aktualnych planach serwerowych działających na BBB 2.7 lub nowszym.

Wskazówki

  • Użyj recordID z prefiksem, aby wyszukiwać nagrania, gdy masz tylko częściowy identyfikator — BigBlueButton dopasowuje wszystkie nagrania, których ID zaczyna się od podanego ciągu.
  • Zawsze jawnie określ parametr state, jeśli chcesz zobaczyć nagrania, które są jeszcze przetwarzane lub zostały usunięte, ponieważ domyślnie są one wykluczone.
  • Połącz meetingID z state, aby skutecznie zawęzić wyniki — na przykład, aby znaleźć tylko opublikowane nagrania dla konkretnego spotkania.
  • W przypadku dużych wdrożeń z wieloma nagraniami używaj stronicowania, aby uniknąć limitów czasu i zmniejszyć rozmiar odpowiedzi.
  • Używaj filtrów metadanych (parametry meta_), aby znajdować nagrania na podstawie niestandardowych atrybutów ustawionych podczas tworzenia spotkania.

Najczęściej zadawane pytania

Endpoint zwraca wszystkie nagrania w stanie published lub unpublished. Nagrania, które są jeszcze przetwarzane lub zostały oznaczone do usunięcia, nie są uwzględniane, chyba że jawnie ustawisz parametr state.

Gdy podasz częściowy identyfikator nagrania, BigBlueButton dopasowuje wszystkie nagrania, których pełne ID zaczyna się od podanego ciągu. Na przykład przekazanie 652c9eb4 zwróci każde nagranie, którego ID zaczyna się od tego prefiksu. W oficjalnej dokumentacji bywa to określane jako dopasowanie wieloznaczne, ale w praktyce jest to ściśle dopasowanie prefiksowe (startsWith), a nie dopasowanie podciągu.

Tak. Użyj parametru meta z tymi samymi nazwami kluczy, które zostały ustawione podczas tworzenia spotkania. Na przykład, jeśli podczas tworzenia spotkania przekazano meta_presenter=John, możesz filtrować po tej samej parze klucz-wartość w getRecordings. Należy pamiętać, że dokładne zachowanie dopasowywania dla filtrów metadanych nie jest w pełni określone w oficjalnej dokumentacji.

meetingID to zewnętrzny identyfikator przypisany podczas tworzenia spotkania. Jedno spotkanie może wygenerować wiele nagrań. recordID to unikalny identyfikator każdego pojedynczego nagrania. Gdy podane są oba, recordID ma pierwszeństwo, a meetingID jest ignorowany.

Paginacja wymaga BBB 2.7 lub nowszego. Ustaw parametr limit, aby określić, ile nagrań ma zostać zwróconych na żądanie (od 1 do 100), i użyj offset, aby pominąć określoną liczbę wyników. Odpowiedź będzie zawierać pole totalElements, dzięki czemu można obliczyć całkowitą liczbę stron. Parametr offset nie ma żadnego efektu, jeśli nie podano także limit.

BigBlueButton automatycznie ogranicza wartość do dozwolonego zakresu. Jeśli podasz wartość większą niż 100, zostanie potraktowana jako 100. Jeśli podasz wartość mniejszą niż 1, zostanie potraktowana jako 1. Żaden błąd nie zostanie zwrócony.

Tak. Nagrania pokoi breakout są uwzględniane i można je rozpoznać po polu isBreakout ustawionym na true. Mogą też zawierać dodatkowe pola, takie jak identyfikator spotkania nadrzędnego i numer sekwencji breakout.