Calibre 서버의 API - 조사
기술 및 설계 문서 본 문서는 연구 및 제안된 아키텍처를 포함합니다. 설명된 모든 기능이 반드시 사용 가능한 것은 아니며, 사용자 가이드 및 코드는 현재 작동 방식을 설명합니다.
2026년 10월 30일 Calibre의 소스 코드를 기반으로 수행된 조사" (src/calibre/srv/), 문서 없음: 존재하지 않습니다. 구현 및 테스트는 Packages/Core/Sources/CalibreKit.
1. 유지보수 담당자 본인이 제기한 경고
API에 대한 문서에 대해 문의했을 때 /ajax, Kovid Goyal은 문서가 존재하지 않으며, 이 표면은 공개되지도 안정적이지도 않다, 소스 코드를 읽어야 한다고 답변했습니다. 결과는 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 | 사전 식별자로 색인화됨, 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} | 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()afinally. 결론은 한 번만 읽을 수 있습니다. 그리고 동일한 라이브러리에서 작업을 시작한 사용자만 결과를 조회할 수 있습니다.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/search | GET | 검색 도서 본문에서 메타데이터뿐 아니라 |
/fts/snippets/{book_ids} | GET | 컨텍스트를 포함한 추출 |
/fts/reindex, /fts/indexing, /fts/disable | POST | 인덱스 구동 |
인덱스는 서버 측에서 활성화되어야 합니다. 따라서 Podbook은 전역 검색을 위해 라이브러리 자체를 인덱싱할 필요가 없으며, Calibre 외부에서 가져온 도서에 대해서만 인덱싱하면 됩니다.
7. 도서관에서 글쓰기 — srv/cdb.py
POST /cdb/cmd/{commande}?library_id=L 하위 명령을 실행합니다 calibredb 서버에 있습니다. 그렇습니다. la 쓰기에 지원되는 경로: 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 서버가 어딘가에서 실행 중이어야 합니다.