API 开发者指南

本文档面向需要通过 API 集成或扩展华杨 CMDB 系统的开发者，介绍华杨 CMDB REST API 的设计规范、认证方式、请求/响应格式和各模块 API 概览。

基础约定

URL 结构

所有 API 遵循统一的 URL 模式：

{base_url}/api/{tenantId}/cmdb/{module}/{resource}

部分	说明	示例
`base_url`	API 服务器地址	`http://localhost:8102/itom`
`tenantId`	租户 ID（路径参数）	`100000001`
`module`	模块名称	`class-model`、`tql-query`、`datain`
`resource`	资源路径	`definitions`、`definitions/{name}`

HTTP 方法语义

方法	语义	幂等性
`GET`	查询资源	是
`POST`	创建资源或执行操作	否
`PUT`	更新资源（全量替换）	是
`DELETE`	删除资源	是

请求头

Content-Type: application/json
Accept: application/json
Authorization: Bearer {access_token}

认证

系统使用 Keycloak 作为身份认证服务。调用受保护的 API 需要先获取访问令牌。

获取令牌

POST /api/{tenantId}/platform/authenticate

请求体：

{
  "username": "admin",
  "password": "admin"
}

成功响应（200）：

{
  "success": true,
  "code": 200,
  "timestamp": "2026-04-15T10:30:00.000Z",
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 300,
    "refresh_expires_in": 1800
  }
}

认证失败（401）：

{
  "success": false,
  "code": 401,
  "timestamp": "2026-04-15T10:30:00.000Z",
  "error": {
    "errorcode": "15010401",
    "message": "Invalid username or password",
    "type": "AUTHENTICATION_ERROR",
    "details": {}
  }
}

使用令牌

在后续请求中通过 Authorization 头携带令牌：

Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

统一响应格式

所有 API 响应遵循统一的信封格式，包含 success、code、timestamp 三个必填字段。

成功响应

{
  "success": true,
  "code": 200,
  "timestamp": "2026-04-10T07:28:33.695Z",
  "data": { ... }
}

错误响应

{
  "success": false,
  "code": 400,
  "timestamp": "2026-04-10T07:28:33.695Z",
  "error": {
    "errorcode": "15010400",
    "message": "Validation failed",
    "type": "VALIDATION_ERROR",
    "details": { ... }
  }
}

错误码结构

错误码为 8 位数字，由三部分组成：

{serviceCode}{moduleCode}{errorCode}

组成	说明	示例
服务码（2 位）	标识来源服务	`15` = cmdb-api, `20` = class-model
模块码（2 位）	标识模块	`01` = classModel, `02` = tqlQuery, `03` = datain
错误码（4 位）	具体错误	`0400` = 验证失败, `0404` = 未找到

错误类型

type	HTTP 状态码	说明
`VALIDATION_ERROR`	400	请求参数验证失败，`details` 中包含具体字段错误
`AUTHENTICATION_ERROR`	401	未认证或令牌无效
`AUTHORIZATION_ERROR`	403	权限不足
`NOT_FOUND_ERROR`	404	请求的资源不存在
`CONFLICT_ERROR`	409	资源冲突（如重复创建）
`RATE_LIMIT_ERROR`	429	请求频率超限
`INTERNAL_SERVER_ERROR`	500	服务器内部错误

查询参数

列表类接口支持统一的查询参数：

参数	类型	默认值	说明
`limit`	integer	20	每页记录数（1-1000）
`offset`	integer	0	偏移量
`sort`	array	-	排序条件 `[{field, direction}]`
`fields`	array	-	返回字段白名单
`filters`	array	-	过滤条件（见下文）

API 模块概览

Class Model — 配置项类型管理

管理配置项类型（Class Definition）的 CRUD 操作和继承层次。

方法	路径	说明
GET	`/class-model/definitions`	获取所有类定义
POST	`/class-model/definitions`	创建类定义
GET	`/class-model/definitions/{name}`	获取指定类定义
PUT	`/class-model/definitions/{name}`	更新类定义
DELETE	`/class-model/definitions/{name}`	删除类定义
GET	`/class-model/definitions/{name}/parents`	获取父类列表
GET	`/class-model/definitions/{name}/children`	获取子类列表
GET	`/class-model/definitions/{name}/hierarchy`	获取完整层次结构

类定义核心字段：

{
  "name": "ci_server",
  "display_name": "服务器",
  "parent_name": "ci_host",
  "description": "服务器配置项类型",
  "attributes": {
    "ip_address": {
      "name": "ip_address",
      "type": "string",
      "required": false,
      "display_name": "IP 地址"
    }
  },
  "identification_rule": {
    "attributes": ["serial_number"]
  }
}

查询参数：

includeAttributes (boolean) — 是否在响应中包含属性定义
includeMetadata (boolean) — 是否包含元数据
parentDepth / childDepth (integer) — 层次查询的深度

Datain — 数据写入

统一的数据写入入口，支持在单次请求中同时操作配置项和关系。

POST /datain/topology

操作类型（operation 字段）：

add — 新增节点和关系
update — 更新已有节点
delete — 删除节点或关系
addOrUpdate — 存在则更新，不存在则新增

请求示例：

{
  "operation": "add",
  "nodes": [
    {
      "id": "server-001",
      "type": "ci_server",
      "properties": {
        "name": "web-server-01",
        "ip_address": "192.168.1.10"
      }
    }
  ],
  "links": [
    {
      "id": "link-001",
      "type": "r_runs_on",
      "from_id": "server-001",
      "to_id": "app-001"
    }
  ]
}

nodes 中的 id 为客户端临时标识，系统完成处理后返回实际 ID。links 通过 from_id/to_id 引用节点的临时 ID 建立关系。

TQL Query — 拓扑查询

执行 TQL（Topology Query Language）查询，跨类型查询配置项及其关系数据。

POST /tql-query/execute

请求结构核心概念：

{
  "tqlQuery": {
    "type": "normal",
    "rootNode": "ci_computer",
    "limit": 20,
    "nodes": [
      {
        "type": "ci_computer",
        "queryIdentifier": "computer",
        "visible": true,
        "typeConfig": {
          "includeSubtypes": true
        },
        "layoutConfig": {
          "type": "SIMPLE",
          "items": ["name", "ip_address"]
        },
        "attributeConditions": [
          {
            "attribute": "name",
            "operator": "contains",
            "value": "server"
          }
        ],
        "linkConditions": [
          {
            "linkIdentifier": "runs_on",
            "conditionType": "exists"
          }
        ]
      }
    ],
    "relations": [
      {
        "type": "r_runs_on",
        "queryIdentifier": "runs_on",
        "from": "computer",
        "to": "app",
        "linkType": "normal"
      }
    ],
    "orderBy": [{ "field": "id", "direction": "ASC" }]
  }
}

顶层字段：

字段	说明
`type`	查询类型，目前固定为 `normal`
`rootNode`	查询的根配置项类型名称
`nodes`	查询涉及的配置项类型节点列表
`relations`	节点之间的关系定义
`orderBy`	排序配置，格式为 `[{field, direction}]`，direction 可选 `ASC` / `DESC`
`limit`	返回数量限制

nodes[] 节点字段：

字段	说明
`type`	配置项类型名称（如 `ci_computer`）
`queryIdentifier`	节点标识符，在查询内唯一，供 relations 引用
`visible`	是否在结果中返回，默认 `true`
`typeConfig`	类型配置（是否包含子类型等）
`layoutConfig`	返回字段配置
`attributeConditions`	属性过滤条件数组
`linkConditions`	关系过滤条件数组
`idCondition`	按 ID 过滤（用于指定/排除特定实例）

nodes[].typeConfig — 类型配置：

字段	说明
`includeSubtypes`	是否包含子类型。`true` = 包含自身及所有子类型（递归），`false` = 仅自身
`complexTypeConditions`	各类型单独配置，优先级高于全局 `includeSubtypes`

complexTypeConditions 每项结构：

字段	说明
`type`	类型名称
`includeSubtypes`	该类型是否包含其子类型
`exclude`	是否排除该类型本身，默认 `false`

nodes[].layoutConfig — 返回字段配置：

type 值	说明
`SIMPLE`	自定义字段列表，`items` 为字符串数组，如 `["name", "ip_address"]`
`ALL`	返回所有字段，`items` 省略
`COMPLEX`	按子类型分别配置字段

COMPLEX 模式下 items 每项结构：

字段	说明
`type`	子类型名称
`includedAttributes`	包含的字段列表（与 `excludedAttributes` 二选一）
`excludedAttributes`	排除的字段列表（与 `includedAttributes` 二选一）

nodes[].attributeConditions — 属性过滤条件：

简单条件：

{
  "attribute": "name",
  "operator": "contains",
  "value": "server"
}

条件组（支持嵌套，conditions 内可混入条件组实现不超过5层的深度）：

{
  "logicalOperator": "and",
  "not": false,
  "conditions": [
    { "attribute": "name", "operator": "contains", "value": "server" },
    {
      "logicalOperator": "or",
      "conditions": [
        { "attribute": "status", "operator": "equals", "value": "active" }
      ]
    }
  ]
}

字段	说明
`attribute`	属性名称
`operator`	操作符（见下方 TQL 操作符表）
`value`	比较值，类型为 string / number / boolean / 数组
`logicalOperator`	条件组的逻辑运算符：`and` / `or`
`not`	是否对条件组取反，默认 `false`
`conditions`	条件组的子条件数组（可嵌套条件组）

TQL 操作符：

操作符	说明
`equals`	等于
`notEquals`	不等于
`greaterThan`	大于
`greaterThanOrEqual`	大于等于
`lessThan`	小于
`lessThanOrEqual`	小于等于
`in`	在列表中
`notIn`	不在列表中
`isNull`	为空（`value: true` = IS NULL，`value: false` = IS NOT NULL）
`like`	模糊匹配
`contains`	包含
`startsWith`	开始于
`endsWith`	结束于
`containsAny`	包含任意一个（数组）
`containsAll`	包含全部（数组）
`containsIgnoreCase`	包含（不区分大小写）

nodes[].linkConditions — 关系过滤条件：

简单条件：

{
  "linkIdentifier": "runs_on",
  "conditionType": "exists"
}

条件组（支持嵌套，结构与 attributeConditions 一致）：

{
  "logicalOperator": "and",
  "not": false,
  "conditions": [
    { "linkIdentifier": "runs_on", "conditionType": "exists" },
    { "linkIdentifier": "depends_on", "conditionType": "optional" }
  ]
}

字段	说明
`linkIdentifier`	引用的 relation 的 `queryIdentifier`
`conditionType`	关系约束类型（见下表）
`logicalOperator`	条件组逻辑运算符：`and` / `or`
`not`	是否对条件组取反
`conditions`	条件组的子条件数组（可嵌套）

conditionType	说明
`exists`	关系必须存在（至少一条）
`not_exists`	关系必须不存在
`optional`	关系可有可无

分页：当响应中 hasMore 为 true 时，使用 cursor 值继续查询获取后续数据。

Query Definition — 查询定义管理

管理可复用的 TQL 查询定义。

方法	路径	说明
GET	`/query-definition/definitions`	获取所有查询定义
POST	`/query-definition/definitions`	创建查询定义
GET	`/query-definition/definitions/{name}`	获取指定查询定义
PUT	`/query-definition/definitions/{name}`	更新查询定义
DELETE	`/query-definition/definitions/{name}`	删除查询定义
GET	`/query-definition/query-groups`	获取查询分组列表
POST	`/query-definition/query-groups`	创建查询分组
PUT	`/query-definition/query-groups/{id}`	更新查询分组
DELETE	`/query-definition/query-groups/{id}`	删除查询分组
GET	`/query-definition/query-groups/{groupId}/definitions`	获取分组下的查询定义

查询参数：includeDefinition (boolean) — 列表接口默认不返回查询定义内容，设为 true 可包含。

CI History — 配置项变更历史

查询配置项的变更记录。

方法	路径	说明
GET	`/ci-history`	查询变更历史列表
GET	`/ci-history/entity/{entityId}/{entityType}`	查询指定配置项的变更历史
GET	`/ci-history/transaction/{transactionId}`	查询指定事务的变更详情

Relation History — 关系变更历史

查询配置项关系的变更记录。

方法	路径	说明
GET	`/relation-history`	查询关系变更历史列表
GET	`/relation-history/from/{fromId}/to/{toId}`	查询两个配置项之间的变更历史

CI Export — 配置项导出

异步导出配置项数据。

方法	路径	说明
POST	`/ci-export/list`	提交导出任务
GET	`/ci-export/{jobId}/status`	查询导出任务状态

导出为异步操作。提交后返回 jobId，通过轮询状态接口获取进度和下载链接。

Dashboard — 仪表盘管理

管理仪表盘及其分组。

仪表盘 API 支持 CRUD 操作、分组管理、导入导出等功能。系统预置的仪表盘带有保护标记，不可编辑或删除。

Swagger 文档

系统内置了 Swagger UI，部署后可在导航菜单中找到 API 文档入口，直接在浏览器中查看完整的 API 规范、请求示例和在线调试。

基础约定​

URL 结构​

HTTP 方法语义​

请求头​

认证​

获取令牌​

使用令牌​

统一响应格式​

成功响应​

错误响应​

错误码结构​

错误类型​

查询参数​

API 模块概览​

Class Model — 配置项类型管理​

Datain — 数据写入​

TQL Query — 拓扑查询​

Query Definition — 查询定义管理​

CI History — 配置项变更历史​

Relation History — 关系变更历史​

CI Export — 配置项导出​

Dashboard — 仪表盘管理​

Swagger 文档​