分页查询某个周期内各码的执行情况
按码分页返回某个周期内各码的执行情况。period_key 先从 cycleTasks/getCompletion 取得并原样传入;status 筛选的是该周期的任务状态,与筛选计划生命周期的 plan_scope 不同。
请求
text
POST https://open.cli.im/api/v2/rpc/cycleTasks/listQrcodes| 项目 | 要求 |
|---|---|
| 最低权限 | 只读,见权限档位 |
| 需要的 scope | records.read |
| 组织 Key | 不能调用,返回 403 credential_type_not_allowed,见历史组织 Key |
请求参数
请求体为 JSON。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
project_id | integer | 否 | 计划所在分区 ID,0 为默认分区。默认 0 |
plan_id | string | 是 | 周期计划 ID,取自 cyclePlans/list |
plan_scope | string | 否 | 计划所处阶段:running(默认)已启用且未结束,包含 active 和 not_started;active 已开始且生效中;not_started 已启用但未到开始时间;closed 已暂停;finished 计划已结束(不代表各周期的任务都已完成)。它与 cycleTasks/listQrcodes 的 status(某个周期内各码的完成状态)不是同一个概念。可选值:running、active、not_started、closed、finished。默认 "running" |
period_key | string | 是 | 周期标识,原样使用 cycleTasks/getCompletion 返回的 period_key,不要自行拼接。最长 128 个字符 |
status | string | 否 | 按该周期内各码的完成状态筛选:all(默认)全部;finished 已完成;unfinished 未完成(包含 not_started、in_progress、expired_unfinished);no_need 无需执行;expired_unfinished 逾期未完成;in_progress 进行中;not_started 未开始。可选值:all、finished、unfinished、no_need、expired_unfinished、in_progress、not_started。默认 "all" |
page | integer | 否 | 页码,从 1 开始。默认 1。范围 1–10000 |
page_size | integer | 否 | 每页条数。默认 20。范围 1–100 |
请求示例
示例里的 ID、幂等键等换成实际值。
bash
curl -sS -X POST 'https://open.cli.im/api/v2/rpc/cycleTasks/listQrcodes' \
-H "Authorization: Bearer ${CAOLIAO_API_KEY}" \
-H 'Content-Type: application/json' \
-d '{
"project_id": 0,
"plan_id": "40021",
"period_key": "2026-11-18",
"status": "unfinished",
"page": 1,
"page_size": 20
}'响应
成功时 HTTP 状态码为 200,顶层 code 为 0,结果在 data 里。失败时的返回见错误码与调用额度和业务错误码。
| 字段 | 类型 | 一定返回 | 说明 |
|---|---|---|---|
data.list | object[] | 是 | 各码的执行情况 |
data.list[].code_id | string | 是 | 码 ID |
data.list[].code_name | string | 否 | 码名称 |
data.list[].code_number | any | 否 | 码编号 |
data.list[].code_status | any | 否 | 该码在这个周期的状态 |
data.list[].code_status_detail | any | 否 | 更细的状态 |
data.list[].code_status_text | string | 否 | 状态文字 |
data.list[].finished_times | any | 否 | 已完成次数 |
data.list[].required_times | any | 否 | 要求完成次数 |
data.list[].configured_required_times | any | 否 | 计划配置的要求次数 |
data.list[].effective_required_times | any | 否 | 实际生效的要求次数 |
data.list[].times | object[] | 是 | 各执行时段的情况 |
data.list[].times[].seq | any | 否 | 时段序号 |
data.list[].times[].task_instance_id | any | 否 | 任务实例 ID |
data.list[].times[].execute_status | any | 否 | 执行状态 |
data.list[].times[].execute_status_text | any | 否 | 执行状态文字 |
data.list[].times[].real_execute_time | any | 否 | 实际执行时间 |
data.list[].times[].start_time | any | 否 | 时段开始时间 |
data.list[].times[].end_time | any | 否 | 时段结束时间 |
data.list[].times[].is_applicable | any | 否 | 该时段是否需要执行 |
data.list[].times[].skip_reason | any | 否 | 无需执行的原因 |
data.list[].times[].record_id | any | 否 | 对应的填写记录 ID;没有填写记录时为空 |
data.list[].times[].auto_rule_id | any | 否 | 自动判定完成的规则 ID |
data.list[].times[].auto_reason | any | 否 | 自动判定完成的原因 |
data.pagination | object | 是 | 分页信息 |
data.pagination.page | integer | 是 | 当前页码,从 1 开始 |
data.pagination.page_size | integer | 是 | 每页条数 |
data.pagination.total | integer | 是 | 符合条件的总条数 |
data.pagination.has_more | boolean | 是 | 是否还有下一页。为 true 时即使当前页为空也应继续翻页 |
data.period_key | string | 是 | 本次查询的周期标识 |
data.status | string | 是 | 本次查询使用的状态筛选 |
响应示例
json
{
"code": 0,
"message": "ok",
"data": {
"list": [
{
"code_id": "7001234",
"code_name": "1 号空压机",
"code_status": "unfinished",
"code_status_detail": "not_started",
"code_status_text": "未开始",
"finished_times": 0,
"required_times": 1,
"times": [
{
"seq": 1,
"execute_status": "not_started",
"start_time": "2026-11-18 00:00:00",
"end_time": "2026-11-18 23:59:59",
"is_applicable": true,
"record_id": null
}
]
}
],
"pagination": {
"page": 1,
"page_size": 20,
"total": 3,
"has_more": false
},
"period_key": "2026-11-18",
"status": "unfinished"
}
}常见错误
PERMISSION_DENIED、CYCLE_QUERY_REJECTED、CYCLE_QUERY_UNAVAILABLE。含义和处理方式见业务错误码。
本页由 openapi.json 生成。全部接口见接口清单。