# 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/`、 `/api/v0.1/attributes/` 根据属性名称、别名或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/` 修改属性 * 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/` 根据ID删除属性 * param * `int:attr_id` 属性ID * return ``` { "message":"attribute %s deleted" % attr_name } ``` * error * `404` 属性不存在 * `500` 删除属性失败 #### CIType属性管理 * GET `/api/v0.1/attributes/citype/` 根据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/` 根据`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/` 删除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/` 修改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/` 修改CIType * param * `enabled` 0 or 1 * return ``` { "type_id": 2 } ``` * error * `500` 设置失败 * `404` CIType不存在 * DELETE `/api/v0.1/citypes/` 根据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//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//parents` 返回parent id * return ``` { "parents": [{'parent':1, 'relaltion_type': 'containes', "ctr_id":1}], } ``` * error 无 * POST `/api/v0.1/cityperelations//` 增加CIType关系 * param * `string:relation_type` 类型名称 * return ``` { "ctr_id":1 } ``` * error * `500` 增加失败 * `404` CIType不存在 * DELETE `/api/v0.1/cityperelations/` 根据`ctr_id`删除CIType关系 * return ``` { "message":"CIType relation %s deleted" % type } ``` * error * `500` 删除失败 * `404` 关系不存在 ### CI管理接口 * GET `/api/v0.1/ci/type/` 查询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/` 查询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/` 删除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//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//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//` 增加CI关系 * param * `int: more` more实例 * `string:relation_type` 类型名称 * return ``` { "cr_id":1 } ``` * error * `500` 增加失败 * `404` CI不存在 * DELETE `/api/v0.1/cirelations/delete/` 根据`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/` 历史记录详情 * return ``` { "username": "pycook", "timestamp": "2015-01-02 20:21:16", "rel_history": { "add": [ [ 123, "deploy", 234 ] ], "delete": [] }, "attr_history": {} } ``` * error * `404` 该记录不存在