跳到主要内容

API 参考

Canopy 公开了一套完整的 REST API，驱动您在 Web 界面中可以执行的所有操作。您可以使用它自动更新库存、与 CI/CD 流水线集成、构建自定义仪表板，或将 EA 数据引入其他工具（BI、GRC、ITSM、电子表格）。

完整的 OpenAPI 3.1 规范在侧边栏的 API 端点 部分中提供——每个端点、参数和响应结构均在每次发布时从后端源代码重新生成。

基础 URL​

所有 API 端点均位于 /api/v1 前缀下。您的 Canopy 环境 URL 遵循以下格式：

https://{您的-slug}-canopy.rhizo-tech.org/api/v1

将 {您的-slug} 替换为您组织的 slug，该 slug 显示在您的 Rhizo 帐户中和您用于访问 Canopy 的 URL 中。

唯一的例外是健康检查端点，它挂载在 /api/health（无版本前缀）。

交互式 API 参考​

完整的 OpenAPI 3.1 规范在侧边栏的 API 端点 部分中提供。每个端点页面都包含一个交互式操场，您可以在其中输入 bearer token 并针对您的 Canopy 环境执行实时请求。

原始规范也可供代码生成器下载：

https://docs.rhizo-tech.org/api/openapi.json
备注

要使用交互式操场，请在侧边栏 API 端点 部分中打开任意端点页面，在 Authorization 字段中输入您的 bearer token，填写参数，然后点击 Send。

身份验证​

除 /auth/*、健康检查和公共 Web 门户外，所有端点均需在 Authorization 标头中发送 JSON Web Token：

Authorization: Bearer <access_token>

获取令牌​

使用您的电子邮件和密码调用 POST /api/v1/auth/login：

curl -X POST https://{您的-slug}-canopy.rhizo-tech.org/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "your-password"}'

响应包含一个 access_token：

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer"
}

令牌有效期为 24 小时。使用 POST /api/v1/auth/refresh 无需重新输入凭据即可延长会话。

SSO 用户

如果您的组织使用单点登录，则无法通过 API 使用电子邮件/密码登录。请要求您的 Canopy 管理员创建一个专用的具有本地密码的服务账户用于自动化。

使用令牌​

curl https://{您的-slug}-canopy.rhizo-tech.org/api/v1/cards \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

权限​

API 执行与 Web 界面相同的 RBAC 规则。每个变更端点均检查调用者的应用级角色和其在受影响卡片上持有的任何利益相关者角色。没有单独的「API 权限」或服务账户绕过——自动化脚本以其使用令牌的用户权限运行。

如果请求失败并返回 403 Forbidden，则令牌有效，但用户缺少所需权限。请参阅用户与角色页面了解权限注册表。

常用端点组​

侧边栏参考是完整的可信来源；下表是最常用组的快速索引：

前缀用途
/auth登录、注册、SSO 回调、令牌刷新、当前用户信息
/cards卡片的 CRUD（核心实体）、层级、历史、审批、CSV 导出
/relations卡片间关系的 CRUD
/metamodel卡片类型、字段、节、子类型、关系类型
/reports仪表板 KPI、组合、矩阵、生命周期、依赖关系、成本、数据质量
/bpm业务流程管理——图表、元素、流程版本、评估
/ppm项目组合管理——举措、状态报告、WBS、任务、成本、风险
/turbolensAI 驱动的分析（供应商、重复项、架构 AI）
/risksEA 风险登记（TOGAF 阶段 G）
/diagramsDrawIO 图表
/soaw架构工作说明书文档
/adr架构决策记录
/users、/roles用户和角色管理（仅限管理员）
/settings应用程序设置（徽标、货币、SMTP、AI、模块开关）
/servicenowServiceNow CMDB 双向同步
/events、/notifications审计跟踪和用户通知（包括 SSE 流）

分页、筛选与排序​

列表端点接受一组一致的查询参数：

参数说明
page页码（从 1 开始）
page_size每页条目数（默认 50，最大 200）
sort_by排序字段（例如 name、updated_at）
sort_dirasc 或 desc
search自由文本筛选（在支持的地方）

特定资源的筛选器在侧边栏参考的每个端点中均有文档记录（例如 /cards 接受 type、status、parent_id、approval_status）。

实时事件（Server-Sent Events）​

GET /api/v1/events/stream 是一个长期 SSE 连接，在事件发生时推送事件（卡片已创建、已更新、已审批等）。Web 界面使用它无需轮询即可刷新徽章和列表。任何支持 SSE 的 HTTP 客户端都可以订阅——可用于构建实时仪表板或外部通知桥接。

代码生成​

由于 API 完全由 OpenAPI 3.1 描述，您可以用任何主流语言生成类型安全的客户端：

# 下载规范
curl https://docs.rhizo-tech.org/api/openapi.json -o canopy-openapi.json

# 生成 Python 客户端
openapi-generator-cli generate \
  -i canopy-openapi.json \
  -g python \
  -o ./canopy-client-py

# …或 TypeScript、Go、Java、C# 等

对于 Python 自动化，最简单的路径通常是使用 httpx 或 requests 手写调用——API 足够小，生成器很少值得引入依赖。

限流​

身份验证敏感端点（登录、注册、密码重置）进行限流以防止暴力破解攻击。其他端点目前不限流；对于繁重的自动化脚本，请在客户端实现限流。

版本控制与稳定性​

  • API 通过 /api/v1 前缀进行版本控制。重大更改将引入与之并存的 /api/v2。
  • 在 v1 内，附加更改（新端点、新可选字段）可以在次要版本和补丁版本中发布。删除或合同更改保留给主版本号升级。
  • 当前版本由 GET /api/health 报告，因此您可以通过自动化检测升级。

故障排除​

问题解决方案
401 Unauthorized令牌缺失、格式错误或已过期。通过 /auth/login 或 /auth/refresh 重新验证。
403 Forbidden令牌有效，但用户缺少所需权限。在用户与角色中检查用户的角色。
422 Unprocessable EntityPydantic 验证失败。响应体列出了哪些字段无效及原因。