Scrapyd API 接口详解：从部署到任务管理的完整指南

Scrapyd API 接口详解：从部署到任务管理的完整指南

scrapyd A service daemon to run Scrapy spiders 项目地址: https://gitcode.com/gh_mirrors/sc/scrapyd

什么是Scrapyd API

Scrapyd是一个用于部署和运行Scrapy爬虫的应用服务器，它提供了一套RESTful API接口，允许开发者通过HTTP请求来管理爬虫项目、版本和任务。这套API是Scrapyd的核心功能，使得爬虫的部署和管理可以完全自动化。

基础认证

如果启用了基础认证（Basic Authentication），在调用API时需要提供用户名和密码。使用curl时可以通过-u参数指定：

curl -u yourusername:yourpassword http://localhost:6800/daemonstatus.json

核心API接口详解

1. 服务状态检查（daemonstatus.json）

用途：检查Scrapyd服务的负载状态

请求方法：GET

返回示例：

{
  "node_name": "mynodename",
  "status": "ok",
  "pending": 0,
  "running": 0,
  "finished": 0
}

字段说明：

• node_name: 节点名称
• status: 服务状态（"ok"表示正常）
• pending: 等待执行的任务数
• running: 正在执行的任务数
• finished: 已完成的任务数

2. 项目版本管理

添加版本（addversion.json）

用途：向项目中添加一个新版本，如果项目不存在则创建

请求方法：POST

必需参数：

• project: 项目名称
• version: 版本号（遵循Python包版本规范）
• egg: 包含项目代码的Python egg文件

技术细节：

• egg文件必须设置Scrapy的入口点（entry point）
• 推荐使用scrapyd-deploy工具来生成和部署egg
• 版本号会被解析为标准的Python包版本

示例：

curl http://localhost:6800/addversion.json -F project=myproject -F version=r23 -F egg=@myproject.egg

删除版本（delversion.json）

用途：删除项目的特定版本

请求方法：POST

必需参数：

• project: 项目名称
• version: 要删除的版本号

注意：如果删除的是项目的最后一个版本，项目也会被自动删除

3. 任务调度与管理

调度任务（schedule.json）

用途：调度一个爬虫任务（相当于执行scrapy crawl命令）

请求方法：POST

必需参数：

• project: 项目名称
• spider: 爬虫名称

可选参数：

• _version: 项目版本（默认使用最新版本）
• jobid: 任务ID（默认生成UUID v1）
• priority: 任务优先级（数字越大优先级越高）
• setting: 可以覆盖Scrapy的设置
• 其他参数：将作为爬虫的参数传递

重要提示：

• 爬虫类必须能够接受任意数量的关键字参数
• 重复参数只有第一个值会被传递到爬虫

任务状态查询（status.json）

用途：查询特定任务的当前状态

请求方法：GET

必需参数：

• job: 任务ID
• project: 项目名称（可选）

返回状态：可能是"pending"、"running"或"finished"

取消任务（cancel.json）

用途：取消正在运行或等待的任务

请求方法：POST

必需参数：

• project: 项目名称
• job: 任务ID

技术细节：

• 对运行中的任务会发送终止信号
• Windows默认发送BREAK信号，其他系统默认发送INT信号

4. 项目与爬虫查询

项目列表（listprojects.json）

用途：获取所有项目名称列表

请求方法：GET

版本列表（listversions.json）

用途：获取项目的所有版本号

请求方法：GET

必需参数：

• project: 项目名称

返回顺序：按版本号排序，最新版本在最后

爬虫列表（listspiders.json）

用途：获取项目中特定版本的爬虫列表

请求方法：GET

必需参数：

• project: 项目名称

可选参数：

• _version: 项目版本（默认使用最新版本）

注意：对于通过scrapy.cfg配置的项目，不应指定版本参数

任务列表（listjobs.json）

用途：获取项目的所有任务（包括等待中、运行中和已完成）

请求方法：GET

可选参数：

• project: 项目名称（用于筛选）

返回数据结构：

• pending: 等待中的任务
• running: 运行中的任务（包含进程ID和开始时间）
• finished: 已完成的任务（包含开始和结束时间）

日志和输出：

• log_url: 日志文件路径（如果启用了日志目录）
• items_url: 输出文件路径（如果启用了items目录）

5. 项目管理

删除项目（delproject.json）

用途：删除整个项目及其所有版本

请求方法：POST

必需参数：

• project: 项目名称

最佳实践建议

1. 版本管理：为每个部署使用不同的版本号，便于回滚和追踪

2. 任务优先级：合理使用priority参数管理重要任务的执行顺序

3. 日志管理：配置logs_dir以保留任务日志，便于问题排查

4. 参数传递：确保爬虫能够正确处理通过API传递的参数

5. 错误处理：检查API返回的status字段，确保操作成功

通过这套完整的API，开发者可以实现Scrapy爬虫项目的全生命周期管理，从部署、版本控制到任务调度和监控，全部可以通过HTTP接口自动化完成。

scrapyd A service daemon to run Scrapy spiders 项目地址: https://gitcode.com/gh_mirrors/sc/scrapyd