API strežnika Calibre — anketa
Tehnična in oblikovna dokumentacija. Ta dokument vsebuje študije in predlagano arhitekturo. Vse opisane funkcije niso nujno na voljo; uporabniški priročnik in koda določata trenutno operacijo.
Anketa je bila izvedena 30. oktobra 2026 iz izvorne kode Calibre (src/calibre/srv/), dokumentacije ni: ne obstaja. Izvedeno in zajeto s testi v Packages/Core/Sources/CalibreKit.
1. Opozorilo, ki prihaja od samega vzdrževalca
Na vprašanje o dokumentaciji za API /ajax Kovid Goyal odgovori, da ne obstaja, da ta površina ni niti javna niti stabilna in da je treba prebrati izvorno kodo. Posledice, navedene v CalibreKit :
- , so vse dekodiranje tolerantno — manjkajoče, nepričakovano polje ali
nullnikoli ne povzroči neuspeha vpisa v knjižnico; - narava strežnika se zazna pri razvejanju (
detectFlavor()), ker Calibre-Web vrne 404 za vse/ajax/*in ponuja samo OPDS ; - OPDS ostaja rezervna možnost, ki je standardizirana in stabilna;
- testi zamrznejo dejanske oblike bajtov, tako da bo nadgradnja različice Calibre pokvarila test in ne aplikacije.
2. Tri konvencije za poimenovanje knjižnice
To je glavna past te API. Kodirana je enkrat v CalibreClient.url(path:query:libraryInQuery:) in preverjena s štirimi testi.
| Družina poti | Kam gre? library_id |
|---|---|
/ajax/…, /get/… | Komponenta poti — /ajax/search/Calibre_Library |
/conversion/…, /cdb/…, /fts/… | Parameter poizvedbe — ?library_id=Calibre_Library |
/book-…-last-read-position/… | Komponenta poti, ponovno |
Prijavljeno srv/utils.py : get_library_data() Branje rd.query.get('library_id').
3. Katalog — srv/ajax.py
| Pot | Upodablja |
|---|---|
GET /ajax/library-info | {library_map, default_library} — služi tudi kot preizkus narave strežnika |
GET /ajax/search/{library} | {total_num, offset, num, book_ids, …}, parametri query, num, offset, sort, sort_order, vl |
GET /ajax/books/{library}?ids=1,2,3 | Slovar Indeksirano z ID-jem, null Za prepovedano knjigo |
GET /ajax/book/{id}/{library} | Metapodatki knjige |
GET /ajax/categories/{library} | Kategorije najvišje ravni |
GET /ajax/category/{nom}/{library} | Vsebina kategorije, oštevilčena |
GET /ajax/books_in/{cat}/{item}/{library} | ID-ji kategorije Kategorija |
Dve dekodirni pasti, obe zajeti z Testi:
Identifikatorja ni v objektu. /ajax/books indeksira svoj slovar po identifikatorju in ga ne ponavlja znotraj. CalibreKit ga vbrizga prek userInfo dekoderja.
0101-01-01T00:00:00+00:00 pomeni "brez datuma". To je stražar UNDEFINED_DATE Calibre. Naivno dekodiran, ustvari knjigo, objavljeno v Antiquity. CalibreDate ga vrne nazaj v nil.
4. Pretvorba — srv/convert.py
To je odkritje, ki spremeni arhitekturo: strežnik Calibre pretvori prek HTTP.
| Pot | Metoda | Vloga |
|---|---|---|
/conversion/book-data/{id} | GET | Vhodni formati, izhodni formati, sprejete možnosti |
/conversion/start/{id} | POST | Telo {input_fmt, output_fmt, options} → vrne delujoč identifikator |
/conversion/status/{job} | POST | {running, percent, msg} nato stanje terminala; ?abort_job=1 prekinitve |
Podrobnosti, vzete iz vira, vse pomembne pri uporabi:
- Samo POST (
receive_data_methods = {'POST'}). Zahteva GET je zavrnjena. input_fmtmora biti format, ki ga knjiga dejansko ima : strežnik od tam zgradi izvorno pot in preostanek zavrne. Pričakuje ga z velikimi črkami,output_fmtz malimi črkami.- Status se porabi pri prvem branju terminala :
del conversion_jobs[job_id], nato pacleanup()vfinally. Zaključek je mogoče prebrati samo enkrat. In poizvedbo lahko izvede samo uporabnik, ki je začel opravilo v isti knjižnici.CalibreKit.convert(…)zajame zanko anketiranja, tako da noben klicatelj ne mora razmišljati o tem. - Izdelana oblika se doda knjigi v knjižnici :
db.add_format(book_id, fmt, output_path). Opravilo se torej opravi samo enkrat in vse naprave nato izkoristijo njegove prednosti, tako da/get/EPUB/{id}. - Datoteke z recepti so zavrnjene (izvajanje kode), omrežje pa blokira seznam možnosti.
Celotna pot, kot jo izvaja CalibreKit :
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. Položaj branja in opombe — srv/books.py
Calibre že sinhronizira položaje branja na strani strežnika.
| Pot | Metoda | Vloga |
|---|---|---|
/book-get-last-read-position/{library}/{id}:{FMT} | GET | znani položaji, na napravo |
/book-set-last-read-position/{library}/{id}/{FMT} | POST | shrani {device, cfi, pos, pos_frac} |
/book-get-annotations/{library}/{which} | GET | poudarke in opombe |
/book-manifest/{id}/{FMT} | GET | strežnik normalizira katero koli obliko v manifest za svoj bralnik |
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom} | GET | vir iz normalizirane knjige |
/book-get-storage/{library}/{id}/{FMT} | GET | stanje shranjevanja |
Dve posledici za Podbook:
Dnevnike je mogoče opustiti .jsonl opisano v začetnih specifikacijah, vsaj kot glavni mehanizem: Calibre že ima položaj na napravo, na knjigo in na format. Dnevniki ostanejo uporabni za tisto, česar Calibre ne ve – položaj v zvoku, besedni zvezek.
/book-manifest je bližnjica za ocenjevanje. Strežnik že ve, kako pretvoriti kateri koli format v standardizirano strukturo za svoj spletni bralnik. To pokriva del tega, kar naj bi BookKit naredil. Pred pisanjem razčlenjevalnika je treba preveriti: format manifesta je notranji za Calibre, zato ga je treba obravnavati kot površino /ajax, vendar previdno.
srv/kosync.py razkriva tudi protokol za sinhronizacijo KOReader (/kosync/users/auth, /kosync/syncs/progress, še en možen pristop, ki so ga že sprejeli drugi bralniki.
6. Iskanje po celotnem besedilu — srv/fts.py
| Pot | Metoda | Vloga |
|---|---|---|
/fts/search | GET | išče besedilo knjig, ne le metapodatke |
/fts/snippets/{book_ids} | GET | izvlečene s kontekstom |
/fts/reindex, /fts/indexing, /fts/disable | POST | nadzor indeksa |
Indeks mora biti omogočen na strani strežnika. Podbook zato za globalno iskanje ne potrebuje indeksiranja same knjižnice — samo za knjige, uvožene zunaj Calibre.
7. Pisanje v knjižnico — srv/cdb.py
POST /cdb/cmd/{commande}?library_id=L izvede podukaz calibredb na strežniku. To je podprta metoda za pisanje: metadata.db ne prenaša drugega zapisovalnika.
Razpoložljivi ukazi: 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 vam omogoča, da stanje obdelave Podbook zapišete v stolpec po meri #podbook, ki je viden iz Calibre, lepo.
8. OPDS — srv/opds.py
/opds, /opds/navcatalog/{which}, /opds/category/…, /opds/search/{query}. Standarden, stabilen, v lokalnem omrežju oglaševan kot Bonjour. Je rezervna možnost, ko /ajax ni na voljo – zlasti ko Calibre-Web ni na voljo.
9. Kaj se s tem spremeni za Podbook
| Začetna hipoteza | Resničnost |
|---|---|
| Napisati je treba razčlenjevalnik MOBI | Napačno iz v1: ebook-convert je bilo že zadostno |
| Pretvorba zahteva delavnico na Mac | Napačno : calibre-server pretvoril HTTP. iPad zahteve, strežnik deluje, knjižnica raste |
| Podbook mora izumiti svojo sinhronizacijo položaja | Delno napačno : Calibre že vzdržuje eno, na napravo |
| Podbook mora indeksirati za globalno iskanje | Napačno : /fts/search obstaja |
metadata.db samo za branje, pisanje ni mogoče | Napačno : /cdb/cmd/… je uradna metoda pisanja |
API /ajax je trdna baza podatkov | Napačno : ni javna, ni stabilna. Zato tolerantno dekodiranje, zaznavanje narave in rezervna možnost OPDS |
Ostaja res: Datoteke, zaščitene z DRM, se ne bodo odprle in strežnik Calibre mora nekje delovati, da bosta pretvorba in globalno iskanje na voljo.