飞书项目帮助中心

Appearance

Return to top
页面导航

获取指定的工作项列表[增强]

一：单空间

请求体说明

类别值
请求地址{base_url}/open_api/:project_key/work_item/:work_item_type_key/search/params
请求方式POST

请求 Header

字段值必须填写
Content-Typeapplication/json必须
X-PLUGIN-TOKEN用户在开放平台中获取的 Token，参考插件身份凭证章节。必须
X-USER-KEY当选择使用插件身份凭证的时候，需要额外必选指定接口调用的用户user_key，user_key可双击用户头像获取可选
X-IDEM-UUID写类型接口的幂等串，可以不设置，设置后会进行同一个X-PLUGIN-TOKEN下同一接口的幂等判断可选

参考请求格式如下：

curl --location -g --request GET '{base_url}/open_api/:project_key/work_item/:work_item_type_key/search/params' \
--header 'X-PLUGIN-TOKEN: {{token}}' \
--header 'X-USER-KEY: {{user_key}}' \
--data-raw ''

路径参数

参数名是否必填值类型说明
project_key是string空间id [project_key]，或者空间域名 [simple_name]
work_item_type_key是string工作项类型，可以从获取工作项类型接口获取。

请求参数

参数名是否必填值类型说明
search_group是SearchGroup筛选条件，可参考搜索参数格式及示例。
page_size否int64每页数据，最大 50；排序方式：按照工作项id 排序。
page_num否int64分页页码，从1开始，默认为1。

请求体格式 

{
    "page_size":50,
    "page_num":1,
    "search_group":{
        "conjunction":"AND",
        "search_params":[
            {
                "param_key":"created_at",
                "value":1654064482000,
                "operator":">"
            },
            {
                "param_key":"created_at",
                "value":1654063482000,
                "operator":"<"
            },
            {
                "param_key":"sub_stage",
                "value":["start"],
                "operator":"="
            }
        ]
    }
}

返回值类型

list[WorkItemInfo]，最多只能查询到2000条数据，超过请自行用过滤条件减少匹配的工作项数目。

返回格式 

{
    "data":[//结构同获取工作项详情
        {
            "id":1,
            "name":"item1",
            "work_item_type_key":"story",
            "project_key":"60acd5610444ba031b503055",
            "simple_name":"test",
            "template_type":"control",
            "pattern":"Node",
            "sub_stage":"started",
            "work_item_status": {},
            "current_node":[
                {
                    "id":"state_1",
                    "name":"node1",
                    "owners":[
                        "7012514555133820947"
                    ]
                }
            ],
            "created_by":"7009146719661228031",
            "updated_by":"7009146719661228031",
            "created_at":1633776613033,
            "updated_at":1633776613033,
            "fields":[
                {
                    "field_alias": "",
                    "field_key": "aborted",
                    "field_type_key": "aborted",
                    "field_value": {
                        "is_aborted": false,
                        "reason": ""
                    }
                },
                {
                    "field_alias": "",
                    "field_key": "role_owners",
                    "field_type_key": "role_owners",
                    "field_value": [
                        {
                            "owners": [
                                "7012514555184152596"
                            ],
                            "role": "uiouiouio"
                        },
                        {
                            "owners": null,
                            "role": "test"
                        },
                        {
                            "owners": null,
                            "role": "tt"
                        }
                    ]
                }
            ],
        }
    ],
    "err": {},
    "err_msg": "",
    "err_code": 0,
    "pagination": {
        "page_num": 1,
        "page_size": 10,
        "total": 1
    }
}

搜索参数格式及常用示例

操作符枚举值 

const {
    Reg = "~" //匹配
    NReg = "!~" //不匹配
    Eq = "=" //等于
    Ne = "!=" //不等于
    Lt = "<" //小于
    Gt = ">" //大于
    Lte = "<=" //小于等于
    Gte = ">=" //大于等于
    HasAnyOf = "HAS ANY OF" //存在选项属于
    HasNoneOf = "HAS NONE OF" //不存在选项属于
    IsNull = "IS NULL" //为空
    NotNull = "IS NOT NULL" //不为空
}

固定参数及取值

如果操作符选的是为空、不为空，不校验参数值，除流程节点时间、节点负责人、角色人员会校验参数值，只校验参数是否支持该操作符。

参数名
参数key
操作符可取值
参数值类型
说明
进行中节点
current_nodes
"="、"!="、"HAS ANY OF"、"HAS NONE OF"
list<string>
节点名称列表
筛选时对应「进行中节点」
流程节点
all_states
"="、"!="、"HAS ANY OF"、"HAS NONE OF"
list<string>
节点名称列表
筛选时对应「流程节点」
流程节点时间
feature_state_time
"<"、">"、"<="、">="、"IS NULL"、"IS NOT NULL"
[{

    "state_name":"开始", //节点名称

    "state_timestamp":1645718400000, //节点筛选时间戳

    "state_condition":0 //筛选的节点状态，开始：0，结束：1

}]
"state_name":需要筛选的节点名称，示例："开始"
"state_timestamp": 需要筛选的节点时间戳，内部转成天的单位
"state_condition": 需要筛选的节点状态，枚举，只能选start=0，end=1
筛选时对应「流程节点时间」
全部人员
people
"="、"!="、"HAS ANY OF"、"HAS NONE OF"、"IS NULL"、"IS NOT NULL"
list<string>
user_key列表
筛选时对应「参与人员」中的全部人员
创建时间
created_at
"="、"!="、"<"、">"、"<="、">="
int64
毫秒时间戳
更新时间
updated_at
"="、"!="、"<"、">"、"<="、">="
int64
毫秒时间戳
节点负责人
node_owners
"="、"!="、"HAS ANY OF"、"HAS NONE OF"、"IS NULL"、"IS NOT NULL"
[{

    "owners": [""],

    "state_name": "",

}]
指定节点名称和人员，多组节点之间关系用「AND」，如果需要用「OR」，使用group拆分即可
筛选时对应「参与人员」中的节点负责人
工作项ID
work_item_id
"="、"!="、"<"、">"、"<="、">="，
"HAS ANY OF"、"HAS NONE OF"
list<int64>
工作项id列表
工作项状态
work_item_status
"="、"!="、"HAS ANY OF"、"HAS NONE OF"
list<string>
工作项状态key列表。如果要筛选终止状态，"=","HAS ANY OF"这两个操作需要传closed；"!=","HAS NONE OF"这两个操作符不需要传closed，默认会过滤掉已终止的需求
需求：对应「需求状态」
其他工作项：对应「状态」
模板id
template_id
"="、"!="、"HAS ANY OF"、"HAS NONE OF"、"IS NULL"、"IS NOT NULL"
list<int64>
模板id列表，可通过获取工作项下流程类型获取
筛选时对应「工作项类型」
业务线
business
"="、"!="、"HAS ANY OF"、"HAS NONE OF"、"IS NULL"、"IS NOT NULL"
list<string>
业务线id列表，可通过获取空间下业务线详情获取
角色人员
role_owners
"=","!=","HAS ANY OF","HAS NONE OF","IS NULL", "IS NOT NULL"
[{

    "owners": [""],

    "role": "",

}]
指定角色和人员，多个角色之间关系用「且」，如果需要用「或」，使用group拆分即可
筛选时对应「参与人员」中的角色人员

自定义类型及取值

如果操作符选的是为空、不为空，不校验字段值，只校验字段当前字段是否支持该操作符。

参数类型
对应的typeKey
操作符可取值
字段值类型
说明
单行文本/多行文本
text
"~"、"!~"、"="、"!="、"IS NULL"、"IS NOT NULL"
string
匹配使用的是前后模糊匹配
数字
number
"="、"!="、"<"、">"、"<="、">="、"IS NULL"、"IS NOT NULL"
float64
正常操作即可
链接
link
"~"、"!~"、"="、"!="、"IS NULL"、"IS NOT NULL"
string
匹配链接的字符串
开关
bool
"="、"!="、"IS NULL"、"IS NOT NULL"
bool
搜索开关类型，如果想搜空值，需要使用"IS NULL"操作符
单值系统外信号
signal
"="、"!="、"HAS ANY OF"、"HAS NONE OF"
list<string>
系统外信号，"undefined"表示暂无信息，"null"表示进行中，"false"表示未通过，"true"表示已通过;
单选
select
"="、"!="、"HAS ANY OF"、"HAS NONE OF"、"IS NULL"、"IS NOT NULL"
list<string>
  • 选项value值列表，(不是label)
  • 可通过获取空间字段接口，拿到选项值列表
  • 或者可通过「字段配置」「配置选项」来查看具体选项的id
单选按钮
radio
"="、"!="、"HAS ANY OF"、"HAS NONE OF"、"IS NULL"、"IS NOT NULL"
list<string>
多选
multi-select
"="、"!="、"HAS ANY OF"、"HAS NONE OF"、"IS NULL"、"IS NOT NULL"
list<string>
级联单选
tree-select
"="、"!="、"HAS ANY OF"、"HAS NONE OF"、"IS NULL"、"IS NOT NULL"
list<string>
级联多选
tree-multi-select
"="、"!="、"HAS ANY OF"、"HAS NONE OF"、"IS NULL"、"IS NOT NULL"
list<string>
单选人员
user
"="、"!="、"HAS ANY OF"、"HAS NONE OF"、"IS NULL"、"IS NOT NULL"
list<string>
user_key列表
多选人员
multi-user
"="、"!="、"HAS ANY OF"、"HAS NONE OF"、"IS NULL"、"IS NOT NULL"
list<string>
user_key列表
富文本
multi-text
"~"、"!~"、"IS NULL"、"IS NOT NULL"
string
只会以无格式的值进行匹配
单选关联工作项
workitem_related_select
"="、"!="、"HAS ANY OF"、"HAS NONE OF"、"IS NULL"、"IS NOT NULL"
list<int64>
关联的工作项id列表
多选关联工作项
workitem_related_multi_select
"="、"!="、"HAS ANY OF"、"HAS NONE OF"、"IS NULL"、"IS NOT NULL"
list<int64>
关联的工作项id列表
日期时间
precise_date
"<"、">"、"<="、">="、"IS NULL"、"IS NOT NULL"
int64
要实现在区间的操作符，需重复传入时间参数两次，通过大于小于操作符的组合实现过滤
日期
date
"<"、">"、"<="、">="、"IS NULL"、"IS NOT NULL"
int64

常用查询请求体示例

查询需求下指定状态，且创建时间在某个区间的工作项列表。

{
    "page_size":50,
    "page_num":1,
    "search_group":{
        "conjunction":"AND",
        "search_params":[
            {
                "param_key":"created_at",
                "value":1654064482000,
                "operator":">"
            },
            {
                "param_key":"created_at",
                "value":1654063482000,
                "operator":"<"
            },
            {
                "param_key":"sub_stage",
                "value":["start"],
                "operator":"="
            }
        ]
    }
}

查询需求下包含指定人员的所有工作项

{
    "page_size":50,
    "page_num":1,
    "search_group":{
        "conjunction":"AND",
        "search_params":[
            {
                "param_key":"people",
                "value":["XXX"],
                "operator":"HAS ANY OF"
            }
        ]
    }
}

通过需求id查询指定的需求

{
    "page_size":50,
    "page_num":1,
    "search_group":{
        "conjunction":"AND",
        "search_params":[
            {
                "param_key":"work_item_id",
                "value":[12345,45678],
                "operator":"HAS ANY OF"
            }
        ]
    }
}

查询一个需求下关联的所有缺陷，(使用_field_linked_story)，路径参数的工作项类型需指定缺陷

{
    "page_size":50,
    "page_num":1,
    "search_group":{
        "conjunction":"AND",
        "search_params":[
            {
                "param_key":"_field_linked_story",
                "value":[12345],
                "operator":"="
            }
        ]
    }
}

查询一段时间内更新的工作项

{
    "page_size":50,
    "page_num":1,
    "search_group":{
        "conjunction":"AND",
        "search_params":[
            {
                "param_key":"updated_at",
                "value": 1654064482000,
                "operator":">"
            },
            {
                "param_key":"updated_at",
                "value": 1657064482000,
                "operator":"<"
            }
        ]
    }
}

查询角色A存在指定人员且角色B存在指定人员的工作项

{
    "search_group":{
        "conjunction":"AND",
        "search_params":[
            {
                "param_key":"role_owners",
                "value":[
                    {
                    "role":"A",
                    "owners":["XXX"]
                },
                {
                    "role":"B",
                    "owners":["XXX"]
                }
                ],
                "operator":"HAS ANY OF"
            }
        ]
    }
}

查询节点「开始」存在指定负责人且节点「进行中」存在指定负责人的工作项

{
    "search_group":{
        "conjunction":"AND",
        "search_params":[
            {
                "param_key":"node_owners",
                "value":[
                    {
                    "state_name":"开始",
                    "owners":["XXX"]
                },
                {
                    "state_name":"进行中",
                    "owners":["XXX"]
                }
                
                ],
                "operator":"HAS ANY OF"
            }
        ]
    }
}

查询使用了某个template的工作项

{
    "search_group":{
        "conjunction":"AND",
        "search_params":[
            {
                "param_key":"template_id",
                "value":[123,456],
                "operator":"HAS ANY OF"
            }
        ]
    }
}

查询除了终止和结束状态的需求(终止状态默认不返回，所以不需要传closed)

{
    "search_group":{
        "conjunction":"AND",
        "search_params":[
            {
                "param_key":"work_item_status",
                "value":["end"],
                "operator":"!="
            }
        ]
    }
}'

查询业务线等于某个值且角色 PM 的人员等于指定人员，或者不存在优先级属于 P2 的工作项。

{
    "search_group":{
        "conjunction":"AND",
        "search_params":[
            {
                "param_key":"business",
                "value":["xxx"],
                "operator":"="
            },
            {
                "param_key":"role_owners",
                "value":[{
                    "role":"pm",
                    "owners":["xxx"]
                }],
                "operator":"="
            }
        ],
        "search_groups":[
            {
                "conjunction":"OR",
                "search_params":[
                    {
                        "param_key":"priority",
                        "value":["2"],
                        "operator":"HAS NONE OF"
                    }
                ]
            }
        ]
    }
}