Siirry pääsisältöön

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 null ei 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ä.

ReittiperheMinne 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​

TiePalauttaa
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,3sanakirja 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.

TieMenetelmäRooli
/conversion/book-data/{id}HANKIsyöttömuodot, tulostusmuodot, hyväksytyt vaihtoehdot
/conversion/start/{id}POSTrunko {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_fmt täytyy olla muodossa, joka kirjassa todella on : Palvelin rakentaa sieltä lähdepolun ja hylkää loput. Hän odottaa sitä isoilla kirjaimilla, output_fmt pienillä kirjaimilla.
  • Tila kuluu ensimmäisen päätteen lukemisen yhteydessä : del conversion_jobs[job_id] sitten cleanup() in a finally. 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.

TieMenetelmäRooli
/book-get-last-read-position/{library}/{id}:{FMT}HANKItunnetut sijainnit laitteittain
/book-set-last-read-position/{library}/{id}/{FMT}POSTtallentaa {device, cfi, pos, pos_frac}
/book-get-annotations/{library}/{which}HANKIkohokohdat ja muistiinpanot
/book-manifest/{id}/{FMT}HANKIpalvelin normalisoi minkä tahansa muodon manifestissa omalle lukijalleen
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom}HANKIstandardoitu kirjaresurssi
/book-get-storage/{library}/{id}/{FMT}HANKItallennustila

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​

TieMenetelmäRooli
/fts/searchHANKIhaku kirjojen tekstissä, ei vain metatietoja
/fts/snippets/{book_ids}HANKIotteita kontekstineen
/fts/reindex, /fts/indexing, /fts/disablePOSTindeksin 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​

AlkuhypoteesiTodellisuus
MOBI-jäsennin on kirjoitettavaVäärä versiosta 1: ebook-convert riitti jo
Muuntaminen vaatii työpajan aiheesta MacVäärin : calibre-server muuntaa muotoon HTTP. iPad-pyynnöt, palvelin toimii, kirjasto rikastuu
Podbook täytyy keksiä paikannusajoitusOsittain väärin : Calibre sisältää jo yhden laitetta kohti
Podbook pitäisi indeksoida yleistä hakua vartenVäärin : /fts/search on olemassa
metadata.db vain luku, ei kirjoitus mahdollistaVäärin : /cdb/cmd/… on virallinen kirjoitusreitti
API /ajax on vankka perustaVää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ä.