7x31/cmdb
1
0
Fork 0
mirror of https://github.com/veops/cmdb.git synced 2025-11-02 20:36:09 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
e73810b456c888cb2dd568174df206e2c006e8dc
cmdb/docs/cmdb_api.md
pycook 872d9baa59 add docs
2019-10-24 20:43:51 +08:00

15 KiB
Raw Blame History

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 该记录不存在