Μετάβαση στο κύριο περιεχόμενο

Το API του διακομιστή Calibre — σημειώθηκε

Τεχνικός φάκελος και σχεδιασμός. Αυτό το έγγραφο διατηρεί τις μελέτες και την προβλεπόμενη αρχιτεκτονική. Μπορεί να μην είναι διαθέσιμες όλες οι λειτουργίες που περιγράφονται. το οδηγός χρήσης και ο κωδικός καθορίζει την τρέχουσα λειτουργία.

Δήλωση που έγινε στις 30 Οκτωβρίου 2026 από τον πηγαίο κώδικα του Calibre (src/calibre/srv/), δεν υπάρχει τεκμηρίωση: δεν υπάρχει. Υλοποιήθηκε και καλύπτεται από δοκιμές σε Packages/Core/Sources/CalibreKit.


1. Προειδοποίηση, η οποία προέρχεται από τον ίδιο τον συντηρητή​

Ρωτήθηκε για τεκμηρίωση για API /ajax, ο Kovid Goyal απαντά ότι δεν υπάρχει, ότι αυτή η επιφάνεια δεν είναι ούτε δημόσιο ούτε σταθερό και ότι πρέπει να διαβάσετε την πηγή. Συνέπειες που διατηρούνται σε CalibreKit :

  • όλη η αποκωδικοποίηση είναι ανεκτική — λείπει, απροσδόκητο ή null Το δεν προκαλεί ποτέ την αποτυχία μιας λίστας βιβλιοθήκης.
  • η φύση του διακομιστή εντοπίζεται κατά τη σύνδεση (detectFlavor()), γιατί το Calibre-Web απαντά στο 404 σε όλα /ajax/* και μόνο προσφορές OPDS;
  • Το OPDS παραμένει η εναλλακτική διαδρομή, τυποποιημένο και σταθερό.
  • Οι δοκιμές παγώνουν τα πραγματικά σχήματα byte, έτσι ώστε μια αναβάθμιση του Calibre να σπάει μια δοκιμή και όχι την εφαρμογή.

2. Τρεις συμβάσεις για την ονομασία της βιβλιοθήκης​

Αυτή είναι η κύρια παγίδα αυτού του API. Κωδικοποιείται μία φορά μέσα CalibreClient.url(path:query:libraryInQuery:) και επαληθεύτηκε με τέσσερις δοκιμές.

Οικογένεια διαδρομήςΠού πηγαίνει library_id
/ajax/…, /get/…στοιχείο διαδρομής — /ajax/search/Calibre_Library
/conversion/…, /cdb/…, /fts/…παράμετρος ερωτήματος — ?library_id=Calibre_Library
/book-…-last-read-position/…στοιχείο διαδρομής, ξανά

Έγινε check in srv/utils.py : get_library_data() κρεβάτι rd.query.get('library_id').


3. Κατάλογος — srv/ajax.py​

ΔρόμοςΕπιστροφές
GET /ajax/library-info{library_map, default_library} — χρησιμεύει επίσης ως δοκιμή φύσης διακομιστή
GET /ajax/search/{library}{total_num, offset, num, book_ids, …}, παράμετροι query, num, offset, sort, sort_order, vl
GET /ajax/books/{library}?ids=1,2,3Λεξικό ευρετηριασμένο με αναγνωριστικό, null για ένα απαγορευμένο βιβλίο
GET /ajax/book/{id}/{library}τα μεταδεδομένα ενός βιβλίου
GET /ajax/categories/{library}κατηγορίες πρώτου επιπέδου
GET /ajax/category/{nom}/{library}το περιεχόμενο μιας κατηγορίας, σελιδοποιημένο
GET /ajax/books_in/{cat}/{item}/{library}τα αναγνωριστικά μιας κατηγορίας

Δύο παγίδες αποκωδικοποίησης, που καλύπτονται και οι δύο από δοκιμές:

Το αναγνωριστικό δεν υπάρχει στο θέμα. /ajax/books Το ευρετηριάζει το λεξικό του κατά αναγνωριστικό και δεν το επαναλαμβάνει μέσα. CalibreKit Το το εγχέει μέσω του userInfo του αποκωδικοποιητή.

0101-01-01T00:00:00+00:00 σημαίνει "χωρίς ημερομηνία". Είναι ο φρουρός UNDEFINED_DATE από Calibre. Αφελώς αποκωδικοποιημένο, παράγει ένα βιβλίο που εκδόθηκε στην Αρχαιότητα. CalibreDate Το το επαναφέρει στο nil.


4. Μετατροπή — srv/convert.py​

Αυτή είναι η ανακάλυψη που αλλάζει την αρχιτεκτονική: ο διακομιστής Calibre μετατρέπει, κατά HTTP.

ΔρόμοςΜέθοδοςΡόλος
/conversion/book-data/{id}ΠΑΡΕΤΕμορφές εισόδου, μορφές εξόδου, αποδεκτές επιλογές
/conversion/start/{id}ΑΝΑΡΤΗΣΗσώμα {input_fmt, output_fmt, options} → επιστρέφει ένα αναγνωριστικό εργασίας
/conversion/status/{job}ΑΝΑΡΤΗΣΗ{running, percent, msg} τότε η τερματική κατάσταση. ?abort_job=1 Το διακόπτει

Λεπτομέρειες που σημειώνονται στην πηγή και όλες σημαντικές για χρήση:

  • ΑΝΑΡΤΗΣΗ μόνο (receive_data_methods = {'POST'}). Το GET απορρίπτεται.
  • input_fmt πρέπει να είναι μια μορφή που έχει στην πραγματικότητα το βιβλίο : Ο διακομιστής δημιουργεί τη διαδρομή πηγής από εκεί και απορρίπτει τα υπόλοιπα. Το περιμένει με κεφαλαία γράμματα, output_fmt με πεζά.
  • Η κατάσταση καταναλώνεται κατά την πρώτη ανάγνωση του τερματικού : del conversion_jobs[job_id], λοιπόν cleanup() σε α finally. Μπορείτε να διαβάσετε το συμπέρασμα μόνο μία φορά. Και μόνο ο χρήστης που ξεκίνησε την εργασία, στην ίδια βιβλιοθήκη, μπορεί να την ρωτήσει. CalibreKit.convert(…) Το τυλίγει τον βρόχο ανίχνευσης, ώστε κανένας καλών να μην χρειάζεται να το σκεφτεί.
  • Η μορφή προϊόντος προστίθεται στο βιβλίο της βιβλιοθήκης : db.add_format(book_id, fmt, output_path). Επομένως, η εργασία γίνεται μόνο μία φορά και όλες οι συσκευές επωφελούνται από αυτήν. /get/EPUB/{id}.
  • Τα αρχεία συνταγών απορρίπτονται (εκτέλεση κώδικα) και η λίστα επιλογών απαγορεύεται από το δίκτυο.

Η πλήρης διαδρομή, όπως π.χ 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. Θέση ανάγνωσης και σχολιασμοί — srv/books.py​

Το Calibre συγχρονίζει ήδη τις θέσεις αναπαραγωγής, από την πλευρά του διακομιστή.

ΔρόμοςΜέθοδοςΡόλος
/book-get-last-read-position/{library}/{id}:{FMT}ΠΑΡΕΤΕγνωστές θέσεις, ανά συσκευή
/book-set-last-read-position/{library}/{id}/{FMT}ΑΝΑΡΤΗΣΗσώζει {device, cfi, pos, pos_frac}
/book-get-annotations/{library}/{which}ΠΑΡΕΤΕεπισημάνσεις και σημειώσεις
/book-manifest/{id}/{FMT}ΠΑΡΕΤΕΟ διακομιστής κανονικοποιεί οποιαδήποτε μορφή σε μανιφέστο για τον δικό του αναγνώστη
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom}ΠΑΡΕΤΕένας τυποποιημένος πόρος βιβλίων
/book-get-storage/{library}/{id}/{FMT}ΠΑΡΕΤΕκατάσταση αποθήκευσης

Δύο συνέπειες για το Podbook:

Μπορούμε να εγκαταλείψουμε τις εφημερίδες .jsonl Το περιγράφεται στις αρχικές προδιαγραφές, τουλάχιστον ως ο κύριος μηχανισμός: Το Calibre κατέχει ήδη μια θέση ανά συσκευή, ανά βιβλίο και ανά μορφή. Τα αρχεία καταγραφής εξακολουθούν να είναι χρήσιμα για αυτό που ο Calibre δεν γνωρίζει — τη θέση στον ήχο, το σημειωματάριο λεξιλογίου.

/book-manifest Το είναι μια συντόμευση για αξιολόγηση. Ο διακομιστής γνωρίζει ήδη πώς να μετατρέψει οποιαδήποτε μορφή σε μια τυποποιημένη δομή για τον αναγνώστη Ιστού του. Αυτό καλύπτει μέρος του τι BookKit έπρεπε να κάνει. Για διερεύνηση πριν από τη σύνταξη του αναλυτή: η μορφή της δήλωσης είναι εσωτερική στο Calibre, επομένως πρέπει να αντιμετωπίζεται ως επιφάνεια /ajax, με προσοχή.

srv/kosync.py Το εκθέτει επιπλέον το πρωτόκολλο συγχρονισμού KOREader (/kosync/users/auth, /kosync/syncs/progress), μια άλλη πιθανή διαδρομή, που έχει ήδη υιοθετηθεί από άλλους αναγνώστες.


6. Αναζήτηση πλήρους κειμένου — srv/fts.py​

ΔρόμοςΜέθοδοςΡόλος
/fts/searchΠΑΡΕΤΕαναζήτηση στο κείμενο των βιβλίων, όχι μόνο μεταδεδομένα
/fts/snippets/{book_ids}ΠΑΡΕΤΕαποσπάσματα με περιεχόμενο
/fts/reindex, /fts/indexing, /fts/disableΑΝΑΡΤΗΣΗΈλεγχος ευρετηρίου

Το ευρετήριο πρέπει να είναι ενεργοποιημένο από την πλευρά του διακομιστή. Επομένως, το Podbook δεν χρειάζεται να ευρετηριάσει την ίδια τη βιβλιοθήκη για καθολική αναζήτηση — μόνο για βιβλία που εισάγονται εκτός του Calibre.


7. Γράψιμο στη βιβλιοθήκη — srv/cdb.py​

POST /cdb/cmd/{commande}?library_id=L Το εκτελεί μια υποεντολή calibredb στον διακομιστή. Είναι το υποστηριζόμενος τρόπος γραφής: metadata.db Το δεν ανέχεται δεύτερο πρόγραμμα επεξεργασίας.

Διαθέσιμες εντολές: 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 Το σάς επιτρέπει να γράψετε την κατάσταση επεξεργασίας του Podbook σε μια προσαρμοσμένη στήλη #podbook, ορατός από το Calibre, σωστά.


8. OPDS — srv/opds.py​

/opds, /opds/navcatalog/{which}, /opds/category/…, /opds/search/{query}. Τυπικό, σταθερό, ανακοινώθηκε στο Hello στο τοπικό δίκτυο. Είναι η απόσυρση όταν /ajax Το δεν υπάρχει — ειδικά ενάντια στο Calibre-Web.


9. Τι αλλάζει αυτό για το Podbook​

Αρχική υπόθεσηΠραγματικότητα
Πρέπει να γραφτεί ένας αναλυτής MOBIΛάθος από v1: ebook-convert Το ήταν ήδη αρκετό
Για τη μετατροπή απαιτείται εργαστήριο στο MacΛάθος : calibre-server Το μετατρέπεται σε HTTP. iPad αιτήματα, ο διακομιστής λειτουργεί, η βιβλιοθήκη εμπλουτίζεται
Το Podbook πρέπει να εφεύρει τον χρονισμό της θέσης τουΜερικώς ψευδές : Calibre έχει ήδη ένα, ανά συσκευή
Το Podbook πρέπει να ευρετηριάσει για καθολική αναζήτησηΛάθος : /fts/search υπάρχει
metadata.db μόνο για ανάγνωση, δεν είναι δυνατή η γραφήΛάθος : /cdb/cmd/… είναι η επίσημη διαδρομή γραφής
Το API /ajax Το είναι μια γερή βάσηΛάθος : όχι δημόσιο, όχι σταθερό. Εξ ου και η ανεκτική αποκωδικοποίηση, ανίχνευση φύσης και εναλλακτική OPDS

Εξακολουθεί να ισχύει: Τα αρχεία με προστασία DRM δεν ανοίγουν και ο διακομιστής Calibre πρέπει να εκτελείται κάπου για να είναι διαθέσιμη η μετατροπή και η καθολική αναζήτηση.