文档首页/ 需求管理 CodeArts Req/ API参考/ API/ IPD工作项管理/ 工作项列表分组 - ShowIssuesGroup
更新时间:2026-09-15 GMT+08:00
分享

工作项列表分组 - ShowIssuesGroup

功能介绍

工作项列表分组。

调用方法

请参见如何调用API

授权信息

当前API调用无需身份策略权限。

URI

POST /v1/ipdprojectservice/projects/{project_id}/issues/group

表1 路径参数

参数

是否必选

参数类型

描述

project_id

String

参数解释

项目32位ID,项目唯一标识。通过查询IPD项目列表获取,响应消息体中的id字段的值就是项目ID。

约束限制

不涉及。

取值范围

32个字符,由英文字母和数字组成。

默认取值

不涉及。

表2 Query参数

参数

是否必选

参数类型

描述

issue_type

String

参数解释

工作项类型,区分大小写,传入错误的工作项类型时不返回数据。

约束限制

支持多种工作项类型,使用英文逗号分隔。

取值范围

RR/SF/IR/SR/AR/Task/Bug(系统设备类项目可选值)

RR/SF/IR/US/Task/Bug(独立软件类项目可选值)

RR/Epic/FE/US/Task/Bug(云服务类项目可选值)

默认取值

不涉及。

is_project_group

Boolean

参数解释

是否是项目群场景。

约束限制

不涉及。

取值范围

true:项目群场景。

false:非项目群场景

默认取值

false。

group_field_id

String

参数解释

分组字段ID。

约束限制

通过接口查询工作项类型字段列表获取响应参数中的id字段。

取值范围

不涉及。

默认取值

不涉及。

group_sort

String

参数解释

分组字段选项的排序规则。

约束限制

不涉及。

取值范围

asc:升序。

desc:降序

默认取值

asc。

请求参数

表3 请求Body参数

参数

是否必选

参数类型

描述

filter

Array of Map<String,ConditionVO> objects

参数解释

查询过滤器的数组,每个数组元素就是一个查询条件,数组元素为Map<String, ConditionVO>类型,Map中的key表示查询的列,ConditionVO表示查询条件的值,值的来源根据key动态选择。

示例filter元素 {"descendants.plan_pi":{"values":["956200745322848257"],"operator":"||"}} ,表示查询项目下发布为956200745322848257的工作项。可以将这个查询条件翻译为SQL,select ... where plan_pi in ("956200745322848257"). plan_pi作为key ("descendants."表示在树形结构中搜索符合条件的子工作项,非必要条件。一般场景下,plan作为key即可),发布计划的id作为查询条件的值。如果要查询多个发布下的工作项,values数组中放入多个发布计划的id作为数组元素即可。

约束限制

最大200个字符。

取值范围

不涉及。

默认取值

不涉及。

filter_mode

String

参数解释

过滤模式。

约束限制

最大512个字符。

取值范围

  • OR_AND:多条filter之间是或的关系,同一个filter的key,value是且的关系。

  • AND_OR:多条filter之间是且的关系,同一个filter的key,value是或的关系。

默认取值

AND_OR

page

PageInfoVO object

参数解释

分页信息。

约束限制

不涉及。

取值范围

不涉及。

默认取值

不涉及。

sort

Array of SortInfo objects

参数解释

排序条件。

约束限制

不涉及。

取值范围

不涉及。

默认取值

不涉及。

表4 ConditionVO

参数

是否必选

参数类型

描述

values

Array of strings

参数解释

查询条件的值。

取值范围

根据查询条件的key确定。如key为plan_pi,值则为发布计划的ID;如果key为assignee等人员类型字段,值为用户ID;若key为created_date等日期时间类型字段,一般为[1760284800000,1760371199999]这种起止时间戳,精确到毫秒。

约束限制

最大200个字符。

operator

String

参数解释

操作符。

约束限制

不涉及

取值范围

  • "||":表示查询目标和values之间的关系为或。

  • "!":表示查询目标和values之间的关系为非。

  • "=":表示查询目标和values之间的关系为等于,通常values中只有一个元素时使用。

  • "<>"、"<"、">":表示查询目标和values之间的关系为区间、小于、大于,通常用于日期时间、整数类型的过滤,包含边界值。

默认取值

"||"

表5 PageInfoVO

参数

是否必选

参数类型

描述

page_no

Integer

参数解释

分页索引。

约束限制

不涉及

取值范围

最小值1,最大值10000

默认取值

1

page_size

Integer

参数解释

分页大小。

约束限制

不涉及

取值范围

最小值5,最大值200

默认取值

200

表6 SortInfo

参数

是否必选

参数类型

描述

field

String

参数解释

排序字段code。

约束限制

不涉及

取值范围

通过查询字段模板列表接口获取,响应体中的code就是字段唯一标识。

默认取值

不涉及

asc

Boolean

参数解释

是否升序。

约束限制

不涉及

取值范围

  • true:升序

  • false:降序

默认取值

不涉及

响应参数

状态码:200

表7 响应Body参数

参数

参数类型

描述

status

String

参数解释

响应状态。

取值范围

success:响应成功。

error:响应失败

message

String

参数解释

响应消息。

取值范围

不涉及。

result

GroupIssueVO object

参数解释

返回数据。

取值范围

不涉及。

表8 GroupIssueVO

参数

参数类型

描述

field_info

FieldVO object

参数解释

分组字段信息。

取值范围

不涉及。

data

Array of GroupDataVO objects

参数解释

工作项分组数据列表,包含字段选项、数据统计、工作项列表数据。

取值范围

不涉及。

表9 FieldVO

参数

参数类型

描述

id

String

参数解释

字段唯一标识。

取值范围

5~32个字符。

code

String

参数解释

字段编码。在项目中使用时一般使用code作为字段标识而不是字段ID。

取值范围

不涉及。

display_name

String

参数解释

字段显示名称。

取值范围

不涉及。

created_by

String

参数解释

字段创建人ID。

取值范围

不涉及。

created_date

String

参数解释

字段创建时间。时间戳格式,单位毫秒。

取值范围

不涉及。

modified_by

String

参数解释

字段最后修改人ID。

取值范围

不涉及。

modified_date

String

参数解释

字段最后修改时间。时间戳格式,单位毫秒。

取值范围

不涉及。

field_type

String

参数解释

字段类型标识。

取值范围

不涉及。

field_type_id

String

参数解释

字段类型ID。用于区分不同的字段类型。

取值范围

不涉及。

field_type_name

String

参数解释

字段类型名称。如单选列表、多选列表、多行文本等。

取值范围

不涉及。

definition_type

String

参数解释

字段定义类型。用于区分系统字段和自定义字段。

取值范围

  • 1:系统字段。

  • 2:系统字段。

  • 3:系统字段。

  • 4:租户自定义字段。

  • 5:项目自定义字段。

show_on_card

Boolean

参数解释

是否显示在云服务类型的迭代看板卡片模式中。

取值范围

  • true:显示。

  • false:不显示。

optional

Boolean

参数解释

字段是否为必填项。

取值范围

  • true:必填。

  • false:非必填。

controlled

Boolean

参数解释

字段是否受控。如果工作项已经基线,修改受控字段值时会触发变更评审。

取值范围

  • true:受控。

  • false:不受控。

immutable

Boolean

参数解释

字段是否不可变。更新接口无法更新不可变字段。

取值范围

  • true:不可变。

  • false:可变。

no

Integer

参数解释

字段排序序号。数值越小越靠前显示。

取值范围

0~9999的整数。

default_value

String

参数解释

字段默认值。创建工作项时自动填充。

取值范围

不涉及。

option

OptionEntity object

参数解释

字段选项。单选列表类型字段的选项信息,包含选项ID、编码、显示名称等属性。

取值范围

不涉及。

all_options

Array of OptionEntity objects

参数解释

字段所有选项。多选列表类型字段的全部选项信息,数组元素包含选项ID、编码、显示名称等属性。

取值范围

不涉及。

has_same_display_name

Boolean

参数解释

是否存在同名字段。用于检测字段名称冲突。

取值范围

  • true:存在同名字段。

  • false:不存在同名字段。

表10 OptionEntity

参数

参数类型

描述

id

String

参数解释

选项id。

取值范围

不涉及

code

String

参数解释

选项code值。

取值范围

不涉及

display_value

String

参数解释

选项名称。

取值范围

不涉及

value

String

参数解释

选项唯一标识。

取值范围

不涉及

level

Integer

参数解释

选项层级。用于区分层级字段的层级深度。

取值范围

1~4的整数,层级字段最多支持4层。

sequence

Integer

参数解释

选项排序序号。数值越小越靠前显示。

取值范围

0~2147483647。

parent_id

String

参数解释

父选项ID。层级选项中指向父级选项的标识,顶级选项为空或null。

取值范围

2~32个字符。

表11 GroupDataVO

参数

参数类型

描述

field_option

Map<String,Object>

参数解释

字段选项对象,由字段类型决定返回对象结构体。

取值范围

不涉及。

issue_count

Integer

参数解释

分组工作项数量统计,最多只会返回1000条数据。

取值范围

0-1000。

issues

Array of Map<String,String> objects

参数解释

分组工作项列表数据。

取值范围

不涉及。

状态码:400

表12 响应Body参数

参数

参数类型

描述

error_code

String

参数解释

错误码。

取值范围

不涉及。

error_msg

String

参数解释

错误描述,对error_code的补充解释。

取值范围

不涉及。

请求示例

研发需求IR,SR,AR根据字段优先级(字段id10042)的选项值升序进行分组。

POST https://{endpoint}/v1/ipdprojectservice/projects/{project_id}/issues/query/issues/group?issue_type=IR,SR,AR&group_field_id=10042&group_sort=asc

{
  "filter" : [ {
    "status" : {
      "values" : [ "Start" ],
      "operator" : "||"
    }
  } ]
}

响应示例

状态码:200

{
  "status" : "success",
  "message" : null,
  "result" : {
    "field_info" : {
      "display_name" : "优先级",
      "code" : "priority",
      "name" : "priority",
      "id" : "10042",
      "show" : true,
      "description" : "优先级",
      "default_value" : "中",
      "default_value_map" : {
        "value" : "中"
      },
      "field_type" : "pick",
      "created_by" : "system",
      "created_date" : "2025-08-18 15:32:38.0",
      "modified_by" : "system",
      "modified_date" : "2025-08-18 15:32:38.0",
      "definition_type" : "2",
      "field_type_id" : "10001",
      "alm_field_type_id" : "10001",
      "field_type_name" : "单选列表",
      "using_status" : true,
      "required" : false,
      "controlled" : false,
      "immutable" : false,
      "optional" : true,
      "option_source" : "PICK",
      "show_on_split" : false,
      "show_on_filter" : true,
      "show_on_edit" : true,
      "show_on_table" : true,
      "sort_on_table" : true,
      "no" : 70,
      "option" : [ {
        "id" : "1164224531902066709",
        "display_value" : "高",
        "value" : "高",
        "code" : "高",
        "value_py" : "3",
        "sequence" : 1,
        "level" : 1,
        "domain_id" : "1164224531201617921",
        "belong_definition_type" : "5"
      }, {
        "id" : "1164224531902066708",
        "display_value" : "中",
        "value" : "中",
        "code" : "中",
        "value_py" : "2",
        "sequence" : 2,
        "level" : 1,
        "domain_id" : "1164224531201617921",
        "belong_definition_type" : "5"
      }, {
        "id" : "1164224531902066707",
        "display_value" : "低",
        "value" : "低",
        "code" : "低",
        "value_py" : "1",
        "sequence" : 3,
        "level" : 1,
        "domain_id" : "1164224531201617921",
        "belong_definition_type" : "5"
      } ]
    },
    "data" : [ {
      "field_option" : {
        "id" : "1164224531902066708",
        "display_value" : "中",
        "value" : "中",
        "code" : "中",
        "value_py" : "2",
        "sequence" : 2,
        "level" : 1,
        "domain_id" : "1164224531201617921",
        "belong_definition_type" : "5"
      },
      "issue_count" : 2,
      "issues" : [ {
        "position_float" : "9999999998.0339220000",
        "develop_owner" : null,
        "type" : "requirement",
        "plan_test_end_date" : null,
        "domain_id" : {
          "id" : "1164224531201617921",
          "name" : "mod1-min-0818-1",
          "title" : "mod1-min-0818-1",
          "project_id" : "5e5670b9d38a4512940d9cd34c79adf3",
          "parent_id" : null,
          "category" : "Project",
          "created_by" : "c2d89e38a64a466f8f945f595df4402d",
          "model_id" : "10001",
          "children" : [ ]
        },
        "number" : "IR20250821460586",
        "path" : "/1165232073562370048",
        "convolution_actual_hours" : null,
        "upstream_change_flag" : null,
        "workload_man_day" : null,
        "children" : null,
        "id" : "1165232073562370048",
        "state" : "正在工作",
        "stay_days" : 0,
        "ir2feature" : "",
        "need_break" : {
          "id" : "1164224531902066748",
          "display_value" : "是",
          "value" : "yes",
          "code" : "yes",
          "value_py" : "yes",
          "sequence" : 1,
          "level" : 1,
          "domain_id" : "1164224531201617921",
          "belong_definition_type" : "5"
        },
        "collaborative_history" : null,
        "related_network_security" : {
          "id" : "1164224531902066693",
          "display_value" : "否",
          "value" : "no",
          "code" : "no",
          "value_py" : "no",
          "sequence" : 2,
          "level" : 1,
          "domain_id" : "1164224531201617921",
          "belong_definition_type" : "5"
        },
        "assigned_cc" : null,
        "workitem2label" : null,
        "baseline" : null,
        "close_time" : null,
        "priority" : {
          "id" : "1164224531902066708",
          "display_value" : "中",
          "value" : "中",
          "code" : "中",
          "value_py" : "2",
          "sequence" : 2,
          "level" : 1,
          "domain_id" : "1164224531201617921",
          "belong_definition_type" : "5"
        },
        "modified_date" : "1755742575426",
        "created_by" : {
          "user_id" : "c2d89e38a64a466f8f945f595df4402d",
          "user_name" : "ForTest",
          "domain_id" : "aae03ca0d6814951980945b6eeca56cd",
          "nick_name" : "ForTest",
          "role_id" : "f06cca67c5374731ab643fe35e48e2fa,aee76e0b876c4406927e8973a96233c0",
          "role_name" : "项目经理,项目管理员",
          "role_alias_name" : "Project manager,Project admin",
          "role_code" : "Project manager,project_admin"
        },
        "break_status" : {
          "id" : "1164224531902066713",
          "display_value" : "未分解",
          "value" : "undecomposed",
          "code" : "undecomposed",
          "value_py" : "undecomposed",
          "sequence" : 2,
          "level" : 1,
          "domain_id" : "1164224531201617921",
          "belong_definition_type" : "5"
        },
        "status_modified_date" : "1755742575373",
        "important" : null,
        "collaboratives" : null,
        "parent_id" : null,
        "business_domain" : {
          "id" : "1164224531902066727",
          "display_value" : "软件",
          "value" : "software",
          "code" : "software",
          "value_py" : "rj",
          "sequence" : 1,
          "level" : 1,
          "domain_id" : "1164224531201617921",
          "belong_definition_type" : "5"
        },
        "assignee" : {
          "user_id" : "c2d89e38a64a466f8f945f595df4402d",
          "user_name" : "ForTest",
          "domain_id" : "aae03ca0d6814951980945b6eeca56cd",
          "nick_name" : "ForTest",
          "role_id" : "f06cca67c5374731ab643fe35e48e2fa,aee76e0b876c4406927e8973a96233c0",
          "role_name" : "项目经理,项目管理员",
          "role_alias_name" : "Project manager,Project admin",
          "role_code" : "Project manager,project_admin"
        },
        "region" : "example",
        "status" : {
          "id" : "1164224531914649621",
          "belonging" : "START",
          "space_id" : "1164224531201617921",
          "name" : "初始",
          "code" : "Start",
          "definition_type" : "5",
          "belong_definition_type" : 3,
          "display_value" : "初始",
          "position" : 1,
          "displayable" : 1,
          "editable" : 1,
          "deletable" : 1,
          "mutable" : 1,
          "title_py" : "cs",
          "created_by" : "c2d89e38a64a466f8f945f595df4402d",
          "created_date" : "1755502358654",
          "modified_date" : "1755502358654",
          "modified_by" : "c2d89e38a64a466f8f945f595df4402d",
          "linkage_node_fields" : false
        },
        "plan_pi" : null,
        "tenant_id" : "aae03ca0d6814951980945b6eeca56cd",
        "plan_dev_end_date" : null,
        "link" : "",
        "is_suspended" : null,
        "change_status" : null,
        "title" : "IR-test-2",
        "sum_workload_man_day" : null,
        "ir2rr" : "",
        "plan_end_date" : null,
        "plan_start_date" : null,
        "convolution_plan_hours" : null,
        "no_break_reason" : null,
        "submitted_by" : [ {
          "user_id" : "c2d89e38a64a466f8f945f595df4402d",
          "user_name" : "ForTest",
          "domain_id" : "aae03ca0d6814951980945b6eeca56cd",
          "nick_name" : "ForTest",
          "role_id" : "f06cca67c5374731ab643fe35e48e2fa,aee76e0b876c4406927e8973a96233c0",
          "role_name" : "项目经理,项目管理员",
          "role_alias_name" : "Project manager,Project admin",
          "role_code" : "Project manager,project_admin"
        } ],
        "cascade_delete" : "none",
        "issue_opinion_id" : null,
        "test_owner" : null,
        "issue_review_id" : null,
        "modified_by" : {
          "user_id" : "c2d89e38a64a466f8f945f595df4402d",
          "user_name" : "ForTest",
          "domain_id" : "aae03ca0d6814951980945b6eeca56cd",
          "nick_name" : "ForTest",
          "role_id" : "f06cca67c5374731ab643fe35e48e2fa,aee76e0b876c4406927e8973a96233c0",
          "role_name" : "项目经理,项目管理员",
          "role_alias_name" : "Project manager,Project admin",
          "role_code" : "Project manager,project_admin"
        },
        "created_date" : "1755742575299",
        "closed_flag" : null,
        "category" : "IR",
        "collaborative_status" : [ ],
        "setup" : true,
        "inherit_button" : "hide",
        "parent_status" : "no"
      }, {
        "position_float" : "9999999998.6892810000",
        "develop_owner" : null,
        "type" : "requirement",
        "plan_test_end_date" : null,
        "domain_id" : {
          "id" : "1164224531201617921",
          "name" : "mod1-min-0818-1",
          "title" : "mod1-min-0818-1",
          "project_id" : "5e5670b9d38a4512940d9cd34c79adf3",
          "parent_id" : null,
          "category" : "Project",
          "created_by" : "c2d89e38a64a466f8f945f595df4402d",
          "model_id" : "10001",
          "children" : [ ]
        },
        "number" : "IR20250821460683",
        "path" : "/1165232022399000576",
        "convolution_actual_hours" : null,
        "upstream_change_flag" : null,
        "workload_man_day" : null,
        "children" : null,
        "id" : "1165232022399000576",
        "state" : "正在工作",
        "stay_days" : 0,
        "ir2feature" : "",
        "need_break" : {
          "id" : "1164224531902066748",
          "display_value" : "是",
          "value" : "yes",
          "code" : "yes",
          "value_py" : "yes",
          "sequence" : 1,
          "level" : 1,
          "domain_id" : "1164224531201617921",
          "belong_definition_type" : "5"
        },
        "collaborative_history" : null,
        "related_network_security" : {
          "id" : "1164224531902066693",
          "display_value" : "否",
          "value" : "no",
          "code" : "no",
          "value_py" : "no",
          "sequence" : 2,
          "level" : 1,
          "domain_id" : "1164224531201617921",
          "belong_definition_type" : "5"
        },
        "assigned_cc" : null,
        "workitem2label" : null,
        "baseline" : null,
        "close_time" : null,
        "priority" : {
          "id" : "1164224531902066708",
          "display_value" : "中",
          "value" : "中",
          "code" : "中",
          "value_py" : "2",
          "sequence" : 2,
          "level" : 1,
          "domain_id" : "1164224531201617921",
          "belong_definition_type" : "5"
        },
        "modified_date" : "1755742563247",
        "created_by" : {
          "user_id" : "c2d89e38a64a466f8f945f595df4402d",
          "user_name" : "ForTest",
          "domain_id" : "aae03ca0d6814951980945b6eeca56cd",
          "nick_name" : "ForTest",
          "role_id" : "f06cca67c5374731ab643fe35e48e2fa,aee76e0b876c4406927e8973a96233c0",
          "role_name" : "项目经理,项目管理员",
          "role_alias_name" : "Project manager,Project admin",
          "role_code" : "Project manager,project_admin"
        },
        "break_status" : {
          "id" : "1164224531902066713",
          "display_value" : "未分解",
          "value" : "undecomposed",
          "code" : "undecomposed",
          "value_py" : "undecomposed",
          "sequence" : 2,
          "level" : 1,
          "domain_id" : "1164224531201617921",
          "belong_definition_type" : "5"
        },
        "status_modified_date" : "1755742563179",
        "important" : null,
        "collaboratives" : null,
        "parent_id" : null,
        "business_domain" : {
          "id" : "1164224531902066727",
          "display_value" : "软件",
          "value" : "software",
          "code" : "software",
          "value_py" : "rj",
          "sequence" : 1,
          "level" : 1,
          "domain_id" : "1164224531201617921",
          "belong_definition_type" : "5"
        },
        "assignee" : {
          "user_id" : "c2d89e38a64a466f8f945f595df4402d",
          "user_name" : "ForTest",
          "domain_id" : "aae03ca0d6814951980945b6eeca56cd",
          "nick_name" : "ForTest",
          "role_id" : "f06cca67c5374731ab643fe35e48e2fa,aee76e0b876c4406927e8973a96233c0",
          "role_name" : "项目经理,项目管理员",
          "role_alias_name" : "Project manager,Project admin",
          "role_code" : "Project manager,project_admin"
        },
        "region" : "example",
        "status" : {
          "id" : "1164224531914649621",
          "belonging" : "START",
          "space_id" : "1164224531201617921",
          "name" : "初始",
          "code" : "Start",
          "definition_type" : "5",
          "belong_definition_type" : 3,
          "display_value" : "初始",
          "position" : 1,
          "displayable" : 1,
          "editable" : 1,
          "deletable" : 1,
          "mutable" : 1,
          "title_py" : "cs",
          "created_by" : "c2d89e38a64a466f8f945f595df4402d",
          "created_date" : "1755502358654",
          "modified_date" : "1755502358654",
          "modified_by" : "c2d89e38a64a466f8f945f595df4402d",
          "linkage_node_fields" : false
        },
        "plan_pi" : null,
        "tenant_id" : "aae03ca0d6814951980945b6eeca56cd",
        "plan_dev_end_date" : null,
        "link" : "",
        "is_suspended" : null,
        "change_status" : null,
        "title" : "IR-test-1",
        "sum_workload_man_day" : null,
        "ir2rr" : "",
        "plan_end_date" : null,
        "plan_start_date" : null,
        "convolution_plan_hours" : null,
        "no_break_reason" : null,
        "submitted_by" : [ {
          "user_id" : "c2d89e38a64a466f8f945f595df4402d",
          "user_name" : "ForTest",
          "domain_id" : "aae03ca0d6814951980945b6eeca56cd",
          "nick_name" : "ForTest",
          "role_id" : "f06cca67c5374731ab643fe35e48e2fa,aee76e0b876c4406927e8973a96233c0",
          "role_name" : "项目经理,项目管理员",
          "role_alias_name" : "Project manager,Project admin",
          "role_code" : "Project manager,project_admin"
        } ],
        "cascade_delete" : "none",
        "issue_opinion_id" : null,
        "test_owner" : null,
        "issue_review_id" : null,
        "modified_by" : {
          "user_id" : "c2d89e38a64a466f8f945f595df4402d",
          "user_name" : "ForTest",
          "domain_id" : "aae03ca0d6814951980945b6eeca56cd",
          "nick_name" : "ForTest",
          "role_id" : "f06cca67c5374731ab643fe35e48e2fa,aee76e0b876c4406927e8973a96233c0",
          "role_name" : "项目经理,项目管理员",
          "role_alias_name" : "Project manager,Project admin",
          "role_code" : "Project manager,project_admin"
        },
        "created_date" : "1755742563095",
        "closed_flag" : null,
        "category" : "IR",
        "collaborative_status" : [ ],
        "setup" : true,
        "inherit_button" : "hide",
        "parent_status" : "no"
      } ]
    } ]
  }
}

状态码

状态码

描述

200

工作项列表分组接口成功的响应。

400

错误信息

错误码

请参见错误码

相关文档