CMDB

开发人员指南 > 开发人员指南 > Codebeamer 开发 > Codebeamer 扩展和插件开发汇总 > REST API (v1) > CMDB

CMDB

CMDB 类别具有以下形式的 URI："/category/{id}" 或 "{projectURI}/category/{name}"，其中 {id} 为内部唯一类别 ID/编号，{name} 为类别名称，该类别名称仅在项目中唯一。

获取类别类型架构

GET /category/type/schema

获取可用的类别类型

GET /category/types

所有类别类型均已预定义。不能创建、更新或删除类别类型。

获取类别类型定义

GET /category/type/{categoryTypeIdOrName}

获取不可变的类别类型定义。

获取可用的类别权限

GET /category/permissions

所有类别权限均已预定义。不能创建、更新或删除类别权限。

获取类别权限

GET /category/permission/{permissionIdOrName}

获取不可变的类别权限定义。

获取类别架构

GET /category/schema

创建新类别

POST /category

请求正文必须包含具有所有必需特性的有效类别对象，例如：

{
"project": "/project/1",
"type": "/category/type/Test case",
"name": "Test Cases",
"keyName": "TESTCASE",
"description": "Test cases to validate and verify the product",
"descFormat": "Plain",
"workflow": true
}

创建新类别作为另一个类别的复制

POST {categoryURI}/clone

请求正文必须包含与上述相同的有效类别对象，但新类别将使用指定的类别作为模板，并继承类别架构和权限。

更新类别设置

PUT /category

请求正文必须包含要更新的类别 URI 和特性，例如，要禁用类别的有限状态机：

{
"uri": "/project/1/category/Test Cases",
"workflow": false
}

删除类别

DELETE {categoryURI}

获取类别定义

GET {categoryURI}

获取类别的基本项架构

GET {categoryURI}/schema

注意：不能通过 REST API 配置类别的项架构。

获取类别项特性的架构

GET {categoryURI}/field/{fieldIdOrName}

注意：不能通过 REST API 配置类别项字段的架构。

获取每个角色的所有已授权类别权限

GET {categoryURI}/roles/permissions

获取授予特定角色的类别权限

GET {categoryURI}{roleURI}/permissions

GET {roleURI}{categoryURI}/permissions

设置特定角色的类别权限

PUT {categoryURI}{roleURI}/permissions

PUT {roleURI}{categoryURI}/permissions

请求正文必须包含要授予角色的类别权限数组 (传递权限 ID 或权限名称即可)，例如：

[
"Issue - View Any",
"Issue - View Comments/Attachments"
]

移除特定角色的所有类别权限

DELETE {categoryURI}{roleURI}/permissions

DELETE {roleURI}{categoryURI}/permissions

获取用户对某个类别的有效权限

GET {categoryURI}{userURI}/permissions

GET {userURI}{categoryURI}/permissions

获取项目中所有类别的列表

GET {projectURI}/categories[?query]

参数	类型	必需	含义
type	字符串	否	以逗号分隔的类别类型 (ID 或名称) 列表，仅显示这些类型的类别。
hidden	布尔型	否	如果设置为 true，还会显示隐藏的类别。默认值为 false。
deleted	布尔型	否	如果设置为 true，还会显示移除的类别。默认值为 false。

例如，显示测试项目中的所有“测试用例”和“测试集”类别：

GET https://hostname/cb/rest/project/1/categories?type=Test Case,Test Set&hidden=true

获取对用户可见的所有类别的列表 (按项目分组)

GET {userURI}/categories[?query]

参数	类型	必需	含义
type	字符串	否	以逗号分隔的类别类型 (ID 或名称) 列表，仅显示这些类型的类别。
hidden	布尔型	否	如果设置为 true，还会显示隐藏的类别。默认值为 false。
deleted	布尔型	否	如果设置为 true，还会显示移除的类别。默认值为 false。

获取对用户可见的项目中所有类别的列表

GET {userURI}{projectURI}/categories[?query]

GET {projectURI}{userURI}/categories[?query]

参数	类型	必需	含义
type	字符串	否	以逗号分隔的类别类型 (ID 或名称) 列表，仅显示这些类型的类别。
hidden	布尔型	否	如果设置为 true，还会显示隐藏的类别。默认值为 false。
deleted	布尔型	否	如果设置为 true，还会显示移除的类别。默认值为 false。

获取用户具有特定权限的所有类别的列表 (按项目分组)

GET {userURI}/categories/permission/{permissionIdOrName}[?query]

参数	类型	必需	含义
permissionIdOrName	字符串	是	类别权限的 ID 或名称
type	字符串	否	以逗号分隔的类别类型 (ID 或名称) 列表，仅显示这些类型的类别。
hidden	布尔型	否	如果设置为 true，还会显示隐藏的类别。默认值为 false。
deleted	布尔型	否	如果设置为 true，还会显示移除的类别。默认值为 false。

例如，查找当前用户具有添加项权限的所有“测试用例”类别：

GET https://hostname/cb/rest/user/self/categories/permission/Issue - Add?type=Test Case

获取用户具有特定权限的项目中所有类别的列表

GET {userURI}{projectURI}/categories/permission/{permissionIdOrName}[?query]

GET {projectURI}{userURI}/categories/permission/{permissionIdOrName}[?query]

参数	类型	必需	含义
permissionIdOrName	字符串	是	类别权限的 ID 或名称
type	字符串	否	以逗号分隔的类别类型 (ID 或名称) 列表，仅显示这些类型的类别。
hidden	布尔型	否	如果设置为 true，还会显示隐藏的类别。默认值为 false。
deleted	布尔型	否	如果设置为 true，还会显示移除的类别。默认值为 false。

获取类别中所有项的汇总

GET {categoryURI}/item/summary

例如：

GET https://hostname/cb/rest/project/1/category/Contacts/item/summary

{
"total": 2,
"open": 2
}

获取类别中所有项的大纲 (自 Codebeamer 7.9.0 版本起)

GET {categoryURI}/outline[?query]

参数	类型	必需	含义
paragraph	布尔型	false	是否还要返回各个跟踪器项的段落/章节编号。默认值为 false。
flat	布尔型	false	是否将大纲作为简单列表返回，其中子项直接跟在其父项之后 (值为 true 时)。默认值为 false，这种情况下返回树。
depth	整型	false	返回的大纲/层次结构的最大深度。depth 为 0 时，仅返回顶层项/根项。默认值为无限制 (全深度)。

例如：

GET https://hostname/cb/rest/project/1/category/TestCases/outline?paragraph=true&depth=0

将返回顶层/根目录项 (包括段落/章节编号)。各个项的布尔特性 leaf 用于指示该项具有子项 (false) 还是没有子项 (true)。您可以通过以下方式查询非叶项的子项/后代项：

GET {itemURI}/outline[?query]

这允许以交互/按需方式扩展任意程度或深度的大纲。

newerThan 仅从 Codebeamer 9.3.0 版本开始受支持，且向后兼容旧版 newerThen 参数。使用更新版本时，请改用旧版 newerThen 参数。

获取类别项的页面

GET {categoryURI}/items/page/{page}[?query]

参数	类型	必需	含义
page	整型	是	要返回的结果页的编号。第一页的编号为 1。
pagesize	整型	否	页面大小 (以项数表示)，有效范围为 [1 ..500]。默认值为 100。
status	字符串	否	{"已开启", "已关闭", "已解决", "未解决", "成功", "不成功"} 状况之一，仅显示具有此 (元数据) 状况的类别项。默认值为任意状况。
newerThan	字符串	否	时间戳，用于仅返回在此日期和时间之后创建/修改的项。您可以将相对时间戳指定为 "[{This \| Last [n]}] [{minute \| hour \| day \| week \| month \| quarter \| year}[s]]"，其中 "Today" 是 "This day" 的同义词，"Yesterday" 是 "Last day" 的同义词，例如 "Last week"、"This month" 或 "Last 2 days" 等；或指定为 "hh[:mm[:ss]]"；或指定为 "n {h[our] \| m[in[ute]] \| s[ec[ond]]}[s]"，例如 "30 min" 或 "6 hours" 等。以 ISO 8601 格式指定绝对时间戳，例如 "2013-03-12T14:38:06+01:00"。

获取符合所有指定条件的类别项的页面

GET {categoryURI}/items/and/{criteria}/page/{page}[?query]

参数	类型	必需	含义
criteria	字符串	是	以分号分隔的 property=value[, ...] 条件列表，其中每个条件都必须匹配。
page	整型	是	要返回的结果页的编号。第一页的编号为 1。
pagesize	整型	否	页面大小 (以项数表示)，有效范围为 [1 ..500]。默认值为 100。
newerThan	字符串	否	时间戳，用于仅返回在此日期和时间之后创建/修改的项。您可以将相对时间戳指定为 "[{This \| Last [n]}] [{minute \| hour \| day \| week \| month \| quarter \| year}[s]]"，其中 "Today" 是 "This day" 的同义词，"Yesterday" 是 "Last day" 的同义词，例如 "Last week"、"This month" 或 "Last 2 days" 等；或指定为 "hh[:mm[:ss]]"；或指定为 "n {h[our] \| m[in[ute]] \| s[ec[ond]]}[s]"，例如 "30 min" 或 "6 hours" 等。以 ISO 8601 格式指定绝对时间戳，例如 "2013-03-12T14:38:06+01:00"。

例如：获取由 [USER:bond] 创建的功能测试用例：

GET https://hostname/cb/rest/project/1/category/Test Cases/items/and/submitter=[USER:bond];type=Functional/page/1

获取类别项与至少一个指定条件相符的页面

GET {categoryURI}/items/or/{criteria}/page/{page}[?query]

参数	类型	必需	含义
criteria	字符串	是	以分号分隔的 property=value[, ...] 条件列表，其中必须至少匹配一个条件。
page	整型	是	要返回的结果页的编号。第一页的编号为 1。
pagesize	整型	否	页面大小 (以项数表示)，有效范围为 [1 ..500]。默认值为 100。
newerThan	字符串	否	时间戳，用于仅返回在此日期和时间之后创建/修改的项。您可以将相对时间戳指定为 "[{This \| Last [n]}] [{minute \| hour \| day \| week \| month \| quarter \| year}[s]]"，其中 "Today" 是 "This day" 的同义词，"Yesterday" 是 "Last day" 的同义词，例如 "Last week"、"This month" 或 "Last 2 days" 等；或指定为 "hh[:mm[:ss]]"；或指定为 "n {h[our] \| m[in[ute]] \| s[ec[ond]]}[s]"，例如 "30 min" 或 "6 hours" 等。以 ISO 8601 格式指定绝对时间戳，例如 "2013-03-12T14:38:06+01:00"。

例如：获取其中 "country" 为 Germany 或 "language" 为 German 的联系人的第一页：

GET https://hostname/cb/rest/project/1/category/Contacts/items/or/country=DE;language=de/page/1

加载今天修改的项。

GET https://hostname/cb/rest/project/1/category/Contacts/items/page/1?newerThan=Today

加载昨天或今天修改的项。

GET https://hostname/cb/rest/project/1/category/Contacts/items/page/1?newerThan=Yesterday

获取符合所有强制条件且至少符合一个可选条件的类别项的页面

GET {categoryURI}/items/and/{mandatoryCriteria}/or/{optionalCriteria}/page/{page}[?query]

参数	类型	必需	含义
mandatoryCriteria	字符串	是	以分号分隔的 property=value[, ...] 条件列表，其中每个条件都必须匹配。
optionalCriteria	字符串	是	以分号分隔的 property=value[, ...] 条件列表，其中必须至少匹配一个条件。
page	整型	是	要返回的结果页的编号。第一页的编号为 1。
pagesize	整型	否	页面大小 (以项数表示)，有效范围为 [1 ..500]。默认值为 100。
newerThan	字符串	否	时间戳，用于仅返回在此日期和时间之后创建/修改的项。您可以将相对时间戳指定为 "[{This \| Last [n]}] [{minute \| hour \| day \| week \| month \| quarter \| year}[s]]"，其中 "Today" 是 "This day" 的同义词，"Yesterday" 是 "Last day" 的同义词，例如 "Last week"、"This month" 或 "Last 2 days" 等；或指定为 "hh[:mm[:ss]]"；或指定为 "n {h[our] \| m[in[ute]] \| s[ec[ond]]}[s]"，例如 "30 min" 或 "6 hours" 等。以 ISO 8601 格式指定绝对时间戳，例如 "2013-03-12T14:38:06+01:00"。

例如：获取从本周开始其中 "country" 为 Germany 或 "language" 为 German 的新业务联系人：

GET https://hostname/cb/rest/project/1/category/Contacts/items/and/type=Company/or/country=DE;language=de/page/1?newerThan=This week

这对您有帮助吗?