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

v4.181.0：REST API 开放需求相关的资源，优化文档使用示例

2023-08-22 · sunjingyun

更新内容

  1. 开放需求相关的资源
  2. 统一相似资源的属性开放范围，优化文档中的示例
  3. 开放团队资源
  4. 开放测试用例、执行用例的附件资源
  5. 扩展获取工作项列表、新增获取工作项关联测试用例
  6. 修复若干 API 的错误

开放产品需求相关的资源

获取需求状态列表
GET /v1/ship/idea_states
获取一个需求状态
GET /v1/ship/idea_states/{idea_state_id}
获取需求属性列表
GET /v1/ship/idea_properties
获取一个需求属性
GET /v1/ship/idea_properties/{property_id}
获取需求优先级列表
GET /v1/ship/idea_priorities
获取一个需求优先级
GET /v1/ship/idea_priorities/{priority_id}
获取产品排期列表
GET /v1/ship/products/{product_id}/plans
获取一个产品排期
GET /v1/ship/products/{product_id}/plans/{plan_id}
获取产品模块列表
GET /v1/ship/products/{product_id}/suites
获取一个产品模块
GET /v1/ship/products/{product_id}/suites/{suite_id}
获取需求列表
GET /v1/ship/ideas
获取一个需求
GET /v1/ship/ideas/{idea_id}
获取一个需求关注人
GET /v1/ship/ideas/{idea_id}/participants/{participant_id}

目前需求相关的资源还只是只读资源，创建和修改操作仍需要在 PingCode 网页中完成。获取一个需求的数据结构为：

{
    "id": "64b4d70ba368e6594360ea24",
    "url": "https://rest_api_root/v1/ship/ideas/64b4d70ba368e6594360ea24",
    "product": {
        "id": "6422711c3f12e6c1e46d40e6",
        "url": "http://rest_api_root/v1/ship/products/6422711c3f12e6c1e46d40e6",
        "identifier": "SLC",
        "name": "示例产品"
    },
    "identifier": "SLC-1",
    "title": "示例需求",
    "plan": {
        "id": "63bb744414bd13c9def24ce4",
        "url": "https://rest_api_root/v1/ship/products/6422711c3f12e6c1e46d40e6/plans/63bb744414bd13c9def24ce4",
        "name": "账号管理"
    },
    "assignee": {
        "id": "a0417f68e846aae315c85d24643678a9",
        "url": "https://rest_api_root/v1/directory/users/a0417f68e846aae315c85d24643678a9",
        "name": "john",
        "display_name": "John",
        "avatar": "https://s3.amazonaws.com/bucket/b46ef40c-e22e-4ecf-a599-cace9fba839a_160x160.png"
    },
    "state": {
        "id": "63e1bf51898a0be5a2d21b2a",
        "url": "https://rest_api_root/v1/ship/idea_states/63e1bf51898a0be5a2d21b2a",
        "name": "待评审",
        "type": "pending"
    },
    "priority": {
        "id": "5cb9466afda1ce4ca0090005",
        "url": "https://rest_api_root/v1/ship/idea_priorities/5cb9466afda1ce4ca0090005",
        "name": "P0",
        "type": "high"
    },
    "plan_at": {
        "from": 1690732800,
        "to": 1691337599,
        "granularity": "day"
    },
    "real_at": {
        "from": 1690732800,
        "to": 1691337599,
        "granularity": "day"
    },
    "progress": 0.6,
    "description": "这是一段描述",
    "properties": {
        "backlog_from": "5cb7e6e2fda1ce4ca0000001",
        "backlog_type": "5cb7e763fda1ce4ca0010002"
    },
    "participants": [
        {
            "id": "a0417f68e846aae315c85d24643678a9",
            "url": "https://rest_api_root/v1/ship/ideas/64b4d70ba368e6594360ea24/participants/a0417f68e846aae315c85d24643678a9",
            "type": "user",
            "user": {
                "id": "a0417f68e846aae315c85d24643678a9",
                "url": "https://rest_api_root/v1/directory/users/a0417f68e846aae315c85d24643678a9",
                "name": "john",
                "display_name": "John",
                "avatar": "https://s3.amazonaws.com/bucket/b46ef40c-e22e-4ecf-a599-cace9fba839a_160x160.png"
            }
        },
        {
            "id": "63c8fb32729dee3334d96af7",
            "url": "https://rest_api_root/v1/ship/ideas/64b4d70ba368e6594360ea24/participants/63c8fb32729dee3334d96af7",
            "type": "userGroup",
            "userGroup": {
                "id": "63c8fb32729dee3334d96af7",
                "url": "https://rest_api_root/v1/directory/groups/63c8fb32729dee3334d96af7",
                "name": "Open Team"
            }
        }
    ],
    "created_at": 1689573131,
    "created_by": {
        "id": "a0417f68e846aae315c85d24643678a9",
        "url": "https://rest_api_root/v1/directory/users/a0417f68e846aae315c85d24643678a9",
        "name": "john",
        "display_name": "John",
        "avatar": "https://s3.amazonaws.com/bucket/b46ef40c-e22e-4ecf-a599-cace9fba839a_160x160.png"
    },
    "updated_at": 1689573131,
    "updated_by": {
        "id": "a0417f68e846aae315c85d24643678a9",
        "url": "https://rest_api_root/v1/directory/users/a0417f68e846aae315c85d24643678a9",
        "name": "john",
        "display_name": "John",
        "avatar": "https://s3.amazonaws.com/bucket/b46ef40c-e22e-4ecf-a599-cace9fba839a_160x160.png"
    },
    "is_archived": 0,
    "is_deleted": 0
}

统一相似资源的属性开放范围，优化文档中的示例

我们统一了相似资源的属性开放范围，统一了相似属性的创建和更新逻辑，对文档中的所有资源和示例进行了梳理。比如：

  1. 补全了工单、工作项、测试用例等主要资源的创建时间、创建人、更新时间、更新人、是否删除、是否归档等常用属性；
  2. 统一了各个子产品下自定义属性的数据结构；
  3. 严格区分“{资源}_id”表示资源的 id，“{资源}”表示资源本体（含 id 和 url）；
  4. 将更新一个测试用例的自定义属性的方式修正为跟其他资源一致；
  5. 将附件资源的创建者属性重命名为“created_by”；
  6. 将测试用例类型的资源路径调整为 case_types；
  7. 统一使用正序对资源进行排序；
  8. 等等

另外我们还统一对现有的示例进行了调整，将重要属性、常用属性放置在前面，对同类资源的类似属性的前后顺序进行了调整，并且为了让这些示例更容易被理解，我们尽量让资源们出现在其他资源的引用资源里。

开放团队资源

获取团队列表
GET /v1/directory/groups
获取一个团队
GET /v1/directory/groups/{group_id}

开放测试用例、执行用例的附件资源

向测试用例中上传一个文件
POST /v1/testhub/test_cases/{test_case_id}/files
获取测试用例附件列表
GET /v1/testhub/test_cases/{test_case_id}/attachments
向执行用例中上传一个文件
POST /v1/testhub/runs/{run_id}/files
获取执行用例中的附件列表
GET /v1/testhub/runs/{run_id}/attachments

扩展获取工作项列表、新增获取工作项关联测试用例

获取工作项列表
GET /v1/project/work_items 支持通过下列表条件过滤
project_ids  //多个项目id
parent_ids  //多个项目父工作项id
assignee_ids  //多个负责人id
type_ids //多个工作项类型id
state_ids  //多个状态id
sprint_ids  //多个迭代id
version_ids  //多个发布id
board_ids  //多个看板id
entry_ids  //多个看板栏id
swimlane_ids  //多个泳道id
created_by_ids  //多个创建人id

获取工作项关联测试用例列表
GET /v1/project/work_items/{work_item_id}/test_case_relations

除此之外，REST API 还修复了一些缺陷，更多功能请查看REST API 官方文档 。