Przejdź do głównej zawartości

API serwera Calibre — zanotowano

Dokumentacja techniczna i projekt. W dokumencie tym zachowane są studia i przewidziana architektura. Nie wszystkie opisane funkcje mogą być dostępne; the instrukcja obsługi i kod określają bieżącą operację.

Oświadczenie złożone 30 października 2026 roku na podstawie kodu źródłowego Calibre (src/calibre/srv/), brak dokumentacji: żadna nie istnieje. Wdrożono i objęto testami w Packages/Core/Sources/CalibreKit.


1. Ostrzeżenie, które pochodzi od samego konserwatora​

Zapytany o dokumentację dla API /ajax, Kovid Goyal odpowiada, że nie istnieje, że tej powierzchni nie ma ani publiczny, ani stabilny i że trzeba przeczytać źródło. Konsekwencje zachowane w CalibreKit :

  • całe dekodowanie jest tolerowane — zaginiony, nieoczekiwany lub null nigdy nie powoduje niepowodzenia wyświetlania listy bibliotek;
  • Po połączeniu wykrywany jest charakter serwera (detectFlavor()), ponieważ Calibre-Web odpowiada na wszystko na 404 /ajax/* i oferuje tylko OPDS;
  • OPDS pozostaje trasą awaryjną, znormalizowany i stabilny;
  • Testy zamrażają rzeczywiste kształty bajtów, więc aktualizacja Calibre powoduje przerwanie testu, a nie aplikacji.

2. Trzy konwencje nazewnictwa biblioteki​

To jest główna pułapka tego API. Jest kodowany raz CalibreClient.url(path:query:libraryInQuery:) i zweryfikowany czterema testami.

Rodzina trasDokąd zmierza library_id
/ajax/…, /get/…komponent ścieżki — /ajax/search/Calibre_Library
/conversion/…, /cdb/…, /fts/…parametr zapytania — ?library_id=Calibre_Library
/book-…-last-read-position/…komponent ścieżki, ponownie

Zameldowałem się srv/utils.py : get_library_data() łóżko rd.query.get('library_id').


3. Katalog — srv/ajax.py​

DrogaZwroty
GET /ajax/library-info{library_map, default_library} — służy również jako test natury serwera
GET /ajax/search/{library}{total_num, offset, num, book_ids, …}, parametry query, num, offset, sort, sort_order, vl
GET /ajax/books/{library}?ids=1,2,3słownik indeksowane według identyfikatora, null dla zakazanej książki
GET /ajax/book/{id}/{library}metadane książki
GET /ajax/categories/{library}kategorie pierwszego poziomu
GET /ajax/category/{nom}/{library}zawartość kategorii, spaginowana
GET /ajax/books_in/{cat}/{item}/{library}identyfikatory kategorii

Dwie pułapki w dekodowaniu, obie objęte testami:

Identyfikatora nie ma w temacie. /ajax/books indeksuje swój słownik według identyfikatora i nie powtarza go w środku. CalibreKit wstrzykuje go przez userInfo dekodera.

0101-01-01T00:00:00+00:00 oznacza „brak daty”. To wartownik UNDEFINED_DATE z Calibre. Naiwnie odszyfrowane, tworzy książkę opublikowaną w starożytności. CalibreDate przywraca to nil.


4. Konwersja — srv/convert.py​

To odkrycie zmienia architekturę: serwer Calibre dokonuje konwersji poprzez HTTP.

DrogaMetodaRola
/conversion/book-data/{id}POBIERZformaty wejściowe, formaty wyjściowe, akceptowane opcje
/conversion/start/{id}POSTciało {input_fmt, output_fmt, options} → zwraca identyfikator zadania
/conversion/status/{job}POST{running, percent, msg} następnie stan końcowy; ?abort_job=1 przerywa

Szczegóły podane w źródle i wszystkie istotne w użyciu:

  • Tylko POST (receive_data_methods = {'POST'}). GET zostaje odrzucony.
  • input_fmt musi być format, jaki faktycznie ma ta książka : Serwer buduje stamtąd ścieżkę źródłową i odrzuca resztę. Czeka na to wielkimi literami, output_fmt małymi literami.
  • Status jest zużywany przy pierwszym odczycie terminala : del conversion_jobs[job_id], zatem cleanup() w finally. Konkluzję możesz przeczytać tylko raz. I tylko użytkownik, który uruchomił zadanie w tej samej bibliotece, może wysyłać do niego zapytania. CalibreKit.convert(…) otacza pętlę sondującą, więc żaden rozmówca nie musi o tym myśleć.
  • Format produktu został dodany do książki w bibliotece : db.add_format(book_id, fmt, output_path). Praca jest zatem wykonywana tylko raz, a następnie wszystkie urządzenia z niej korzystają. /get/EPUB/{id}.
  • Pliki receptur są odrzucane (wykonanie kodu), a lista opcji jest blokowana przez sieć.

Pełna trasa, np CalibreKit implementuje to:

GET /conversion/book-data/42?library_id=L → entrées : AZW3, PDF ; sorties : epub, mobi, …
POST /conversion/start/42?library_id=L → 17
{"input_fmt":"AZW3","output_fmt":"epub","options":{}}
POST /conversion/status/17?library_id=L → {"running":true,"percent":10,"msg":"Lecture"}
POST /conversion/status/17?library_id=L → {"running":false,"ok":true,"fmt":"epub","size":912345}
GET /get/EPUB/42/L → le fichier, désormais dans la bibliothèque

5. Pozycja odczytu i adnotacje — srv/books.py​

Calibre już synchronizuje pozycje odtwarzania po stronie serwera.

DrogaMetodaRola
/book-get-last-read-position/{library}/{id}:{FMT}POBIERZznane pozycje według urządzenia
/book-set-last-read-position/{library}/{id}/{FMT}POSTzapisuje {device, cfi, pos, pos_frac}
/book-get-annotations/{library}/{which}POBIERZpodkreślenia i notatki
/book-manifest/{id}/{FMT}POBIERZSerwer normalizuje dowolny format w manifeście dla własnego czytelnika
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom}POBIERZujednolicony zasób książkowy
/book-get-storage/{library}/{id}/{FMT}POBIERZstan przechowywania

Dwie konsekwencje dla Podbook:

Możemy porzucić gazety .jsonl opisany w początkowej specyfikacji, przynajmniej jako główny mechanizm: Calibre już utrzymuje pozycję na urządzenie, na książkę i na format. Dzienniki są nadal przydatne w przypadku tego, czego Calibre nie wie – pozycji w nagraniu, notesu ze słownictwem.

/book-manifest to skrót do oceny. Serwer już wie, jak przekształcić dowolny format w standardową strukturę dla swojego czytnika internetowego. Obejmuje to część tego, co BookKit musiało wystarczyć. Należy sprawdzić przed napisaniem parsera: format manifestu jest wewnętrzny dla Calibre, dlatego należy go traktować jako powierzchnię /ajax, zachowując ostrożność.

srv/kosync.py dodatkowo udostępnia protokół synchronizacji KOReader (/kosync/users/auth, /kosync/syncs/progress), kolejna możliwa trasa, przyjęta już przez innych czytelników.


6. Wyszukiwanie pełnotekstowe — srv/fts.py​

DrogaMetodaRola
/fts/searchPOBIERZszukaj w tekście ksiąg, nie tylko metadane
/fts/snippets/{book_ids}POBIERZfragmenty z kontekstem
/fts/reindex, /fts/indexing, /fts/disablePOSTkontrola indeksu

Indeks musi być włączony po stronie serwera. Dlatego Podbook nie musi indeksować samej biblioteki w celu wyszukiwania globalnego — tylko dla książek importowanych spoza Calibre.


7. Pisanie w bibliotece — srv/cdb.py​

POST /cdb/cmd/{commande}?library_id=L wykonuje podkomendę calibredb na serwerze. To jest Tam obsługiwany sposób zapisu: metadata.db nie toleruje drugiego redaktora.

Dostępne polecenia: add, add_format, remove, remove_format, set_metadata, set_custom, add_custom_column, remove_custom_column, custom_columns, annotations, search, list, list_categories, items, notes, data_files, embed_metadata, export, catalog, saved_searches, virtual_libraries, fts_index, fts_search, check_library, backup_metadata, restore_database, clone, trash.

set_custom umożliwia zapisanie statusu przetwarzania Podbook w niestandardowej kolumnie #podbook, widoczne z Calibre, prawidłowo.


8. OPDS — srv/opds.py​

/opds, /opds/navcatalog/{which}, /opds/category/…, /opds/search/{query}. Standard, stabilny, ogłoszony w Hello w sieci lokalnej. To wycofanie, kiedy /ajax tam nie ma — zwłaszcza przeciwko Calibre-Web.


9. Co to zmienia dla Podbook​

Hipoteza wstępnaRzeczywistość
Należy napisać parser MOBIFałsz z wersji 1: ebook-convert już wystarczyło
Konwersja wymaga warsztatu na temat MacFałsz : calibre-server konwertuje na HTTP. iPad żądań, serwer działa, biblioteka jest wzbogacona
Podbook musi wymyślić synchronizację swojej pozycjiCzęściowo fałszywe : Calibre już zawiera jeden na każde urządzenie
Podbook powinno indeksować w wyszukiwaniu globalnymFałsz : /fts/search istnieje
metadata.db tylko do odczytu, brak możliwości zapisuFałsz : /cdb/cmd/… to oficjalna trasa pisania
API /ajax to solidny fundamentFałsz : niepubliczny i niestabilny. Stąd tolerancyjne dekodowanie, wykrywanie natury i powrót OPDS

Nadal prawda: pliki chronione DRM nie zostaną otwarte, a serwer Calibre musi gdzieś działać, aby możliwa była konwersja i wyszukiwanie globalne.