mirror of
https://github.com/dataabc/weibo-crawler.git
synced 2026-10-18 23:01:10 +08:00
Troray
310 lines
7.9 KiB
Markdown
310 lines
7.9 KiB
Markdown
# Weibo API 说明文档
|
|
|
|
本文档详细介绍了基于 Flask 框架构建的 Weibo API 的各个端点及其使用方法。API 主要用于刷新微博数据、查询任务状态以及获取微博信息。
|
|
|
|
## 目录
|
|
- [Weibo API 说明文档](#weibo-api-说明文档)
|
|
- [目录](#目录)
|
|
- [概述](#概述)
|
|
- [配置说明](#配置说明)
|
|
- [API 端点](#api-端点)
|
|
- [刷新微博数据](#刷新微博数据)
|
|
- [查询任务状态](#查询任务状态)
|
|
- [获取所有微博](#获取所有微博)
|
|
- [获取单条微博详情](#获取单条微博详情)
|
|
- [定时任务](#定时任务)
|
|
- [错误处理](#错误处理)
|
|
- [日志记录](#日志记录)
|
|
- [启动和运行](#启动和运行)
|
|
- [注意事项](#注意事项)
|
|
|
|
---
|
|
|
|
## 概述
|
|
|
|
该 API 旨在通过定时任务和手动触发的任务来抓取和管理微博数据。主要功能包括：
|
|
- 刷新指定用户的微博数据
|
|
- 查询任务的执行状态
|
|
- 获取所有抓取到的微博
|
|
- 获取单条微博的详细信息
|
|
|
|
## 配置说明
|
|
|
|
在运行 API 之前，需要配置service.py相关参数。配置项包括用户ID列表、数据库路径、日志配置、下载选项等。
|
|
|
|
以下是主要配置项的说明：
|
|
|
|
```python
|
|
config = {
|
|
"user_id_list": [
|
|
"6067225218",
|
|
"1445403190"
|
|
],
|
|
"only_crawl_original": 1,
|
|
"since_date": 1,
|
|
"start_page": 1,
|
|
"write_mode": [
|
|
"csv",
|
|
"json",
|
|
"markdown",
|
|
"sqlite"
|
|
],
|
|
"original_pic_download": 0,
|
|
"retweet_pic_download": 0,
|
|
"original_video_download": 0,
|
|
"retweet_video_download": 0,
|
|
"download_comment": 0,
|
|
"comment_max_download_count": 100,
|
|
"download_repost": 0,
|
|
"repost_max_download_count": 100,
|
|
"user_id_as_folder_name": 0,
|
|
"remove_html_tag": 1,
|
|
"cookie": "your weibo cookie",
|
|
"mysql_config": {
|
|
"host": "localhost",
|
|
"port": 3306,
|
|
"user": "root",
|
|
"password": "123456",
|
|
"charset": "utf8mb4"
|
|
},
|
|
"mongodb_URI": "mongodb://[username:password@]host[:port][/[defaultauthdb][?options]]",
|
|
"post_config": {
|
|
"api_url": "https://api.example.com",
|
|
"api_token": ""
|
|
}
|
|
}
|
|
```
|
|
|
|
- **user_id_list**: 需要抓取微博的用户ID列表。
|
|
- **only_crawl_original**: 是否仅抓取原创微博（1为是，0为否）。
|
|
- **since_date**: 起始日期。
|
|
- **start_page**: 起始页码。
|
|
- **write_mode**: 数据存储模式，可选择 CSV、JSON、SQLite 等。
|
|
- **original_pic_download**: 是否下载原创微博的图片（1为是，0为否）。
|
|
- **retweet_pic_download**: 是否下载转发微博的图片（1为是，0为否）。
|
|
- **original_video_download**: 是否下载原创微博的视频（1为是，0为否）。
|
|
- **retweet_video_download**: 是否下载转发微博的视频（1为是，0为否）。
|
|
- **download_comment**: 是否下载评论（1为是，0为否）。
|
|
- **comment_max_download_count**: 评论的最大下载数量。
|
|
- **download_repost**: 是否下载转发信息（1为是，0为否）。
|
|
- **repost_max_download_count**: 转发的最大下载数量。
|
|
- **user_id_as_folder_name**: 是否使用用户ID作为文件夹名称（1为是，0为否）。
|
|
- **remove_html_tag**: 是否移除HTML标签（1为是，0为否）。
|
|
- **cookie**: 用于认证的微博Cookie。
|
|
- **mysql_config**: MySQL数据库的配置信息。
|
|
- **mongodb_URI**: MongoDB的连接URI。
|
|
- **post_config**: POST请求的配置，包括API URL和Token。
|
|
|
|
## API 端点
|
|
|
|
### 刷新微博数据
|
|
|
|
**URL:** `/refresh`
|
|
|
|
**方法:** `POST`
|
|
|
|
**描述:** 手动触发刷新指定用户的微博数据。
|
|
|
|
**请求参数:**
|
|
|
|
- `user_id_list` (可选): 需要刷新微博数据的用户ID列表。格式为JSON数组。例如：
|
|
```json
|
|
{
|
|
"user_id_list": ["6067225218", "1445403190"]
|
|
}
|
|
```
|
|
|
|
**响应:**
|
|
|
|
- **202 Accepted**
|
|
```json
|
|
{
|
|
"task_id": "任务ID",
|
|
"status": "Task started",
|
|
"state": "PENDING",
|
|
"progress": 0,
|
|
"user_id_list": ["6067225218", "1445403190"]
|
|
}
|
|
```
|
|
- **400 Bad Request** (参数无效)
|
|
```json
|
|
{
|
|
"error": "Invalid user_id_list parameter"
|
|
}
|
|
```
|
|
- **409 Conflict** (已有任务在运行)
|
|
```json
|
|
{
|
|
"task_id": "当前运行的任务ID",
|
|
"status": "Task already running",
|
|
"state": "PROGRESS",
|
|
"progress": 50
|
|
}
|
|
```
|
|
|
|
### 查询任务状态
|
|
|
|
**URL:** `/task/<task_id>`
|
|
|
|
**方法:** `GET`
|
|
|
|
**描述:** 查询指定任务的状态和进度。
|
|
|
|
**URL 参数:**
|
|
|
|
- `task_id` (必需): 需要查询的任务ID。
|
|
|
|
**响应:**
|
|
|
|
- **200 OK**
|
|
```json
|
|
{
|
|
"state": "任务状态",
|
|
"progress": 进度百分比,
|
|
"result": {
|
|
"message": "微博列表已刷新"
|
|
}
|
|
}
|
|
```
|
|
或者在任务失败时：
|
|
```json
|
|
{
|
|
"state": "FAILED",
|
|
"progress": 50,
|
|
"error": "错误信息"
|
|
}
|
|
```
|
|
- **404 Not Found** (任务不存在)
|
|
```json
|
|
{
|
|
"error": "Task not found"
|
|
}
|
|
```
|
|
|
|
### 获取所有微博
|
|
|
|
**URL:** `/weibos`
|
|
|
|
**方法:** `GET`
|
|
|
|
**描述:** 获取数据库中所有抓取到的微博，按创建时间倒序排列。
|
|
|
|
**响应:**
|
|
|
|
- **200 OK**
|
|
```json
|
|
[
|
|
{
|
|
"id": "微博ID",
|
|
"content": "微博内容",
|
|
"created_at": "创建时间",
|
|
...
|
|
},
|
|
...
|
|
]
|
|
```
|
|
- **500 Internal Server Error** (服务器错误)
|
|
```json
|
|
{
|
|
"error": "错误信息"
|
|
}
|
|
```
|
|
|
|
### 获取单条微博详情
|
|
|
|
**URL:** `/weibos/<weibo_id>`
|
|
|
|
**方法:** `GET`
|
|
|
|
**描述:** 获取指定ID的微博详细信息。
|
|
|
|
**URL 参数:**
|
|
|
|
- `weibo_id` (必需): 需要获取的微博ID。
|
|
|
|
**响应:**
|
|
|
|
- **200 OK**
|
|
```json
|
|
{
|
|
"id": "微博ID",
|
|
"content": "微博内容",
|
|
"created_at": "创建时间",
|
|
...
|
|
}
|
|
```
|
|
- **404 Not Found** (微博不存在)
|
|
```json
|
|
{
|
|
"error": "Weibo not found"
|
|
}
|
|
```
|
|
- **500 Internal Server Error** (服务器错误)
|
|
```json
|
|
{
|
|
"error": "错误信息"
|
|
}
|
|
```
|
|
|
|
## 定时任务
|
|
|
|
API 启动后，会在后台启动一个定时任务线程，每隔10分钟自动触发一次刷新任务，以确保微博数据的及时更新。如果当前有任务正在运行，定时任务会跳过本次执行。
|
|
|
|
**定时任务行为:**
|
|
- 检查是否有正在运行的任务。
|
|
- 如果没有正在运行的任务，则创建并启动一个新的刷新任务。
|
|
- 如果有任务在运行，则等待下一个周期。
|
|
|
|
**错误处理:**
|
|
- 如果定时任务执行过程中发生错误，会记录日志并在1分钟后重试。
|
|
|
|
## 错误处理
|
|
|
|
API 在处理请求时可能会遇到各种错误，主要包括：
|
|
|
|
- **400 Bad Request:** 请求参数无效。
|
|
- **404 Not Found:** 请求的资源不存在（如任务ID或微博ID）。
|
|
- **409 Conflict:** 资源冲突，如已有任务在运行。
|
|
- **500 Internal Server Error:** 服务器内部错误。
|
|
|
|
错误响应的格式统一为包含 `error` 字段的 JSON 对象，例如：
|
|
|
|
```json
|
|
{
|
|
"error": "错误信息"
|
|
}
|
|
```
|
|
|
|
## 日志记录
|
|
|
|
API 使用 Python 的 `logging` 模块进行日志记录。日志文件存储在 `log/` 目录下，默认日志配置文件为 `logging.conf`。主要记录以下内容：
|
|
|
|
- 服务启动和关闭日志
|
|
- 任务的启动、完成和失败日志
|
|
- 定时任务的执行情况
|
|
- 异常和错误信息
|
|
|
|
确保 `log/` 目录存在，API 会在启动时自动创建该目录（如果不存在）。
|
|
|
|
---
|
|
|
|
## 启动和运行
|
|
|
|
确保所有依赖库已安装，并正确配置了 `logging.conf` 文件和数据库路径。启动 API 的命令如下：
|
|
|
|
```bash
|
|
python service.py
|
|
```
|
|
|
|
API 将在默认的 `5000` 端口启动，并自动开始监听请求和执行定时任务。
|
|
|
|
---
|
|
|
|
## 注意事项
|
|
|
|
- **并发任务控制:** API 限制同一时间只能运行一个刷新任务，以避免数据冲突和资源竞争。
|
|
- **数据存储:** 默认使用 SQLite 数据库存储微博数据，配置中可根据需要调整为其他存储方式（如 MySQL、MongoDB）。
|
|
- **安全性:** 确保 `cookie` 和数据库的敏感信息安全存储，避免泄露。
|
|
|
|
如有任何疑问或问题，请参考源代码中的注释或联系开发团队。
|