Hugging Face's logo

Spaces:
eithney
/
point
Sleeping

App Files Community
1
point / docs /API_DOCUMENTATION.md
eithney
code ref
e74eb63
preview code
|
Raw
History Blame Contribute Delete
7.51 kB

书籍API文档

概述

这是一套基于SQLite数据库的书籍管理API，提供书籍列表、目录、页面内容查询等功能。

快速开始

1. 数据导入

首先需要将JSON数据导入到SQLite数据库：

python import_book_data.py

执行成功后，会在当前目录生成 books.db 文件。

2. 启动应用 

python app.py

应用默认运行在 http://localhost:7860

API端点

基础信息

  • Base URL: http://localhost:7860/api/v2
  • 返回格式: JSON
  • 编码: UTF-8

1. 获取书籍列表

获取所有可用的书籍。

请求

GET /api/v2/books

响应示例

{
  "success": true,
  "count": 1,
  "books": [
    {
      "book_id": 1,
      "book_name": "书籍ID 10242",
      "source_file": "book_10242.json",
      "total_pages": 64,
      "created_at": "2024-10-16 12:00:00",
      "updated_at": "2024-10-16 12:00:00"
    }
  ]
}

2. 获取书籍信息

获取指定书籍的详细信息。

请求

GET /api/v2/books/{book_id}

参数

参数 类型 必需 说明
book_id int 是 书籍ID

响应示例

{
  "success": true,
  "book": {
    "book_id": 1,
    "book_name": "书籍ID 10242",
    "source_file": "book_10242.json",
    "total_pages": 64,
    "created_at": "2024-10-16 12:00:00",
    "updated_at": "2024-10-16 12:00:00"
  }
}

3. 获取书籍目录

获取书籍的所有页面列表（目录）。

请求

GET /api/v2/books/{book_id}/catalog

参数

参数 类型 必需 说明
book_id int 是 书籍ID

响应示例

{
  "success": true,
  "book_id": 1,
  "book_name": "书籍ID 10242",
  "total_pages": 64,
  "catalog": [
    {
      "page_id": 34428,
      "page_number": 55,
      "origin_img_url": "https://res-100200.kingsunedu.com/...",
      "encrypt_img_url": "https://res-100200.kingsunedu.com/..."
    },
    {
      "page_id": 34429,
      "page_number": 56,
      "origin_img_url": "https://res-100200.kingsunedu.com/...",
      "encrypt_img_url": "https://res-100200.kingsunedu.com/..."
    }
  ]
}

4. 获取单页内容

获取指定页面的完整内容，包括所有文本片段、音频等。

请求

GET /api/v2/books/{book_id}/pages/{page_num}

参数

参数 类型 必需 说明
book_id int 是 书籍ID
page_num int 是 页码

响应示例

{
  "success": true,
  "book_id": 1,
  "book_name": "书籍ID 10242",
  "page": {
    "page_id": 34428,
    "page_number": 55,
    "origin_img_url": "https://res-100200.kingsunedu.com/...",
    "encrypt_img_url": "https://res-100200.kingsunedu.com/...",
    "piece_count": 15,
    "pieces": [
      {
        "piece_id": 207349,
        "original": "Unit 1",
        "translation": "",
        "origin_sound_url": "https://res-100200.kingsunedu.com/...",
        "encrypt_sound_url": "https://res-100200.kingsunedu.com/...",
        "duration": 2,
        "coordinate": {
          "x": 0.1031,
          "y": 0.1281,
          "width": 0.0857,
          "height": 0.0277
        },
        "is_evaluated": 0,
        "show_translation": 1,
        "rich_original": "",
        "rich_translation": ""
      }
    ]
  }
}

5. 搜索内容

在书籍中搜索关键词。

请求

GET /api/v2/books/{book_id}/search?keyword={keyword}&limit={limit}

参数

参数 类型 必需 说明
book_id int 是 书籍ID
keyword string 是 搜索关键词
limit int 否 返回结果数量（默认20）

响应示例

{
  "success": true,
  "book_id": 1,
  "keyword": "hello",
  "count": 3,
  "results": [
    {
      "page_id": 34428,
      "page_number": 55,
      "piece_id": 207350,
      "original": "Hello, how are you?",
      "translation": "你好，你好吗？"
    }
  ]
}

6. 获取统计信息

获取书籍的统计数据。

请求

GET /api/v2/books/{book_id}/statistics

参数

参数 类型 必需 说明
book_id int 是 书籍ID

响应示例

{
  "success": true,
  "statistics": {
    "book_id": 1,
    "total_pages": 64,
    "total_pieces": 850,
    "total_audio": 820
  }
}

错误响应

所有API在出错时返回统一格式：

{
  "success": false,
  "error": "错误信息描述"
}

常见错误码

  • 400 - 请求参数错误
  • 404 - 资源不存在
  • 500 - 服务器内部错误

使用示例

cURL 

# 获取书籍列表
curl http://localhost:7860/api/v2/books

# 获取书籍目录
curl http://localhost:7860/api/v2/books/1/catalog

# 获取第55页内容
curl http://localhost:7860/api/v2/books/1/pages/55

# 搜索内容
curl "http://localhost:7860/api/v2/books/1/search?keyword=hello&limit=10"

# 获取统计信息
curl http://localhost:7860/api/v2/books/1/statistics

Python 

import requests

base_url = "http://localhost:7860/api/v2"

# 获取书籍列表
response = requests.get(f"{base_url}/books")
books = response.json()
print(books)

# 获取第55页内容
book_id = 1
page_num = 55
response = requests.get(f"{base_url}/books/{book_id}/pages/{page_num}")
page_data = response.json()
print(page_data)

# 搜索
response = requests.get(f"{base_url}/books/{book_id}/search", params={
    'keyword': 'hello',
    'limit': 10
})
search_results = response.json()
print(search_results)

JavaScript 

const baseUrl = 'http://localhost:7860/api/v2';

// 获取书籍列表
fetch(`${baseUrl}/books`)
  .then(response => response.json())
  .then(data => console.log(data));

// 获取第55页内容
const bookId = 1;
const pageNum = 55;
fetch(`${baseUrl}/books/${bookId}/pages/${pageNum}`)
  .then(response => response.json())
  .then(data => console.log(data));

// 搜索
fetch(`${baseUrl}/books/${bookId}/search?keyword=hello&limit=10`)
  .then(response => response.json())
  .then(data => console.log(data));

数据库结构

books 表

  • book_id: 书籍ID（主键）
  • book_name: 书籍名称
  • source_file: 源文件名
  • total_pages: 总页数
  • created_at: 创建时间
  • updated_at: 更新时间

pages 表

  • page_id: 页面ID（主键）
  • book_id: 所属书籍ID（外键）
  • page_number: 页码
  • origin_img_url: 原始图片URL
  • encrypt_img_url: 加密图片URL
  • created_at: 创建时间

pieces 表

  • piece_id: 片段ID（主键）
  • page_id: 所属页面ID（外键）
  • original: 原文
  • translation: 翻译
  • origin_sound_url: 原始音频URL
  • encrypt_sound_url: 加密音频URL
  • duration: 音频时长
  • coordinate_x/y/width/height: 坐标信息
  • is_evaluated: 是否可评测
  • show_translation: 是否显示翻译
  • rich_original: 富文本原文
  • rich_translation: 富文本翻译
  • created_at: 创建时间

注意事项

  1. 首次使用前必须运行 import_book_data.py 导入数据
  2. 数据库文件 books.db 会在导入时自动创建
  3. 所有API响应都是UTF-8编码的JSON格式
  4. 页码从实际页码开始（如本例中从55开始）
  5. 音频URL有时效性，可能需要定期更新

支持

如有问题，请查看日志文件 logs/app.log