企业官网建设流程全解析

Redmine REST API 实战指南：从密钥获取到自动化集成的完整路径

【免费下载链接】redmineMirror of redmine code source - Official Subversion repository is at https://svn.redmine.org/redmine - contact: @vividtone or maeda (at) farend (dot) jp项目地址: https://gitcode.com/GitHub_Trending/re/redmine

Redmine REST API 是这套开源项目管理工具对外开放数据的能力核心。通过标准的 HTTP 请求，你可以读写项目、问题、用户、时间记录等几乎所有资源，把任务创建、状态同步、报表拉取这些重复劳动交给脚本完成。本文面向第一次接触 Redmine API 的新手，从密钥配置讲起，带你走完一条能直接落地的集成路径。

3步上手：拿到密钥，发出第一个请求

🔑 API 密钥是访问的"门票"。每个用户都可以独立生成自己的密钥，管理入口就藏在个人资料里。对应的路由定义在 config/routes.rb 中：

• my/api_key（GET）用于查看当前密钥
• my/api_key（POST）用于重置，重新生成一个新密钥

生成密钥的操作路径：登录 Redmine → 点击右上角用户名 → "我的账号" → 找到 API 访问密钥区域 → 点击"重置"。复制保存好它，之后不再完整显示。

拿到密钥后，有三种方式把它带给服务器，任选其一：

• URL 查询参数：GET /issues.json?key=你的密钥
• 请求头：X-Redmine-API-Key: 你的密钥
• OAuth2 授权码流程（适合需要代表用户访问的第三方应用）

建议脚本化场景优先使用请求头方式，避免密钥出现在日志记录的 URL 里。

你的第一个请求——列出所有公开问题：

curl -H "X-Redmine-API-Key: 你的密钥" \ "http://你的redmine地址/issues.json?limit=1"

返回一个 JSON 数组，包含total_count和issues字段。如果拿到 200 状态码，说明认证链路已通。想验证各种认证方式的边界行为，可以看看 test/integration/api_test/authentication_test.rb。

核心资源操作：问题、项目、用户的读写套路

Redmine 的 API 资源划分和界面里的模块一一对应，URL 后缀决定格式：.json返回 JSON，.xml返回 XML。所有资源都遵循同一套模式：

以最常用的"问题"为例，创建一个问题的请求体：

POST /issues.json Content-Type: application/json { "issue": { "project_id": 1, "subject": "API 创建的示例任务", "description": "由脚本自动创建", "assigned_to_id": 5 } }

几个值得注意的点：

• 参数命名和界面对齐：status_id、priority_id、due_date等字段与网页表单用的是同一套内部属性，理解界面操作就能猜到 API 参数。
• 权限实时生效：API 请求以你的身份执行，界面里看不到的问题，API 同样拿不到。管理员可以整体关闭 REST API，相关行为见 test/integration/api_test/disabled_rest_api_test.rb。
• 测试用例是最好的文档：test/integration/api_test/ 目录下有 30 多个资源类别的集成测试，覆盖创建、更新、删除、自定义字段等场景，遇到具体资源时先来这里查参数写法，比翻零散文档更快。

灵活取数：过滤、分页与 include 一次讲清

列表类接口（GET 列表端点）的强大之处在于查询参数，三个最常用：

• 过滤：GET /issues.json?status_id=open&assigned_to_id=me，几乎所有属性都可以作为过滤条件，多个条件之间是"与"关系。
• 分页：limit控制条数、offset控制起始位置。配合返回里的total_count可以循环取完全部数据。拉全量数据时建议limit=100分批进行，避免单次响应过大。
• 关联加载：include=children,journals,attachments可以一次带回子任务、评论、附件，省掉 N 次额外请求。做同步脚本时这个参数能显著减少往返。

📦 更新问题时的一个易错点：PUT 请求只包含你要改的字段即可，不必回传完整对象。但如果操作自定义字段，键名格式是cf_字段ID，例如"cf_7": "新值"。自定义字段的 API 行为在 test/integration/api_test/custom_fields_test.rb 中有完整演示。

数据向外推：Webhook 与 OAuth2 应用

API 擅长"拉"，而当你希望"推"——比如问题一有变更就通知 CI 系统——新版 Redmine 内置了 Webhook 能力：

• 在项目设置中为指定事件（问题创建、更新等）配置回调地址
• 服务端以 POST + JSON 载荷推送事件，实现逻辑见 app/models/webhook.rb
• 若配置了签名密钥，请求会携带X-Redmine-Signature-256头，你的接收端应校验该签名以防伪造

对于需要"代表用户"访问的第三方应用（如企业内门户嵌入），Redmine 集成了 OAuth2 授权框架，相关应用管理界面由 app/controllers/oauth2_applications_controller.rb 提供，服务端行为配置在 config/initializers/doorkeeper.rb。管理员可以在"管理 → OAuth2 应用程序"中登记应用并限定访问范围，这比长期持有某个人的 API 密钥更安全。

常见报错排查清单

另外提醒一点生产环境实践：务必使用 HTTPS 传输。API 密钥等同于账号密码，明文 HTTP 下的密钥一旦泄露，等于交出整个账号的权限。

下一步怎么做

按这个顺序走，半小时内可以跑通第一条集成：

1. 登录 Redmine，在"我的账号"里生成 API 密钥
2. 用curl请求一次/issues.json?limit=1，确认返回 JSON
3. 打开 test/integration/api_test/，找到你要操作的资源对应的测试文件，照着请求格式写第一个脚本
4. 需要事件通知的场景，再配置项目级 Webhook

想深入了解安装与环境准备，可以查看 doc/ 目录下的官方文档；API 相关的行为验证始终以集成测试目录为准，它是与源码同步更新的"活文档"。

【免费下载链接】redmineMirror of redmine code source - Official Subversion repository is at https://svn.redmine.org/redmine - contact: @vividtone or maeda (at) farend (dot) jp项目地址: https://gitcode.com/GitHub_Trending/re/redmine