7x31/cmdb
1
0
Fork 0
mirror of https://github.com/veops/cmdb.git synced 2025-08-06 15:20:21 +08:00
Code Issues Packages Projects Releases Wiki Activity

add docs

Browse Source
This commit is contained in:
pycook
2019-10-16 08:29:47 +08:00
parent 56baa2bedc
commit 872d9baa59
3 changed files with 1 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

636
docs/cmdb_api.md Normal file
View File

@@ -0,0 +1,636 @@
# CMDB API文档
## 状态返回码的定义
* 200：成功
* 400：失败
* 401：未认证
* 403：no permission
* 404：not found
* 500：服务器未知错误
## 用户接口
### CI搜索接口
* GET `/api/v0.1/ci/s`
* 参数
* `string:_type` 搜索的ci_type，多个用分号隔开, 例如: _type:(server;vservser)
* `string:q` 搜索表达式, 例如`q=hostname:cmdb*`
* `string:fl` 返回字段(id, attr_name, attr_alias均可)，英文半角逗号分隔
* `string:ret_key` 返回字段类型 `Enum("id", "name", "alias")` 默认 `name`
* `count` 指定一次返回CI数
* `facet` 属性字段，逗号分隔，返回属性字段对应的所有值
* 搜索表达式：
* 简单的字符串
* `attribute:value` 指定属性搜索， `attribute`可以是`id`,`attr_name`和`attr_alias`
* 以上的组合，逗号分隔
* 组合查询支持
* `AND`关系-`默认关系`
* `OR`关系 - eg.`-hostname:cmdb*`、
* `NOT`关系-属性字段前加`~`eg. `~hostname:cmdb*`
* `IN`查询. eg. `hostname:(cmdb*;cmdb-web*)` 小括号, 分号分隔
* `RANGE`查询. eg. `hostname:[cmdb* _TO_ cmdb-web*]` `_TO_`分隔
* `COMPARISON`查询. eg. `cpu_core_num:>5` 支持`>, >=, <, <=`
## api key 认证
每个用户会自动生成一个 `api key` 和 一个`secret`, 通过API接口使用的时候，需要提供一个参数 `_key`值为您的`api key`， 以及参数`_secret`值为除`_key`以外的参数，按照**参数名的字典序**排列，并连接到`url path` + `secret`之后的`sha1`**十六进制**值。
## 管理接口
### Attribute管理接口
* GET `/api/v0.1/attributes` 列出所有属性
* param
* `string:q` 属性名称或者别名，允许为空
* return
```
{
"numfound": 1,
"attributes": [
{
"attr_name": "idc",
"is_choice": true,
"choice_value": ["南汇", "欧阳路"],
"attr_id": 1,
"is_multivalue": false,
"attr_alias": "IDC",
"value_type": "text",
"is_uniq": false
}
}
```
* error 无
* GET `/api/v0.1/attributes/<string:attr_name>`、 `/api/v0.1/attributes/<int:attr_id>` 根据属性名称、别名或ID获取属性
* param
* `string:attr_name` 属性名称或别名
* `int:attr_id` 属性ID
* `attr_id`和`attr_name`选其一
* return
```
{
"attribute": {
"attr_name": "idc",
"is_choice": true,
"choice_value": ["南汇", "欧阳路"],
"attr_id": 1,
"is_multivalue": false,
"attr_alias": "IDC",
"value_type": "text",
"is_uniq": false
},
}
```
* error
* `404` 找不到属性
* POST `/api/v0.1/attributes` 增加新的属性
* param
* `string:attr_name` 属性名称
* `string:attr_alias` 属性别名，可为空，为空时等于`attr_name`
* `boolean:choice_value` 若属性有预定义值, 则不能为空
* `boolean:is_multivalue` 属性是否允许多值，默认`False`
* `boolean:is_uniq` 属性是否唯一，默认`False`
* `string:value_type` 属性值类型， `Enum("text", "int", "float", "date")`, 默认`text`
* return
```
{
"attr_id":1
}
```
* error
* `500` 属性已存在
* `500` 属性增加失败
* PUT `/api/v0.1/attributes/<int:attr_id>` 修改属性
* param
* `string:attr_name` 属性名称
* `string:attr_alias` 属性别名，可为空，为空时等于`attr_name`
* `boolean:choice_value` 若属性有预定义值, 则不能为空
* `boolean:is_multivalue` 属性是否允许多值，值为0或者1，默认`False`
* `boolean:is_uniq` 属性是否唯一，值为0或者1，默认`False`
* `string:value_type` 属性值类型， `Enum("text", "int", "float", "date")`, 默认`text`
* return
```
{
"attr_id":1
}
```
* error
* `500` 属性已存在
* `500` 属性增加失败
* DELETE `/api/v0.1/attributes/<int:attr_id>` 根据ID删除属性
* param
* `int:attr_id` 属性ID
* return
```
{
"message":"attribute %s deleted" % attr_name
}
```
* error
* `404` 属性不存在
* `500` 删除属性失败
#### CIType属性管理
* GET `/api/v0.1/attributes/citype/<int:type_id>` 根据type_id查询固有属性列表
* return
```
{
"attributes": [
{
"attr_name": "idc",
"is_choice": true,
"choice_value": ["南汇", "欧阳路"],
"attr_id": 1,
"is_multivalue": false,
"attr_alias": "IDC",
"value_type": "text",
"is_uniq": false
},
],
"type_id": 1,
}
```
* POST `/api/v0.1/attributes/citype/<int:type_id>` 根据`attr_id`增加CIType的属性
* param
* `string:attr_id` `,`分隔的`attr_id`
* `int:is_required` 0或者1
* return
```
{
"attributes":[1, 2, 3]
}
```
* error
* `404` CIType不存在
* `404` 属性不存在
* `500` 增加失败
* DELETE `/api/v0.1/attributes/citype/<int:type_id>` 删除CIType的属性
* param
* `string:attr_id` `,`分隔的`attr_id`
* return
```
{
"attributes":[1, 2, 3]
}
```
* error
* `404` CIType不存在
* `404` 属性不存在
* `500` 增加失败
### CIType管理接口
* `/api/v0.1/citypes` 列出所有CI类型
* param `string:type_name` 类型名称，允许为空
* return
```
{
"numfound": 2,
"citypes": [
{
"uniq_key": "sn",
"type_name": "物理机",
"type_id": 1,
"enabled": True,
"icon_url": ""
},
{
"uniq_key": "uuid",
"type_name": "KVM",
"type_id": 2,
"enabled": True,
"icon_url": ""
}
],
}
```
* error 无
* GET `/api/v0.1/citypes/query` 查询CI类型
* param `string:type` 可以是type_id, type_name, type_alias
* return
```
{
"citype": {
"type_name": "software",
"type_id": 4,
"icon_url": "",
"type_alias": "\u8f6f\u4ef6",
"enabled": true,
"uniq_key": 21
}
}
```
* error
* `400` message=输入参数缺失
* `404` message='citype is not found'
* POST `/api/v0.1/citypes` 增加新CIType
* param (下列参数任意一个或多个)
* `string:type_name` CIType名称
* `string:type_alias` 类型别名，可为空
* `int:_id` 唯一属性ID
* `string:unique` 唯一属性名称
* `_id`和`unique`只能二选一
* `icon_url`
* `enabled` 0/1
* return
```
{
"type_id": 2
}
```
* error
* `400` message=输入参数缺失
* `500` message=CIType已存在
* `500` message=唯一属性不存在
* `500` message=唯一属性不是唯一的
* PUT `/api/v0.1/citypes/<int:type_id>` 修改CIType
* param (下列参数任意一个或多个)
* `string:type_name` CIType名称
* `string:type_alias` 类型别名，可为空
* `int:_id` 唯一属性ID
* `string:unique` 唯一属性名称
* `_id`和`unique`只能二选一
* `icon_url`
* `enabled` 0/1
* return
```
{
"type_id": 2
}
```
* error
* `400` message=输入参数缺失
* `500` message=CIType已存在
* `500` message=唯一属性不存在
* `500` message=唯一属性不是唯一的
* GET/POST `/api/v0.1/citypes/enable/<int:type_id>` 修改CIType
* param
* `enabled` 0 or 1
* return
```
{
"type_id": 2
}
```
* error
* `500` 设置失败
* `404` CIType不存在
* DELETE `/api/v0.1/citypes/<int:type_id>` 根据ID删除CIType
* return
```
{
"message":"ci type %s deleted" % type_name
}
```
* error
* `500` 删除失败
* `404` CIType不存在
### CITypeRelation管理接口
* GET `/api/v0.1/cityperelations/types` 列出所有CIType关系类型名
* return
```
{
"relation_types": ["连接", "位置", "附属", "部署"],
}
```
* error 无
* GET `/api/v0.1/cityperelations/<int:parent>/children` 返回所有child id
* return
```
{
"children": [
{
"ctr_id": 1,
"type_name": "project",
"type_id": 2,
"icon_url": "",
"type_alias": "应用",
"enabled": true,
"uniq_key": 3
}
]
}
```
* error 无
* GET `/api/v0.1/cityperelations/<int:child>/parents` 返回parent id
* return
```
{
"parents": [{'parent':1, 'relaltion_type': 'containes', "ctr_id":1}],
}
```
* error 无
* POST `/api/v0.1/cityperelations/<int:parent>/<int:child>` 增加CIType关系
* param
* `string:relation_type` 类型名称
* return
```
{
"ctr_id":1
}
```
* error
* `500` 增加失败
* `404` CIType不存在
* DELETE `/api/v0.1/cityperelations/<int:ctr_id>` 根据`ctr_id`删除CIType关系
* return
```
{
"message":"CIType relation %s deleted" % type
}
```
* error
* `500` 删除失败
* `404` 关系不存在
### CI管理接口
* GET `/api/v0.1/ci/type/<int:type_id>` 查询CIType的所有CI,一次返回25条记录
* param
* `string:fields` 返回属性名、id，逗号隔开
* `string:ret_key` 返回属性key,默认'name',还可是'id', 'alias'
* `int:page` 页码
* return
```
{
"numfound": 1,
"type_id":1,
"page": 1,
"cis": [
{
"ci_type": "KVM",
"_type": 1,
"nic": [
2
],
"hostname": "xxxxxx",
"_unique": "xxxxxx",
"_id": 1
}
]
}
```
* erorr
* `404` CIType不存在
* GET `/api/v0.1/ci/<int:ci_id>` 查询CI
* return
```
{
"ci": {
"ci_type": "KVM",
"_type": 1,
"nic": [2],
"hostname": "xxxxx",
"_unique": "xxxxx",
"_id": 1
},
"ci_id": 1
}
```
* erorr 无
* POST `/api/v0.1/ci` 增加CI
* param
* `string:ci_type` CIType name 或者id
* `string:_no_attribute_policy` 当添加不存在的attribute时的策略， 默认`ignore`
* 其他url参数`k=v`： `k` 为属性名(id或别名亦可)， `v`为对应的值
* 此CIType的`unique`字段必须包含在url参数中
* return
```
{
"ci_id":1,
}
```
* erorr
* `500` 添加失败
* PUT `/api/v0.1/ci` 修改CI
* param
* `string:ci_type` CIType name 或者id
* `string:_no_attribute_policy` 当添加不存在的attribute时的策略， 默认`ignore`
* 其他url参数`k=v`： `k` 为属性名(id或别名亦可)， `v`为对应的值
* 此CIType的`unique`字段必须包含在url参数中
* return
```
{
"ci_id":1,
}
```
* erorr
* `500` 添加失败
* DELETE `/api/v0.1/ci/<int:ci_id>` 删除ci
* return
```
{
"message":"ok",
}
```
* erorr
* `500` 删除失败
## CIRelaiton管理接口
* GET `/api/v0.1/cirelations/types` 列出所有CI关系类型名
* return
```
{
"relation_types": ["connect", "install", "deploy", "contain"],
}
```
* error 无
* GET `/api/v0.1/cirelations/<int:first_ci>/second_cis` 返回所有second id
* return
```
{
"numfound": 1,
"second_cis": [
{
"ci_type": "project",
"ci_type_alias": "应用",
"_type": 2,
"_id": 18,
"project_name": "cmdb-api"
}
]
}
```
* error 无
* GET `/api/v0.1/cirelations/<int:second_ci>/first_cis` 返回first ci id
* return
```
{
"first_cis": [
{
"ci_type": "project",
"ci_type_alias": "应用",
"_type": 2,
"_id": 18,
"project_name": "cmdb-api"
}
],
"numfound": 1
}
```
* error 无
* POST `/api/v0.1/cirelations/<int:first_ci>/<int:second_ci>` 增加CI关系
* param
* `int: more` more实例
* `string:relation_type` 类型名称
* return
```
{
"cr_id":1
}
```
* error
* `500` 增加失败
* `404` CI不存在
* DELETE `/api/v0.1/cirelations/delete/<int:cr_id>` 根据`cr_id`删除CI关系
* return
```
{
"message":"CIType relation %s deleted" % type
}
```
* error
* `500` 删除失败
* `404` 关系不存在
## 历史记录管理接口
* GET `/api/v0.1/history/record` 查询历史记录
* param
* `int: page`
* `string: username` 变更用户
* `string: start` 变更开始时间
* `string: end` 变更结束时间
* return
```
{
"username": "",
"start": "2014-12-31 14:57:43",
"end": "2015-01-07 14:57:43",
"records": [
{
"origin": null,
"attr_history": [],
"timestamp": "2015-01-01 22:12:39",
"reason": null,
"rel_history": {
"add": 1
},
"user": 1,
"record_id": 1234,
"ticket_id": null
}
]
}
```
* error 无
* GET `/api/v0.1/history/<int:record_id>` 历史记录详情
* return
```
{
"username": "pycook",
"timestamp": "2015-01-02 20:21:16",
"rel_history": {
"add": [
[
123,
"deploy",
234
]
],
"delete": []
},
"attr_history": {}
}
```
* error
* `404` 该记录不存在

99
docs/cmdb_query_api.md Normal file
View File

@@ -0,0 +1,99 @@
# CMDB查询 API文档
## 用户接口
### CI通用搜索接口
* GET `/api/v0.1/ci/s`
* 参数
* `string:_type` 搜索的ci_type，多个用分号隔开, 例如: _type:(docker;kvm)
* `string:q` 搜索表达式, 例如`q=hostname:cmdb*`
* `string:fl` 返回字段(id, attr_name, attr_alias均可)，英文半角逗号分隔
* `string:ret_key` 返回字段类型 `Enum("id", "name", "alias")` 默认 `name`
* `count` 指定一次返回CI数
* `facet` 属性字段，逗号分隔，返回属性字段对应的所有值
* `wt` 返回的数据格式，默认为`json`, 可选参数为`xml`
* 搜索表达式：
* 简单的字符串
* `attribute:value` 指定属性搜索， `attribute`可以是`id`,`attr_name`和`attr_alias`
* 以上的组合，逗号分隔
* 组合查询支持
* `AND`关系-`默认关系`
* `OR`关系 - eg.`-hostname:cmdb*`、
* `NOT`关系-属性字段前加`~`eg. `~hostname:cmdb*`
* `IN`查询. eg. `hostname:(cmdb*;cmdb-web*)` 小括号, 分号分隔
* `RANGE`查询. eg. `hostname:[cmdb* _TO_ cmdb-web*]` `_TO_`分隔
* `COMPARISON`查询. eg. `cpu_count:>5` 支持`>, >=, <, <=`
* 返回结果
* 搜索表达式 `/api/v0.1/ci/s?q=_type:kvm,status:在线,idc:南汇,private_ip:10.1.1.1*&page=1&fl=hostname,private_ip&facet=private_ip&count=1`
* 返回数据（默认json）
```
{
facet: {
private_ip: [
[
"10.1.1.11",
1,
"private_ip"
],
[
"10.1.1.12",
1,
"private_ip"
],
[
"10.1.1.13",
1,
"private_ip"
]
]
},
total: 1,
numfound: 3,
result: [
{
ci_type: "kvm",
_type: 8,
_id: 3213,
hostname: "xxx11",
private_ip: [
"10.1.1.11"
]
},
{
ci_type: "kvm",
_type: 8,
_id: 123232,
hostname: "xxx12",
private_ip: [
"10.1.1.12"
]
},
{
ci_type: "kvm",
_type: 8,
_id: 123513,
hostname: "xxx13",
private_ip: [
"10.1.1.13"
]
}
],
counter: {
kvm: 3
},
page: 1
}
```
### CI专用搜索接口
##### 根据需求实现