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/redmineRedmine REST API 是这套开源项目管理工具对外开放数据的能力核心。通过标准的 HTTP 请求你可以读写项目、问题、用户、时间记录等几乎所有资源把任务创建、状态同步、报表拉取这些重复劳动交给脚本完成。本文面向第一次接触 Redmine API 的新手从密钥配置讲起带你走完一条能直接落地的集成路径。3步上手拿到密钥发出第一个请求 API 密钥是访问的门票。每个用户都可以独立生成自己的密钥管理入口就藏在个人资料里。对应的路由定义在 config/routes.rb 中my/api_keyGET用于查看当前密钥my/api_keyPOST用于重置重新生成一个新密钥生成密钥的操作路径登录 Redmine → 点击右上角用户名 → 我的账号 → 找到 API 访问密钥区域 → 点击重置。复制保存好它之后不再完整显示。拿到密钥后有三种方式把它带给服务器任选其一URL 查询参数GET /issues.json?key你的密钥请求头X-Redmine-API-Key: 你的密钥OAuth2 授权码流程适合需要代表用户访问的第三方应用建议脚本化场景优先使用请求头方式避免密钥出现在日志记录的 URL 里。你的第一个请求——列出所有公开问题curl -H X-Redmine-API-Key: 你的密钥 \ http://你的redmine地址/issues.json?limit1返回一个 JSON 数组包含total_count和issues字段。如果拿到 200 状态码说明认证链路已通。想验证各种认证方式的边界行为可以看看 test/integration/api_test/authentication_test.rb。核心资源操作问题、项目、用户的读写套路Redmine 的 API 资源划分和界面里的模块一一对应URL 后缀决定格式.json返回 JSON.xml返回 XML。所有资源都遵循同一套模式操作HTTP 方法示例端点列表GET/issues.json?project_id1单条GET/issues/12.json创建POST/issues.json更新PUT/issues/12.json删除DELETE/issues/12.json以最常用的问题为例创建一个问题的请求体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_idopenassigned_to_idme几乎所有属性都可以作为过滤条件多个条件之间是与关系。分页limit控制条数、offset控制起始位置。配合返回里的total_count可以循环取完全部数据。拉全量数据时建议limit100分批进行避免单次响应过大。关联加载includechildren,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 密钥更安全。常见报错排查清单现象可能原因处理建议401 Unauthorized密钥缺失或错误确认请求头拼写密钥重置过则重新获取403 Forbidden当前用户无权访问该资源换用有权限的账号密钥或请管理员授权404 Not Found忘了.json后缀或资源 ID 不存在URL 补上格式后缀核对 ID400 且提示参数问题必填字段缺失如创建问题缺 project_id按错误信息补齐字段返回 HTML 而非 JSON未登录且未带密钥命中了登录页检查认证方式是否生效另外提醒一点生产环境实践务必使用 HTTPS 传输。API 密钥等同于账号密码明文 HTTP 下的密钥一旦泄露等于交出整个账号的权限。下一步怎么做按这个顺序走半小时内可以跑通第一条集成登录 Redmine在我的账号里生成 API 密钥用curl请求一次/issues.json?limit1确认返回 JSON打开 test/integration/api_test/找到你要操作的资源对应的测试文件照着请求格式写第一个脚本需要事件通知的场景再配置项目级 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考