Skip to content

查询各周期的完成情况 ​

按计划 ID 和时间范围查询各周期的完成、未完成数量,周期状态和跳过原因。range_limit.truncated 为 true 时按 next_end_time 继续查询;只读,不创建或修改计划。

请求 ​

text
POST https://open.cli.im/api/v2/rpc/cycleTasks/getCompletion
项目要求
最低权限只读,见权限档位
需要的 scoperecords.read
组织 Key不能调用,返回 403 credential_type_not_allowed,见历史组织 Key

请求参数 ​

请求体为 JSON。

字段类型必填说明
project_idinteger否计划所在分区 ID,0 为默认分区。默认 0
plan_idstring是周期计划 ID,取自 cyclePlans/list
start_timestring是查询范围的开始时间,格式 YYYY-MM-DD HH:mm:ss,如 2026-11-18 00:00:00
end_timestring是查询范围的结束时间,格式 YYYY-MM-DD HH:mm:ss,如 2026-11-18 23:59:59;与开始时间最多相隔 366 天
period_limitinteger否最多返回的周期数,默认 60,最大 120。默认 60。范围 1–120
plan_scopestring否计划所处阶段:running(默认)已启用且未结束,包含 active 和 not_started;active 已开始且生效中;not_started 已启用但未到开始时间;closed 已暂停;finished 计划已结束(不代表各周期的任务都已完成)。它与 cycleTasks/listQrcodes 的 status(某个周期内各码的完成状态)不是同一个概念。可选值:running、active、not_started、closed、finished。默认 "running"

请求示例 ​

示例里的 ID、幂等键等换成实际值。

bash
curl -sS -X POST 'https://open.cli.im/api/v2/rpc/cycleTasks/getCompletion' \
  -H "Authorization: Bearer ${CAOLIAO_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
  "project_id": 0,
  "plan_id": "40021",
  "start_time": "2026-11-17 00:00:00",
  "end_time": "2026-11-18 23:59:59"
}'

响应 ​

成功时 HTTP 状态码为 200,顶层 code 为 0,结果在 data 里。失败时的返回见错误码与调用额度和业务错误码。

字段类型一定返回说明
data.planobject是计划概况
data.plan.plan_idany否周期计划 ID
data.periodsobject[]是时间范围内的各个周期。空数组不代表全部完成
data.periods[].period_keystring是周期标识。查询该周期内各码的执行情况时原样传给 cycleTasks/listQrcodes
data.periods[].labelstring否周期名称
data.periods[].short_labelstring否周期简称
data.periods[].weekdayany否周期对应的星期
data.periods[].start_timestring否周期开始时间
data.periods[].end_timestring否周期结束时间
data.periods[].period_statestring否周期状态
data.periods[].is_skippedboolean否该周期是否被跳过(如节假日)
data.periods[].skip_reasonstring否跳过原因;未跳过时为空字符串
data.periods[].required_timesinteger否该周期要求完成的次数
data.periods[].time_slotsany[]否周期内的执行时段
data.periods[].total_code_countinteger否计划覆盖的码数量
data.periods[].should_check_code_countinteger否该周期应执行的码数量
data.periods[].finished_code_countinteger否已完成的码数量
data.periods[].unfinished_code_countinteger否未完成的码数量
data.periods[].skip_code_countinteger否无需执行的码数量
data.periods[].finish_percentnumber否完成比例
data.periods[].code_status_countsany否按码状态统计的数量
data.periods[].code_status_detail_countsany否按码状态明细统计的数量
data.range_limitobject是结果是否被截断
data.range_limit.max_periodsinteger是本次最多返回的周期数
data.range_limit.truncatedboolean是是否还有更早的周期没有返回
data.range_limit.covered_start_timeany否本次结果覆盖的开始时间
data.range_limit.covered_end_timeany否本次结果覆盖的结束时间
data.range_limit.next_end_timestring是truncated 为 true 时,把它作为下一次请求的 end_time 继续查询更早的周期

响应示例 ​

json
{
  "code": 0,
  "message": "ok",
  "data": {
    "plan": {
      "plan_id": "40021"
    },
    "periods": [
      {
        "period_key": "2026-11-18",
        "label": "11月18日",
        "start_time": "2026-11-18 00:00:00",
        "end_time": "2026-11-18 23:59:59",
        "period_state": "in_progress",
        "is_skipped": false,
        "skip_reason": "",
        "required_times": 1,
        "total_code_count": 12,
        "should_check_code_count": 12,
        "finished_code_count": 9,
        "unfinished_code_count": 3,
        "skip_code_count": 0,
        "finish_percent": 75
      }
    ],
    "range_limit": {
      "max_periods": 60,
      "truncated": false,
      "covered_start_time": "2026-11-17 00:00:00",
      "covered_end_time": "2026-11-18 23:59:59",
      "next_end_time": null
    }
  }
}

常见错误 ​

PERMISSION_DENIED、CYCLE_QUERY_REJECTED、CYCLE_QUERY_UNAVAILABLE。含义和处理方式见业务错误码。


本页由 openapi.json 生成。全部接口见接口清单。