Palvelimen Calibre API — merkitty
Tekninen tiedosto ja suunnittelu. Tämä asiakirja säilyttää tutkimukset ja suunnitellun arkkitehtuurin. Kaikki kuvatut toiminnot eivät välttämättä ole käytettävissä; the käyttöopas ja koodi määrittävät nykyisen toiminnon.
Lausunto tehty 30. lokakuuta 2026 lähdekoodista Calibre (src/calibre/srv/), ei dokumentaatiota: niitä ei ole olemassa. Toteutettu ja testattu vuonna Packages/Core/Sources/CalibreKit.
1. Varoitus, joka tulee ylläpitäjältä itseltään
Kysyttiin asiakirjoista API /ajax, Kovid Goyal vastaa, että sitä ei ole olemassa, että tämä pinta ei ole ei julkinen eikä vakaa, ja sinun on luettava lähde. Seuraukset säilyneet CalibreKit :
- kaikki dekoodaus on suvaitsevaista — puuttuva, odottamaton tai
nullei koskaan aiheuta kirjastoluettelon epäonnistumista; - palvelimen luonne havaitaan yhteyden muodostamisen yhteydessä (
detectFlavor()), koska Calibre-Web vastaa 404 kaikkeen/ajax/*ja tarjoaa vain OPDS; - OPDS pysyy varareittinä, standardoitu ja vakaa;
- -testit pysäyttävät todelliset tavumuodot, joten Calibre-päivitys katkaisee testin sovelluksen sijaan.
2. Kolme kirjaston nimeämiskäytäntöä
Tämä on tämän API tärkein ansa. Se on koodattu kerran sisään CalibreClient.url(path:query:libraryInQuery:) ja vahvistettu neljällä testillä.
| Reittiperhe | Minne on menossa library_id |
|---|---|
/ajax/…, /get/… | polkukomponentti — /ajax/search/Calibre_Library |
/conversion/…, /cdb/…, /fts/… | kyselyparametri — ?library_id=Calibre_Library |
/book-…-last-read-position/… | polkukomponentti, jälleen |
Kirjautunut sisään srv/utils.py : get_library_data() sänky rd.query.get('library_id').
3. Luettelo — srv/ajax.py
| Tie | Palauttaa |
|---|---|
GET /ajax/library-info | {library_map, default_library} — toimii myös palvelimen luonnetestinä |
GET /ajax/search/{library} | {total_num, offset, num, book_ids, …}, parametrit query, num, offset, sort, sort_order, vl |
GET /ajax/books/{library}?ids=1,2,3 | sanakirja indeksoitu tunnisteen mukaan, null kielletystä kirjasta |
GET /ajax/book/{id}/{library} | kirjan metatiedot |
GET /ajax/categories/{library} | ensimmäisen tason luokat |
GET /ajax/category/{nom}/{library} | luokan sisältö sivutettuna |
GET /ajax/books_in/{cat}/{item}/{library} | luokan tunnisteet |
Kaksi dekoodauksen sudenkuoppaa, jotka molemmat on testattu:
Tunniste ei ole aiheessa. /ajax/books indeksoi sanakirjansa tunnisteen mukaan eikä toista sitä sisällä. CalibreKit ruiskuttaa sen userInfo dekooderista.
0101-01-01T00:00:00+00:00 tarkoittaa "ei päivämäärää". Se on vartija UNDEFINED_DATE / Calibre. Naiivisti dekoodattu se tuottaa kirjan, joka on julkaistu Antiikissa. CalibreDate tuo sen takaisin nil.
4. Muunnos — srv/convert.py
Tämä on löytö, joka muuttaa arkkitehtuuria: palvelin Calibre muuntaa, HTTP.
| Tie | Menetelmä | Rooli |
|---|---|---|
/conversion/book-data/{id} | HANKI | syöttömuodot, tulostusmuodot, hyväksytyt vaihtoehdot |
/conversion/start/{id} | POST | runko {input_fmt, output_fmt, options} → palauttaa työtunnuksen |
/conversion/status/{job} | POST | {running, percent, msg} sitten päätetila; ?abort_job=1 keskeyttää |
Lähteeseen merkityt tiedot ja kaikki käytön kannalta merkitykselliset:
- Vain POST (
receive_data_methods = {'POST'}). GET evätään. input_fmttäytyy olla muodossa, joka kirjassa todella on : Palvelin rakentaa sieltä lähdepolun ja hylkää loput. Hän odottaa sitä isoilla kirjaimilla,output_fmtpienillä kirjaimilla.- Tila kuluu ensimmäisen päätteen lukemisen yhteydessä :
del conversion_jobs[job_id]sittencleanup()in afinally. Päätelmän voi lukea vain kerran. Ja vain käyttäjä, joka käynnisti työn samassa kirjastossa, voi kysyä sitä.CalibreKit.convert(…)käärii mittaussilmukan, joten soittajan ei tarvitse ajatella sitä. - Tuotemuoto lisätään kirjaan kirjastossa :
db.add_format(book_id, fmt, output_path). Työ tehdään siis vain kerran, ja sitten kaikki laitteet hyötyvät siitä./get/EPUB/{id}. - Reseptitiedostot evätään (koodin suoritus), ja verkko on kieltänyt luettelon vaihtoehdoista.
Koko reitti, esim CalibreKit toteuttaa sen:
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. Lukupaikka ja huomautukset — srv/books.py
Calibre synkronoi jo toistopaikat palvelinpuolella.
| Tie | Menetelmä | Rooli |
|---|---|---|
/book-get-last-read-position/{library}/{id}:{FMT} | HANKI | tunnetut sijainnit laitteittain |
/book-set-last-read-position/{library}/{id}/{FMT} | POST | tallentaa {device, cfi, pos, pos_frac} |
/book-get-annotations/{library}/{which} | HANKI | kohokohdat ja muistiinpanot |
/book-manifest/{id}/{FMT} | HANKI | palvelin normalisoi minkä tahansa muodon manifestissa omalle lukijalleen |
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom} | HANKI | standardoitu kirjaresurssi |
/book-get-storage/{library}/{id}/{FMT} | HANKI | tallennustila |
Kaksi seurausta Podbook:lle:
Voimme hylätä sanomalehdet .jsonl kuvattu alkuperäisissä teknisissä tiedoissa, ainakin päämekanismina: Calibre sisältää jo aseman laitetta, kirjaa ja muotoa kohti. Lokit ovat edelleen hyödyllisiä sille, mitä Calibre ei tiedä – sijainnista äänikirjassa, sanastomuistikirjassa.
/book-manifest on arvioinnin pikakuvake. Palvelin osaa jo muuttaa minkä tahansa muodon standardoiduksi rakenteeksi verkkolukijaansa varten. Tämä kattaa osan mistä BookKit piti tehdä. Tutkittava ennen jäsentimen kirjoittamista: luettelon muoto on Calibre:n sisäinen, joten sitä on käsiteltävä pintana /ajax, varoen.
srv/kosync.py paljastaa lisäksi KOReaderin synkronointiprotokollan (/kosync/users/auth, /kosync/syncs/progress), toinen mahdollinen reitti, jonka muut lukijat ovat jo ottaneet käyttöön.
6. Koko tekstihaku — srv/fts.py
| Tie | Menetelmä | Rooli |
|---|---|---|
/fts/search | HANKI | haku kirjojen tekstissä, ei vain metatietoja |
/fts/snippets/{book_ids} | HANKI | otteita kontekstineen |
/fts/reindex, /fts/indexing, /fts/disable | POST | indeksin ohjaus |
Indeksin on oltava käytössä palvelinpuolella. Podbook ei siis tarvitse indeksoida itse kirjastoa maailmanlaajuista hakua varten – vain kirjoille, jotka on tuotu tunnuksen Calibre ulkopuolelle.
7. Kirjoittaminen kirjastoon — srv/cdb.py
POST /cdb/cmd/{commande}?library_id=L suorittaa alikomennon calibredb palvelimella. Se on siellä tuettu tapa kirjoittaa: metadata.db ei siedä toista editoria.
Käytettävissä olevat komennot: 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 antaa sinun kirjoittaa Podbook käsittelyn tilan mukautettuun sarakkeeseen #podbook, näkyy kohdasta Calibre, oikein.
8. OPDS — srv/opds.py
/opds, /opds/navcatalog/{which}, /opds/category/…, /opds/search/{query}. Vakio, vakaa, julkistettiin Hellossa paikallisessa verkossa. Se on peruuttaminen, kun /ajax ei ole olemassa – etenkään Calibre-Web vastaan.
9. Mitä tämä muuttaa kohteelle Podbook
| Alkuhypoteesi | Todellisuus |
|---|---|
| MOBI-jäsennin on kirjoitettava | Väärä versiosta 1: ebook-convert riitti jo |
| Muuntaminen vaatii työpajan aiheesta Mac | Väärin : calibre-server muuntaa muotoon HTTP. iPad-pyynnöt, palvelin toimii, kirjasto rikastuu |
| Podbook täytyy keksiä paikannusajoitus | Osittain väärin : Calibre sisältää jo yhden laitetta kohti |
| Podbook pitäisi indeksoida yleistä hakua varten | Väärin : /fts/search on olemassa |
metadata.db vain luku, ei kirjoitus mahdollista | Väärin : /cdb/cmd/… on virallinen kirjoitusreitti |
API /ajax on vankka perusta | Väärin : ei julkinen, ei vakaa. Tästä johtuen suvaitsevainen dekoodaus, luonnontunnistus ja vara OPDS |
Totta edelleen: DRM-suojatut tiedostot eivät avaudu, ja Calibre-palvelimen on oltava käynnissä jossain, jotta muunnos ja yleinen haku ovat käytettävissä.