通过与 Jira 对比，让您更全面了解 PingCode 跳转
PingCode AI 开启智能化研发管理新时代 跳转
关闭
pingcode logo
pingcode logo
功能日记

v5.17.0：REST API 开放空间和页面资源

2023-11-07 · sunjingyun

更新内容

  1. 开放空间资源
  2. 开放页面资源
  3. 开放页面版本资源
  4. 完善团队资源的写入能力

开放空间资源

开放知识库子产品内的空间资源：

创建一个空间
POST /v1/wiki/spaces
部分更新一个空间
PATCH /v1/wiki/spaces/{space_id}
获取一个空间
GET /v1/wiki/spaces/{space_id}
获取空间列表
GET /v1/wiki/spaces
删除一个空间
DELETE /v1/wiki/spaces/{space_id}

需要特殊提醒的是，不能使用企业令牌创建和修改个人空间，而个人令牌不受这个限制，个人令牌完全根据个人在 PingCode 内部的权限而定；两种令牌都可以查看个人空间。另外，在创建团队空间时，需同时指定该空间所属的团队，其余注意事项可参见 REST API 文档。除一些特殊属性之外，空间的属性结构与项目、产品、测试库的属性结构保持一致。

{
    "id": "642fd641209b56920a6c6e5f",
    "url": "https://rest_api_root/v1/wiki/spaces/642fd641209b56920a6c6e5f",
    "identifier": "GROUP",
    "name": "团队空间",
    "scope_type": "user_group",
    "visibility": "private",
    "color": "#FB7894",
    "description": "团队空间所属一个团队，只能添加所属团队内的成员。",
    "members": [],
    "created_at": 1583290300,
    "created_by": {
      	...
    },
    "updated_at": 1583290300,
    "updated_by": {
        ...
    },
    "is_archived": 0,
    "is_deleted": 0
}

开放页面资源

开放知识库子产品内的页面资源（只开放了文档类型的页面写入能力）：

创建一个页面
POST /v1/wiki/pages
部分更新一个页面
PATCH /v1/wiki/pages/{page_id}
更新一个文档正文
PUT /v1/wiki/pages/{page_id}/content
获取一个页面
GET /v1/wiki/pages/{page_id}
获取一个文档正文
GET /v1/wiki/pages/{page_id}/content?version_id=
获取页面列表
GET /v1/wiki/pages?space_id=
删除一个页面
DELETE /v1/wiki/pages/{page_id}

值得注意的是，页面和页面正文是分离的两个资源。但是在创建一个页面的时候，可以指定页面的正文，这样是便于通过 REST API 导入外部数据。第二个需要注意的是，通过 REST API 操作页面时，不存在草稿状态，即创建、更新即发布一个新的页面版本，因此使用时务必谨慎。还有一个需要注意的是，获取页面列表时必须要指定空间 id，也就是一次只能获取一个空间下的页面，不支持通过 REST API 遍历所有的页面。最后一个需要注意的是，在获取文档正文和更新文档正文时，均可以指定文档格式为： text ,  markdown 和 html ，但是即便使用相同的格式获取了内容，再重新更新回去也不能保证页面上的样式完全不变，因为这三种格式均为转译过的格式，与 PingCode 文档里的格式已经相差甚远，因此不建议通过 REST API 对复杂页面进行反复编辑，还是建议使用 PingCode Wiki 来操作。除一些特殊属性之外，页面的属性结构与需求、工单、工作项、用例基本一致。

{
    "id": "63e1bf51760505c8795ebccc",
    "url": "https://rest_api_root/v1/wiki/pages/63e1bf51760505c8795ebccc",
    "space": {
      	……
    },
    "name": "示例页面",
    "parent": {
      	……
    },
    "type": "document",
    "icon": "file-fill",
    "readings": 0,
    "published_at": 1675738962,
    "published_by": {
		……
    },
    "participants": [……],
    "created_at": 1675738962,
    "created_by": {
      	……
    },
    "updated_at": 1675738962,
    "updated_by": {
		……
    },
    "is_archived": 0,
    "is_deleted": 0
}

在开放页面资源时，我们同时在全局的”评论“、”附件“、”关联“中支持了页面。也就是可以全局的方式来为创建评论、上传附件、关联页面等。

开放页面版本

开放页面版本资源：

获取一个页面版本
GET /v1/wiki/pages/{page_id}/versions/{version_id}
获取页面版本列表
GET /v1/wiki/pages/{page_id}/versions
恢复指定页面版本
POST /v1/wiki/pages/{page_id}/versions/{version_id}/restore

可以通过获取页面版本列表，然后查看这个版本正文，再恢复页面到指定版本的顺序来回滚被改坏的文档。

完善团队资源的写入能力

完善了团队资源的写入能力：

创建一个团队
POST /v1/directory/groups
部分更新一个团队
PATCH /v1/directory/groups/{group_id}
添加一个团队成员
POST /v1/directory/groups/{group_id}/members
获取团队成员列表
GET /v1/directory/groups/{group_id}/members
移除一个团队成员
DELETE /v1/directory/groups/{group_id}/members/{member_id}

其他变化

  1. 我们同时开放了项目、产品、测试库的”可见性“属性
  2. 工作项列表支持通过标签过滤
  3. 执行用例支持通过模块过滤
  4. 在工作项的引用数据中开放了它的”自定义属性“，即在”关联“场景下，即可拿到工作项的自定义属性。
  5. 获取执行用例的结果记录和获取测试用例的执行历史
  6. 创建工单时支持指定负责人和优先级
  7. 缺陷修复

更多功能，详见 PingCode REST API 文档