Redmine API 实战3 步完成第一次 Redmine RESTful 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 RESTful API 集成从拿 API Key、验证连通到创建项目、更新问题、管理用户。适合刚接触 Redmine 接口的开发者有经验的读者也能用它快速核对认证、状态码和上线要点。开始前的 3 个准备1. 环境要求一个可访问的 Redmine 实例自建或本地部署均可一个能发 HTTP 请求的工具curl、Postman 或浏览器插件都行一个管理员账号用来发放 API Key2. 获取 Redmine API 密钥用浏览器登录后进入「我的账号」页面页面底部就有 API Key 的查看与重置入口对应路由是 config/routes.rb 中的get my/api_key, :to my#show_api_key post my/api_key, :to my#reset_api_key复制密钥存好。密钥只显示一次的位置要留意——重置后旧密钥立即失效集成脚本里记得同步更换。3. 建一个测试项目在网页上新建一个名叫api-test的项目后面所有请求都用它做目标避免污染正式数据。拿到第一个响应先验证认证Redmine 的 API 是标准 REST 风格GET 读、POST 建、PUT 改、DELETE 删路径就是资源名比如/projects.json、/issues.json。请求返回 JSON 或 XML靠 URL 后缀决定.json或.xml。API Key 与 OAuth 怎么选API Key把密钥放在X-Redmine-API-Key请求头里简单直接适合脚本和服务器间调用OAuth2适合需要授权第三方应用、或密钥不能写进代码的场景流程更重申请应用、回调换令牌新手先用 API Key 即可服务端两种传法都认取密钥的逻辑在 app/controllers/application_controller.rb 的api_key_from_requestdef api_key_from_request if params[:key].present? params[:key].to_s elsif request.headers[X-Redmine-API-Key].present? request.headers[X-Redmine-API-Key].to_s end end安全注意密钥等价于你的账号权限不要提交进版本库、不要拼在前端页面里。用一个 GET 验证连通GET /projects.json?keyyour_api_key返回 200 且带出项目列表含刚建的api-test说明认证和路由都通了。之后正式请求统一走请求头不再用?key查询参数避免密钥出现在服务器访问日志里。最常用的 3 种资源操作POST 创建项目POST /projects.json Content-Type: application/json X-Redmine-API-Key: your_api_key { project: { name: 接口练手项目, identifier: api-demo, description: 通过 Redmine API 创建 } }成功返回 200 和完整项目 JSON。identifier一旦创建不可修改想换名只能删了重建。POST 创建 IssuePUT 更新状态创建问题Redmine 创建问题接口的最小可用字段POST /issues.json Content-Type: application/json X-Redmine-API-Key: your_api_key { issue: { project_id: 1, subject: 接口创建的第一个问题, description: 验证 issues 接口是否可用 } }更新走PUT /issues/1.json只传要改的字段PUT /issues/1.json Content-Type: application/json X-Redmine-API-Key: your_api_key { issue: { status_id: 3, assigned_to_id: 2 } }注意两点status_id受工作流限制当前状态流不到目标状态时会收到 422改状态默认会触发评论与通知可加issue: { ..., notify_about: no }关闭。用户与角色管理建用户并分配角色roles传角色 ID 数组POST /users.json Content-Type: application/json X-Redmine-API-Key: your_api_key { user: { login: zhangsan, firstname: San, lastname: Zhang, mail: zhangsanexample.com, password: S3cure-pass! } }把用户挂到项目并授角色再打一步PUT /projects/api-demo/memberships/9.json Content-Type: application/json X-Redmine-API-Key: your_api_key { membership: { role_ids: [2, 5] } }用户、项目、角色三层数据要分清用户全局存在角色全局定义membership才是把角色挂到某个项目上的纽带。出错了怎么查状态码含义常见原因401未认证密钥缺失或已重置失效403无权限该账号角色不允许此操作如只有普通成员却调了/users.json的创建404资源不存在项目 ID、问题 ID 写错或项目已被删除422参数被拒绝必填字段缺失、状态流不合法、identifier 重复调试三招先看响应体错误信息在 JSON 的errors数组里逐条读比猜状态码快得多降维验证同样的请求换个明确存在的 ID 再发一次能区分「ID 错了」还是「权限不够」对照官方测试用例接口的合法字段和边界行为在 test/integration/api_test/issues_test.rb 里有完整覆盖拿不准的字段先翻它真正提效的技巧批量操作一次POST /issues.json只建一个问题但可以先建项目、再在脚本里循环调用Redmine 的导入功能/imports适合一次性灌入 CSV 级数据别在循环里发几百个请求。用插件扩展自定义端点Redmine 会自动加载每个插件的config/routes.rb并追加到主路由末尾逻辑同样在 config/routes.rb 的末尾所以你可以新建插件注册自己的控制器和资源路径把「批量改状态」「按标签同步」这类业务封装成内部端点而不是散落在各个脚本里。用到你自己项目里的 3 种方式CI/CD 自动化流水线失败时调 issues 接口自动建问题并挂上构建日志人工只处理不靠口口相传。数据同步定时拉/projects.json和/issues.json对比本地数据库双向同步 CRM 里的商机与 Redmine 里的需求。报表与移动端把查询结果导出成周报或让小程序读 issues 列表做轻量任务视图都不需要额外维护一份镜像数据。上线前自查清单全链路 HTTPS密钥和令牌在传输中必须加密内网服务也一样密钥不进代码库用环境变量或密钥管理服务注入并给每个集成方发独立密钥方便单独吊销错误处理写全捕获 401/403/422 并记录请求体摘要422 的errors数组进日志出问题时能回放加超时与重试写操作POST/PUT重试前先查一次是否已生效避免重复建单权限最小化给脚本建专用账号只授它需要的角色别拿管理员密钥跑日常任务【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考