Skip to content

Latest commit

 

History

History
751 lines (671 loc) · 24.5 KB

wecmdb_api_guide.md

File metadata and controls

751 lines (671 loc) · 24.5 KB

CMDB API V2

提供统一接口定义,为使用者提供清晰明了的使用方法

API 操作资源 (Resources):

枚举

配置

权限

其他

API 常规操作 (CRUD):

  • 新增 (Create), 新增一个或多个资源
  • 查询 (Retrieve),查询一个或多个资源,可自定义过滤及排序条件
  • 更新 (Update), 更新一个或多个资源
  • 删除 (Delete), 删除一个或多个资源

API 特殊操作:

API 概览及实例:

枚举类别 - EnumCatType

[POST] /api/v2/enum/catTypes/create

新增枚举类别

输入参数:
参数名称 类型 必选 描述
Array Array of EnumCatTypeDto 枚举类别实体列表,不包含资源唯一ID
输出参数:
参数名称 类型 描述
statusCode string 状态码 - OK: 成功, ERROR: 失败,ERR_INVALID_ARGUMENT: 无效参数错误,ERR_INVALID_CHANGE: 批量处理错误
data Array of EnumCatTypeDto 枚举类别实体列表,包含资源唯一ID
示例:

正常输入:

[
  {
    "callbackId":"123456",
    "catTypeName": "system_design",
    "ciTypeId": 1,
    "description": "系统设计私有枚举类别",
    "type": 3
  }
]

正常输出:

{
  "statusCode": "OK",
  "data": [
    {
      "callbackId": "123456",
      "catTypeName": "system_design",
      "ciTypeId": 1,
      "description": "系统设计私有枚举类别",
      "type": 3,
      "catTypeId": 47
    }
  ]
}

无效输入:

[
  {
    "callbackId":"123456",
    "catTypeName": "system_design",
    "ciTypeId": 1,
    "description": "系统设计私有枚举类别",
    "type": 3
  }
]

异常输出:

{
  "statusCode": "ERR_BATCH_CHANGE",
  "statusMessage": "Fail to create [1] records, detail error in the data block",
  "data": [
    {
      "callbackId": "123456",
      "errorMessage": "Fail to create record with callbackId = [123456], error = [Duplicate cat type name [system_design] found, not allow to add/update.]"
    }
  ]
}

/api/v2/enum/catTypes/retrieve

查询枚举类别

输入参数:
参数名称 类型 必选 描述
request QueryRequest 请求参数对象
输出参数:
参数名称 类型 描述
data PageInfo 分页信息
contents Array of catTypeDto 枚举类别实体列表
示例:

正常输入:

{
  "filterRs": "and",
  "filters": [
    {
      "name": "catTypeName",
      "operator": "eq",
      "value": "sys"
    }
  ]
}

正常输出:

{
  "statusCode": "OK",
  "data": {
    "pageInfo": {
      "startIndex": 0,
      "pageSize": 10000,
      "totalRows": 1
    },
    "contents": [
      {
        "catTypeId": 1,
        "catTypeName": "sys",
        "type": 1,
        "cats": []
      }
    ]
  }
}

无效输入:

{
  "filterRs": "and",
  "filters": [
    {
      "name": "invalidFilterName",
      "operator": "eq",
      "value": "sys"
    }
  ]
}

异常输出:

{
  "statusCode": "ERR_INVALID_ARGUMENT",
  "statusMessage": "Can not find out field [invalidFilterName] for domain ."
}

/api/v2/enum/catTypes/update

更新枚举类别

输入参数:
参数名称 类型 必选 描述
Array Array of EnumCatTypeDto 枚举类别实体列表,必须包含资源唯一ID
输出参数:
参数名称 类型 描述
statusCode string 状态码 - OK: 成功, ERROR: 失败,ERR_INVALID_ARGUMENT: 无效参数错误,ERR_INVALID_CHANGE: 批量处理错误
data Array of EnumCatTypeDto 枚举类别实体列表
示例:

正常输入:

[
  {
    "callbackId":"123456",
    "catTypeId": 47,
    "catTypeName": "system_design",
    "ciTypeId": 1,
    "description": "系统设计私有枚举类别",
    "type": 3
  }
]

正常输出:

{
  "statusCode": "OK",
  "data": [
    {
      "callbackId": "123456",
      "catTypeName": "system_design",
      "ciTypeId": 1,
      "description": "系统设计私有枚举类别",
      "type": 3,
      "catTypeId": 47,
      "cats":[]
    }
  ]
}

无效输入:

[
  {
    "callbackId":"123456",
    "catTypeName": "system_design",
    "ciTypeId": 1,
    "description": "系统设计私有枚举类别",
    "type": 3
  }
]

异常输出:

{
  "statusCode": "ERR_BATCH_CHANGE",
  "statusMessage": "Fail to update [1] records, detail error in the data block",
  "data": [
    {
      "callbackId": "123456",
      "errorMessage": "Fail to update record with callbackId = [123456], error = [Field 'catTypeId' is required.]"
    }
  ]
}

/api/v2/enum/catTypes/delete

删除枚举类别

输入参数:
参数名称 类型 必选 描述
Array Array of integer 资源唯一ID列表
输出参数:
参数名称 类型 描述
data string 成功信息"Success"
statusMessage string 异常信息,无异常则不返回该属性
示例:

正常输入:

[
  47
]

正常输出:

{
  "statusCode": "OK",
  "data": "Success"
}

无效输入:

[
  9999
]

异常输出:

{
  "statusCode": "ERROR",
  "statusMessage": "Unable to find com.webank.cmdb.domain.AdmBasekeyCatType with id 9999"
}

枚举目录 - EnumCat

[POST] /api/v2/enum/cats/create

新增枚举目录

输入参数:
参数名称 类型 必选 描述
Array Array of EnumCatDto 枚举目录实体列表,不包含资源唯一ID
输出参数:
参数名称 类型 描述
statusCode string 状态码 - OK: 成功, ERROR: 失败,ERR_INVALID_ARGUMENT: 无效参数错误,ERR_INVALID_CHANGE: 批量处理错误
data Array of EnumCatDto 枚举目录实体列表,包含资源唯一ID

/api/v2/enum/cats/retrieve

查询枚举目录

输入参数:
参数名称 类型 必选 描述
request QueryRequest 请求参数对象
输出参数:
参数名称 类型 描述
data PageInfo 分页信息
contents Array of EnumCatDto 枚举目录实体列表

/api/v2/enum/cats/update

更新枚举目录

输入参数:
参数名称 类型 必选 描述
Array Array of EnumCatDto 枚举目录实体列表,必须包含资源唯一ID
输出参数:
参数名称 类型 描述
statusCode string 状态码 - OK: 成功, ERROR: 失败,ERR_INVALID_ARGUMENT: 无效参数错误,ERR_INVALID_CHANGE: 批量处理错误
data Array of EnumCatDto 枚举目录实体列表

/api/v2/enum/cats/delete

删除枚举目录

输入参数:
参数名称 类型 必选 描述
Array Array of integer 资源唯一ID列表
输出参数:
参数名称 类型 描述
data string 成功信息"Success"
statusMessage string 异常信息,无异常则不返回该属性

枚举名称/值 - EnumCode

[POST] /api/v2/enum/codes/create

新增枚举名称/值

输入参数:
参数名称 类型 必选 描述
Array Array of EnumCodeDto 枚举名称/值实体列表,不包含资源唯一ID
输出参数:
参数名称 类型 描述
statusCode string 状态码 - OK: 成功, ERROR: 失败,ERR_INVALID_ARGUMENT: 无效参数错误,ERR_INVALID_CHANGE: 批量处理错误
data Array of EnumCodeDto 枚举名称/值实体列表,包含资源唯一ID

/api/v2/enum/codes/retrieve

查询枚举名称/值

输入参数:
参数名称 类型 必选 描述
request QueryRequest 请求参数对象
输出参数:
参数名称 类型 描述
data PageInfo 分页信息
contents Array of EnumCodeDto 枚举名称/值实体列表

/api/v2/enum/codes/update

更新枚举名称/值

输入参数:
参数名称 类型 必选 描述
Array Array of EnumCodeDto 枚举名称/值实体列表,必须包含资源唯一ID
输出参数:
参数名称 类型 描述
statusCode string 状态码 - OK: 成功, ERROR: 失败,ERR_INVALID_ARGUMENT: 无效参数错误,ERR_INVALID_CHANGE: 批量处理错误
data Array of EnumCodeDto 枚举名称/值实体列表

/api/v2/enum/codes/delete

删除枚举名称/值

输入参数:
参数名称 类型 必选 描述
Array Array of integer 资源唯一ID列表
输出参数:
参数名称 类型 描述
data string 成功信息"Success"
statusMessage string 异常信息,无异常则不返回该属性

配置项类型 - CiType

[POST] /api/v2/ciTypes/create

新增配置项类型

输入参数:
参数名称 类型 必选 描述
Array Array of CiTypeDto 配置项类型实体列表,不包含资源唯一ID
输出参数:
参数名称 类型 描述
statusCode string 状态码 - OK: 成功, ERROR: 失败,ERR_INVALID_ARGUMENT: 无效参数错误,ERR_INVALID_CHANGE: 批量处理错误
data Array of CiTypeDto 配置项类型实体列表,包含资源唯一ID

[POST] /api/v2/ciTypes/retrieve

查询配置项类型

输入参数:
参数名称 类型 必选 描述
request QueryRequest 请求参数对象
输出参数:
参数名称 类型 描述
data PageInfo 分页信息
contents Array of CiTypeDto 配置项类型实体列表

[POST] /api/v2/ciTypes/update

更新配置项类型

输入参数:
参数名称 类型 必选 描述
Array Array of CiTypeDto 配置项类型实体列表,必须包含资源唯一ID
输出参数:
参数名称 类型 描述
statusCode string 状态码 - OK: 成功, ERROR: 失败,ERR_INVALID_ARGUMENT: 无效参数错误,ERR_INVALID_CHANGE: 批量处理错误
data Array of CiTypeDto 配置项类型实体列表

[POST] /api/v2/ciTypes/delete

删除配置项类型

输入参数:
参数名称 类型 必选 描述
Array Array of integer 资源唯一ID列表
输出参数:
参数名称 类型 描述
data string 成功信息"Success"
statusMessage string 异常信息,无异常则不返回该属性

配置项类型属性 - CiTypeAttr

[POST] /api/v2/ciTypeAttrs/create

新增配置项类型属性

输入参数:
参数名称 类型 必选 描述
Array Array of CiTypeAttrDto 配置项类型属性实体列表,不包含资源唯一ID
输出参数:
参数名称 类型 描述
statusCode string 状态码 - OK: 成功, ERROR: 失败,ERR_INVALID_ARGUMENT: 无效参数错误,ERR_INVALID_CHANGE: 批量处理错误
data Array of CiTypeAttrDto 配置项类型属性实体列表,包含资源唯一ID

[POST] /api/v2/ciTypeAttrs/retrieve

查询配置项类型属性

输入参数:
参数名称 类型 必选 描述
request QueryRequest 请求参数对象
输出参数:
参数名称 类型 描述
data PageInfo 分页信息
contents Array of CiTypeAttrDto 配置项类型属性实体列表

[POST] /api/v2/ciTypeAttrs/update

更新配置项类型属性

输入参数:
参数名称 类型 必选 描述
Array Array of CiTypeAttrDto 配置项类型属性实体列表,必须包含资源唯一ID
输出参数:
参数名称 类型 描述
statusCode string 状态码 - OK: 成功, ERROR: 失败,ERR_INVALID_ARGUMENT: 无效参数错误,ERR_INVALID_CHANGE: 批量处理错误
data Array of CiTypeAttrDto 配置项类型属性实体列表

[POST] /api/v2/ciTypeAttrs/delete

删除配置项类型属性

输入参数:
参数名称 类型 必选 描述
Array Array of integer 资源唯一ID列表
输出参数:
参数名称 类型 描述
data string 成功信息"Success"
statusMessage string 异常信息,无异常则不返回该属性

配置项 - CI

[POST] /api/v2/ci/{ciTypeId}/create

新增配置项

输入参数:
参数名称 类型 必选 描述
ciTypeId integer URL path里的ciTypeId为配置项类型ID, 即为该配置项类型新增一个或多个配置项
Array Array of Map<key,value> 配置项实体列表,不包含资源唯一ID.
输出参数:
参数名称 类型 描述
statusCode string 状态码 - OK: 成功, ERROR: 失败,ERR_INVALID_ARGUMENT: 无效参数错误,ERR_INVALID_CHANGE: 批量处理错误
data Array of Map<key,value> 配置项实体列表,包含资源唯一ID

[POST] /api/v2/ci/{ciTypeId}/retrieve

查询配置项

输入参数:
参数名称 类型 必选 描述
ciTypeId integer URL path里的ciTypeId为配置项类型ID, 即为该配置项类型新增一个或多个配置项
request QueryRequest 请求参数对象
输出参数:
参数名称 类型 描述
data PageInfo 分页信息
contents Array of Map<key,value>) 配置项实体列表

[POST] /api/v2/ci/{ciTypeId}/update

更新配置项

输入参数:
参数名称 类型 必选 描述
ciTypeId integer URL path里的ciTypeId为配置项类型ID, 即为该配置项类型新增一个或多个配置项
Array Array of Map<key,value> 配置项实体列表,必须包含资源唯一ID
输出参数:
参数名称 类型 描述
statusCode string 状态码 - OK: 成功, ERROR: 失败,ERR_INVALID_ARGUMENT: 无效参数错误,ERR_INVALID_CHANGE: 批量处理错误
data Array of Map<key,value> 配置项实体列表

[POST] /api/v2/ci/{ciTypeId}/delete

删除配置项

输入参数:
参数名称 类型 必选 描述
ciTypeId integer URL path里的ciTypeId为配置项类型ID, 即为该配置项类型新增一个或多个配置项
Array Array of integer 资源唯一ID列表
输出参数:
参数名称 类型 描述
data string 成功信息"Success"
statusMessage string 异常信息,无异常则不返回该属性

用户 - User

TO DO

角色 - Role

TO DO

用户授权 - Role_User

TO DO

配置项授权 - Role_CiType

TO DO

配置项属性授权 - Role_CiTypeAttr

TO DO

配置项属性权限生效条件 - Role_CiTypeAttr_Conditon

TO DO

综合查询 - IntQuery

TO DO

图标 - Image

TO DO

常量 - Constants

TO DO

配置项类型及属性的状态变化操作 - Apply

[POST] /api/v2/ciTypes/applyAll

创建所有待创建(状态为:notCreated)的配置项类型及其属性所对应的物理表及属性列

输入参数:无
输出参数:
参数名称 类型 描述
statusCode string 状态码 - OK: 成功, ERROR: 失败,ERR_INVALID_ARGUMENT: 无效参数错误,ERR_INVALID_CHANGE: 批量处理错误
statusMessage string 异常信息,无异常则不返回该属性

[POST] /api/v2/ciTypes/apply

创建指定的配置项类型及其属性所对应的物理表及属性列

输入参数:
参数名称 类型 必选 描述
Array Array of integer 配置项类型ID列表,见CiTypeDto.ciTypeId
输出参数:
参数名称 类型 描述
statusCode string 状态码 - OK: 成功, ERROR: 失败,ERR_INVALID_ARGUMENT: 无效参数错误,ERR_INVALID_CHANGE: 批量处理错误
statusMessage string 异常信息,无异常则不返回该属性

[POST] /api/v2/ciTypeAttrs/apply

创建指定的配置项类型属性所对应的物理表的属性列

输入参数:
参数名称 类型 必选 描述
Array Array of integer 配置项类型属性ID列表,见CiTypeAttrDto.ciTypeAttrId
输出参数:
参数名称 类型 描述
statusCode string 状态码 - OK: 成功, ERROR: 失败,ERR_INVALID_ARGUMENT: 无效参数错误,ERR_INVALID_CHANGE: 批量处理错误
statusMessage string 异常信息,无异常则不返回该属性

配置项状态变化操作 - CI_State_Operate

[POST] /api/v2/ci/state/operate

配置项状态变化操作,根据配置项类型所对应的状态机允许的状态进行变化操作

输入参数:
参数名称 类型 必选 描述
Array Array of integer 配置项类型ID列表,见CiTypeDto.ciTypeId
operation string 操作名称 - insert: 插入, delete: 删除, update: 更新,discard: 废弃, confirm: 确认, startup: 启动, stop: 停止
注:状态机不同,所对应的操作集合会不同
输出参数:
参数名称 类型 描述
statusCode string 状态码 - OK: 成功, ERROR: 失败,ERR_INVALID_ARGUMENT: 无效参数错误,ERR_INVALID_CHANGE: 批量处理错误
data Array of Map<key,value> 配置项实体列表

数据结构:

1. 公共数据结构

QueryRequest

名称 类型 必选 描述
dialect/data object 方言数据,也称为额外数据
dialect/showCiHistory boolean 是否请求历史数据, 默认:false
filterRs string 默认:and
过滤器的关系 -- and: 与关系, or: 或关系
filters Array of Filter 过滤器
groupsBys Array of string 分组查询
Pageable Pageable 每页信息
paging boolean 请求结果是否要分页
refResources Array of string 跨资源名称列表,为跨资源查询之用
resultsColumns Array of string 请求结果属性列表
sorting/asc boolean 是否升序排列,默认:true
sorting/field string 排序属性名

Filter

名称 类型 必选 描述
name string 资源属性名
operator string 过滤操作符,目前支持:in/contains/eq/gt/lt/ne/notNull/null
value object 根据操作符变化,如operator为eq, value即要求是对象, 如operator为contains, value即要求为列表

PageInfo

名称 类型 必选 描述
pageSize integer 每页显示记录行数
startIndex integer 开始页码索引
totalRows integer 总共记录数

Pageable

名称 类型 必选 描述
pageSize integer 每页显示记录行数
startIndex integer 开始页码索引

2. 实体数据结构

EnumCatTypeDto - 枚举类别

名称 类型 必选 描述
callbackId string 入参唯一索引ID, 作为出参提取对应数据的依据
errorMessage string 出参异常信息,无异常则不返回该属性
catTypeId integer 实体ID, 新增时由系统产生,更新和删除时必选
catTypeName string 枚举类别名称
ciTypeId integer 所属配置项ID, 即该配置项的私有枚举类别
type integer 枚举类别的类型 - 1:系统枚举 2:公共枚举 3:私有枚举
description string 枚举类别的描述

EnumCat - 枚举目录

名称 类型 必选 描述
callbackId string 入参唯一索引ID, 作为出参提取对应数据的依据
errorMessage string 出参异常信息,无异常则不返回该属性
catId integer 实体ID, 新增时由系统产生,更新和删除时必选
catName string 枚举目录名称
catTypeId integer 所属枚举类别ID, 见EnumCatTypeDto
groupTypeId integer 枚举目录组,也称父枚举目录ID
description string 枚举目录的描述

EnumCodeDto - 枚举名称/值

名称 类型 必选 描述
callbackId string 入参唯一索引ID, 作为出参提取对应数据的依据
errorMessage string 出参异常信息,无异常则不返回该属性
codeId integer 实体ID, 新增时由系统产生,更新和删除时必选
catId integer 所属枚举目录ID, 见EnumCatDto
code string 枚举名称
value string 枚举值
groupCodeId integer 枚举组,也称父枚举ID
codeDescription string 枚举的描述
seqNo integer 系统产生并维护
status string 默认:active, 枚举状态 - active: 可用, inactive: 不可用

CiTypeDto - 配置项类型

名称 类型 必选 描述
callbackId string 入参唯一索引ID, 作为出参提取对应数据的依据
errorMessage string 出参异常信息,无异常则不返回该属性
ciTypeId integer 实体ID, 新增时由系统产生,更新和删除时必选
name string 名称
tableName string 对应的数据库表名
status string 默认:notCreated, 配置项状态 - notCreated: 待创建,created: 已创建, dirty: 已创建后更改, decommissioned: 丢弃
catalogId integer 目录ID
seqNo integer 系统产生及维护, 同一层上的排序序列号
layerId integer Y轴的层级序列号
zoomLevelId integer Z轴的层级序列号
imageFileId integer 显示图片ID
description string 描述

CiTypeAttrDto - 配置项类型属性

名称 类型 必选 描述
callbackId string 入参唯一索引ID, 作为出参提取对应数据的依据
errorMessage string 出参异常信息,无异常则不返回该属性
ciTypeAttrId integer 实体ID, 新增时由系统产生,更新和删除时必选
ciTypeId integer 属性所属配置项类型ID,见CiTypeDto
name string 属性名称
inputType string 属性可接受输入数据类型 - text, date, textArea, select, multiSelect, ref, multiRef, number, orchestration_multi_ref, orchestration_ref
propertyName string 属性对应的数据库表列名称, 只支持大小写字母,数据和下划线,而且以必须小写开头
propertyType string 属性对应的数据库表列数据类型
length string 属性对应的数据库表列数据允许的长度
referenceId integer 属性所引用的配置项类型ID, 见CiTypeDto 或 枚举目录ID, 见EnumCatDto
referenceName string 引用关系命名
referenceType integer 引用关系的类型,即对应的枚举目录ID
filterRule string 过滤规则,即当该属性为引用或枚举的时候,使用该设定的规则过滤所引用的数据
searchSeqno integer 搜索排序序列号
displaySeqNo integer 展示排序
autoFillRule string 自动填充规则
status string 默认:notCreated, 配置项状态 - notCreated: 待创建,created: 已创建, dirty: 已创建后更改, decommissioned: 丢弃
isDisplayed boolean 是否展示
isEditable boolean 是否可编辑
isHidden boolean 是否隐藏
isNullable boolean 是否允许保存空值
isRefreshable boolean 是否允许刷新
isSystem boolean 是否系统属性
isUnique boolean 是否唯一,即该属性值不允许保存重复值
isAccessControlled boolean 是否启用权限控制
isAuto boolean 是否自动填充该属性值,即根据autoFillRule属性所设定的规则进行填充
description string 配置项类型属性的描述