Preskoči na vsebino

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 null nikoli 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 potiKam 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​

PotUpodablja
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,3Slovar 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.

PotMetodaVloga
/conversion/book-data/{id}GETVhodni formati, izhodni formati, sprejete možnosti
/conversion/start/{id}POSTTelo {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_fmt mora biti format, ki ga knjiga dejansko ima : strežnik od tam zgradi izvorno pot in preostanek zavrne. Pričakuje ga z velikimi črkami, output_fmt z malimi črkami.
  • Status se porabi pri prvem branju terminala : del conversion_jobs[job_id], nato pa cleanup() v finally. 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.

PotMetodaVloga
/book-get-last-read-position/{library}/{id}:{FMT}GETznani položaji, na napravo
/book-set-last-read-position/{library}/{id}/{FMT}POSTshrani {device, cfi, pos, pos_frac}
/book-get-annotations/{library}/{which}GETpoudarke in opombe
/book-manifest/{id}/{FMT}GETstrežnik normalizira katero koli obliko v manifest za svoj bralnik
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom}GETvir iz normalizirane knjige
/book-get-storage/{library}/{id}/{FMT}GETstanje 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​

PotMetodaVloga
/fts/searchGETišče besedilo knjig, ne le metapodatke
/fts/snippets/{book_ids}GETizvlečene s kontekstom
/fts/reindex, /fts/indexing, /fts/disablePOSTnadzor 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 hipotezaResničnost
Napisati je treba razčlenjevalnik MOBINapačno iz v1: ebook-convert je bilo že zadostno
Pretvorba zahteva delavnico na MacNapačno : calibre-server pretvoril HTTP. iPad zahteve, strežnik deluje, knjižnica raste
Podbook mora izumiti svojo sinhronizacijo položajaDelno napačno : Calibre že vzdržuje eno, na napravo
Podbook mora indeksirati za globalno iskanjeNapačno : /fts/search obstaja
metadata.db samo za branje, pisanje ni mogočeNapačno : /cdb/cmd/… je uradna metoda pisanja
API /ajax je trdna baza podatkovNapač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.