Преминете към основното съдържание

API на сървъра Calibre — проучване

Техническа и проектна документация. Този документ съдържа проучванията и предложената архитектура. Не всички описани функции са непременно налични; ръководството за потребителя и кодът уточняват текущата операция.

Проучване, проведено на 30 октомври 2026 г. от изходния код на Calibre (src/calibre/srv/), няма документация: не съществува. Реализирано и покрито от тестове в Packages/Core/Sources/CalibreKit.


1. Предупреждение, което идва от самия поддържащ​

На въпрос за документацията за API /ajax, Ковид Гоял отговаря, че не съществува, че тази повърхност не е нито публична, нито стабилна и че изходният код трябва да бъде прочетен. Последиците, отбелязани в CalibreKit :

  • всяко декодиране е толерантно — липсващо, неочаквано поле или null никога не води до неуспех на списъка с библиотеки;
  • естеството на сървъра се открива при разклоняване (detectFlavor()), защото Calibre-Web връща 404 за всичко /ajax/* и предлага само OPDS ;
  • OPDS остава резервната опция, която е стандартизирана и стабилна;
  • тестовете замразяват действителните форми на байтовете, така че надграждане на версията на 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/…Компонент на пътя, отново

Регистриран 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Речник Индексиран по ID, null За забранена книга
GET /ajax/book/{id}/{library}Метаданни на книга
GET /ajax/categories/{library}Категории от най-високо ниво
GET /ajax/category/{nom}/{library}Съдържание на категория, номерирано
GET /ajax/books_in/{cat}/{item}/{library}ID на категория Категория

Два декодиращи капана, и двата покрити от тестове:

Идентификаторът не е в обекта. /ajax/books индексира речника си по идентификатор и не го повтаря вътре. CalibreKit го инжектира чрез userInfo на декодера.

0101-01-01T00:00:00+00:00 означава „няма дата“. Това е стражът UNDEFINED_DATE на Calibre. Наивно декодиран, той създава книга, публикувана в Antiquity. CalibreDate го връща към nil.


4. Конвертиране — srv/convert.py​

Това е откритието, което променя архитектурата: сървърът Calibre конвертира чрез HTTP.

МаршрутМетодРоля
/conversion/book-data/{id}GETВходни формати, изходни формати, приети опции
/conversion/start/{id}POSTТяло {input_fmt, output_fmt, options} → връща работещ идентификатор
/conversion/status/{job}POST{running, percent, msg} след това състоянието на терминала; ?abort_job=1 прекъсвания

Детайли, взети от източника, всички важни при употреба:

  • Само POST (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}GETизвестни позиции, за всяко устройство
/book-set-last-read-position/{library}/{id}/{FMT}POSTзапазва {device, cfi, pos, pos_frac}
/book-get-annotations/{library}/{which}GETакценти и бележки
/book-manifest/{id}/{FMT}GETсървърът нормализира всеки формат в манифест за собствения си четец
/book-file/{id}/{FMT}/{taille}/{mtime}/{nom}GETресурс от нормализираната книга
/book-get-storage/{library}/{id}/{FMT}GETсъстояние на съхранение

Две последствия за Podbook:

Логовете могат да бъдат изоставени .jsonl описано в първоначалните спецификации, поне като основен механизъм: Calibre вече държи позиция за всяко устройство, за всяка книга и за всеки формат. Логовете остават полезни за това, което Calibre не знае - позицията в аудиото, тетрадката с речник.

/book-manifest е пряк път за оценка. Сървърът вече знае как да трансформира всеки формат в стандартизирана структура за своя уеб четец. Това покрива част от това, което BookKit е трябвало да направи. Да се ​​проучи преди писане на парсера: форматът на манифеста е вътрешен за Calibre, така че трябва да се третира като повърхността /ajax, с повишено внимание.

srv/kosync.py също така предоставя протокола за синхронизация на KOReader (/kosync/users/auth, /kosync/syncs/progress), друг възможен подход, вече възприет от други четци.


6. Търсене в пълен текст — srv/fts.py​

МаршрутМетодРоля
/fts/searchGETтърси текста на книгите, не само метаданните
/fts/snippets/{book_ids}GETизвлечени с контекста
/fts/reindex, /fts/indexing, /fts/disablePOSTконтрол на индекса

Индексът трябва да е активиран от страна на сървъра. Следователно 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}. Стандартен, стабилен, рекламиран като Bonjour в локалната мрежа. Това е резервният вариант, когато /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 сървър, за да е възможно преобразуването и глобалното търсене.