97 KiB
轮询按运营商账户限流:前端接口变更说明
更新日期:2026-10-26
适用分支:Iteration/8-11(测试环境已部署)
对应方案:docs/engineering/轮询按运营商账户限流技术方案.md 第五部分第 3 节的 7 个提案
本文给前端工程师用:列出这次方案新增、改动和废弃的后台接口,以及每个页面要改什么。字段级定义以接口文档(/api/admin 的 OpenAPI)为准,本文附录列出了全部新增接口的字段表,由接口文档直接生成。
- 新增接口 46 个,删除 0 个,改动 16 个(与方案开始前的代码逐接口对比得出)。
- 所有接口都要登录。列表接口分页参数统一为
page、page_size(最大 100),返回items、total、page、size。 - "仅超级管理员" 的修改接口,其他账号调用返回 403;"仅平台账号" 指超级管理员与平台账号可用。
- 枚举优先从
GET /polling-options取;不在其中的(见第 9 节)以本文与接口文档的说明为准。
1. 需要新增和改造的页面一览
| 页面 | 类型 | 主要接口 | 对应章节 |
|---|---|---|---|
| 网关限流组 | 新增 | /polling-rate-limit-groups |
2.1 |
| 上游错误分类规则(含测试) | 新增 | /gateway-error-classifications |
2.2 |
| 停复机记录 | 新增 | /card-stop-resume-records、/iot-cards/:id/stop-resume-records |
2.3 |
| 网关调用监控(按运营商账户) | 新增 | /polling-stats/carriers、/polling-stats/carriers/:carrier_id/trend |
2.4 |
| 轮询配置 | 改造 | /polling-configs 及匹配预览、优先级、重算到期 |
3 |
| 分层与重置日前统计 | 新增 | /polling-stats/tiers、/polling-stats/pre-reset |
3.4 |
| 资产详情(后台与 C 端) | 改造 | 去掉保护期展示 | 4 |
| 停复机规则演练 | 新增 | /stop-resume-rule/dry-run |
5 |
| 运营商账户调度参数 | 新增 | /polling-carrier-params |
6.1 |
| 请求检查场景 | 新增 | /polling-check-scenes |
6.2 |
| 失败告警(含账户汇总、停机被拒视图) | 新增 | /polling-failure-alerts |
6.3、8.5 |
| 按账户轮询队列监控 | 新增 | /polling-stats/carrier-queues |
6.4、7 |
| 单卡轮询状态(排查用) | 新增 | /iot-cards/:id/polling-state |
6.5、7 |
| 系统配置 | 改造 | /system-configs 增加 polling 模块 |
9 |
| 不轮询清单 | 新增 | /card-polling-pauses |
8.3 |
| 轮询开关文件导入 | 新增 | /polling-status-imports |
8.2 |
| 卡列表、设备列表 | 改造 | 是否轮询筛选与列、批量开关轮询 | 8.1、8.4 |
| 轮询并发配置 | 保留、加提示 | /polling-concurrency |
6.6 |
2. 网关限流与停复机记录(第 1 个提案)
2.1 网关限流组页面(新增)
| 接口 | 说明 |
|---|---|
GET /polling-rate-limit-groups |
列表 |
GET /polling-rate-limit-groups/:id |
详情 |
POST /polling-rate-limit-groups |
新建(仅超级管理员) |
PUT /polling-rate-limit-groups/:id |
修改(仅超级管理员) |
PUT /polling-rate-limit-groups/:id/status |
启停(仅超级管理员),status:1 启用、0 停用 |
DELETE /polling-rate-limit-groups/:id |
删除(仅超级管理员) |
carrier_id为空表示全局组(各账户合计);有值表示该运营商账户的组。operations取值见GET /polling-options的gateway_operations(查流量、查状态、查实名、停机、复机)。- 限流是否真正拦截由系统配置
polling.gateway.rate_limit_mode决定(observe只统计、enforce拦截,见第 9 节),页面上建议展示当前模式。
2.2 上游错误分类规则页面(新增)
| 接口 | 说明 |
|---|---|
GET /gateway-error-classifications |
列表 |
POST /gateway-error-classifications |
新建(仅超级管理员) |
PUT /gateway-error-classifications/:id |
修改(仅超级管理员) |
PUT /gateway-error-classifications/:id/status |
启停(仅超级管理员) |
DELETE /gateway-error-classifications/:id |
删除(仅超级管理员) |
POST /gateway-error-classifications/test |
测试:输入操作与上游返回信息,返回命中的分类,不写数据 |
- 类别(
category)取值见GET /polling-options的error_categories;匹配方式见match_types。 - "自动关闭轮询"只对终态类别生效。
2.3 停复机记录页面(新增)
| 接口 | 说明 |
|---|---|
GET /card-stop-resume-records |
全部记录,时间范围必填,跨度不超过 31 天 |
GET /iot-cards/:id/stop-resume-records |
单卡历史(可放在卡详情或告警详情里,用于查看最近停复机记录) |
- 结果、动作取值见
GET /polling-options的stop_resume_results、stop_resume_actions。
2.4 网关调用监控(新增)
| 接口 | 说明 |
|---|---|
GET /polling-stats/carriers |
按运营商账户汇总最近若干分钟的网关调用(成功率、QPS、耗时、错误类别) |
GET /polling-stats/carriers/:carrier_id/trend |
单个账户的分钟级趋势 |
GET /polling-options |
本方案后台页面用的枚举(操作、错误类别、匹配方式、限流模式、豁免来源、停复机结果与动作) |
3. 轮询配置改造(第 2 个提案:分层轮询)
3.1 字段变化:POST /polling-configs、PUT /polling-configs/:id、列表与详情
| 变化 | 字段 | 说明 |
|---|---|---|
| 新增 | asset_status |
资产状态匹配(1 在库、2 已销售、3 已换货、4 已停用),为空不限 |
| 新增 | package_state |
套餐状态匹配(active 有生效套餐、depleted 已用完、pending 只有待生效、none 无套餐),为空不限 |
| 新增 | pre_reset_window、pre_reset_carddata_interval |
重置日前加密:窗口长度与窗口内流量检查间隔(秒),两者同时配置才生效 |
| 新增(仅修改接口) | clear_fields |
要清空为空值的字段名列表:间隔清空即改为继承,匹配条件清空即不限 |
| 新增(返回) | warnings |
保存提示(如与其他配置优先级相同且条件可能重叠),不影响保存结果,页面应展示 |
| 删除 | protect_check_interval |
保护期已下线,请求与返回都不再有该字段,页面去掉该输入项 |
| 含义变化 | 四个检查间隔 *_check_interval |
三态:正数按间隔;0 不检查且不再继承;不传或为空继承优先级更低的配置。页面要能区分"0"和"空" |
3.2 匹配预览(新增)
| 接口 | 说明 |
|---|---|
GET /polling-configs/match-preview?iccid= |
按当前已保存配置,预览某张卡命中哪些配置、各检查类型的最终间隔 |
POST /polling-configs/match-preview |
同上,但可带未保存的修改(overrides),用于编辑弹窗里"保存前预览",不写数据 |
3.3 优先级与重算到期(新增)
| 接口 | 说明 |
|---|---|
PUT /polling-configs/priorities |
整体调整优先级(拖拽排序后提交 ordered_ids),仅超级管理员 |
POST /polling-configs/recalculate-due |
立即重算轮询到期时间(可按运营商账户),异步,只提前不推后,仅超级管理员;返回 task_id |
GET /polling-configs/recalculate-due/:task_id |
查询重算进度 |
3.4 统计(新增)
| 接口 | 说明 |
|---|---|
GET /polling-stats/tiers |
各层卡数、漏配告警卡数(结果缓存 5 分钟) |
GET /polling-stats/pre-reset |
重置日前加密效果:按账户统计窗口内未查到流量的卡数、最后一次查询距重置时刻分布 |
4. 保护期下线(第 3 个提案)
device_protect_status字段保留但已废弃,固定返回none,涉及:GET /assets/resolve/:identifierGET /assets/:identifier/realtime-statusPOST /assets/:identifier/refresh- C 端
GET /api/c/v1/asset/info
- 前端:后台资产详情与 C 端去掉保护期状态的展示;轮询配置去掉保护期间隔(见 3.1)。
5. 停复机规则演练(第 4 个提案)
| 接口 | 说明 |
|---|---|
GET /stop-resume-rule/dry-run |
对全部卡按停复机新规则只判断不执行:按运营商账户 × 当前停机原因 × 判断结果的汇总,加分页明细;可传"假设的实名管控配置"预演;仅平台账号 |
POST /stop-resume-rule/dry-run/export |
导出明细(导出场景 stop_resume_rule_dry_run),筛选与假设配置同演练接口 |
- 运营商账户的"实名管控"开关(
realname_control_enabled)在运营商账户编辑里(PUT /carriers/:id)。从 0 改为 1 时必须带realname_control_confirm=true,否则接口返回提示文案(含将被停机的卡数),前端应把这段提示作为二次确认展示,确认后带上参数重新提交。
6. 按运营商账户调度(第 5 个提案)
6.1 运营商账户调度参数页面(新增)
| 接口 | 说明 |
|---|---|
GET /polling-carrier-params |
全部运营商账户的生效参数;未单独配置的账户返回全局默认并标记 is_default |
GET /polling-carrier-params/:carrier_id |
单个账户 |
PUT /polling-carrier-params/:carrier_id |
保存(仅超级管理员)。字段为空表示该项用全局默认;执行上限不得大于订阅进程 max_in_flight 之和,超出会被拒绝 |
DELETE /polling-carrier-params/:carrier_id |
删除,恢复全局默认(仅超级管理员) |
字段:inflight_limit、card_max_in_flight(卡任务执行上限与每进程并发),sr_inflight_limit、stop_resume_max_in_flight(停复机执行上限与每进程并发),priority_max_ratio(优先队列最大占比),stop_resume_min_interval(单卡两次停复机调用最小间隔,秒),stop_resume_confirm_delay(停复机结果未知后的确认延迟,秒)。
6.2 请求检查场景页面(新增)
| 接口 | 说明 |
|---|---|
GET /polling-check-scenes |
全部场景(代码预置 8 个:订单支付、套餐激活、停复机成功、设备操作、自动续费购包、C 端资产详情、后台资产实时状态、实名链接) |
PUT /polling-check-scenes/:scene |
修改(仅超级管理员):只可改检查类型、延迟确认序列(递增)与冷却时长 |
6.3 失败告警页面(新增)
| 接口 | 说明 |
|---|---|
GET /polling-failure-alerts |
列表,可按运营商账户、检查类型、错误类别、状态、告警级别、ICCID、时间筛选;view=stop_refused 见 8.5 |
GET /polling-failure-alerts/summary |
未处理告警按运营商账户 × 错误类别汇总(账户汇总视图) |
GET /polling-failure-alerts/:id |
详情;需要看该卡最近的停复机记录时调 GET /iot-cards/:id/stop-resume-records |
PUT /polling-failure-alerts/:id/status |
标记已处理(只有未处理的告警可以标记) |
POST /polling-failure-alerts/close-polling |
勾选告警批量关闭对应卡的轮询,见 8.5 |
- 告警级别:
card卡级、carrier账户级(窗口内同账户告警数超过阈值时产生,card_id为 0)。 - 检查类型:
card_status、carddata、realname、package、stop_resume(停复机,第 6 个提案新增)、all(账户级)。 - 状态:1 未处理、2 已恢复(首次成功后自动转入)、3 已关闭轮询、4 已处理。
6.4 按账户轮询队列监控(新增)
GET /polling-stats/carrier-queues:调度模式、新结构初始化状态,以及每个运营商账户的队列长度、已到期、执行中、执行上限、上一分钟 QPS、限流等待与拒绝、近 1 小时处理中标记到期次数、未处理告警数(含按错误类别)。停复机相关字段见第 7 节。
6.5 单卡轮询状态(新增,排查用)
GET /iot-cards/:id/polling-state:卡所在队列、下次可领取时间、是否执行中、各检查类型的下次到期、最近成功、连续失败与最近错误、待执行的延迟确认。停复机相关字段见第 7 节。建议放在卡详情的"轮询"页签。
6.6 轮询并发配置页面(保留)
/polling-concurrency 仍然存在,但只对旧分片调度(polling.scheduler.mode = legacy)生效,新调度下修改没有效果。页面上请加提示:"仅旧调度生效,按运营商账户调度时请使用运营商账户调度参数"。该页面会在旧调度代码下线时一并删除。
6.7 调度模式切换
通过系统配置 polling.scheduler.mode(legacy / carrier)切换,GET /polling-stats/init-progress(原有接口)查看新结构初始化进度。
7. 停复机指令队列(第 6 个提案)
没有新增接口,只在已有接口上加字段:
- 全局开关:系统配置
polling.stop_resume.queue_enabled(默认关闭)。开启后自动停复机经指令队列执行;关闭即回到各入口当场执行。 GET /polling-stats/carrier-queues每个账户新增:
| 字段 | 说明 |
|---|---|
stop_resume_queue_length |
停复机指令队列长度 |
stop_resume_due |
已到期指令数 |
stop_resume_running |
执行中指令数 |
stop_resume_pending |
结果未知待确认的指令数(按队列前 500 条统计) |
stop_resume_success_1h、stop_resume_failed_1h、stop_resume_retry_1h、stop_resume_unknown_1h |
近 1 小时成功、失败、推后重试、结果未知次数 |
GET /iot-cards/:id/polling-state新增:
| 字段 | 说明 |
|---|---|
stop_resume_queue_enabled |
停复机出口开关是否开启 |
stop_resume_command |
当前停复机指令,没有时为 null:action(stop / start)、reason、scenes、source、version、fail_count、last_error、pending(结果未知待确认)、unknown、written_at、next_at(下次可执行时间,受单卡最小间隔约束) |
last_stop_resume_call_at |
最近一次停复机网关调用时间 |
- 失败告警的检查类型新增
stop_resume(见 6.3)。
8. 不轮询清单与批量开关轮询(第 7 个提案)
8.1 卡列表、设备列表:批量开关轮询(新增)
| 接口 | 说明 |
|---|---|
POST /iot-cards/batch-update-polling-status |
勾选卡批量开关轮询 |
POST /devices/batch-update-polling-status |
勾选设备批量开关轮询(级联到设备下各卡) |
请求:asset_ids(1~500 个,不能重复)、enable_polling(true 开启、false 关闭)、reason(必填,写入不轮询清单)。
返回:success_count、skip_count、fail_count、items(逐项结果)、impact(本次目标状态的影响说明)。逐项 status:
| 值 | 含义 | 典型 reason |
|---|---|---|
| 1 | 成功 | |
| 2 | 跳过 | "已是目标状态"、"已销户,不能开启轮询"、"风险停机,不能开启轮询" |
| 3 | 失败 | 具体错误信息 |
| 4 | 无权限或资产不存在 | "无权限操作该资产或资产不存在" |
- 部分成功不会回滚,请把逐项结果展示给用户(例如结果弹窗按状态分组)。
- 企业账号调用返回 403;代理账号只能操作本店及下级店铺的资产。
- 超过 500 个或 ID 重复直接返回参数错误。
8.2 轮询开关文件导入(新增,仅平台账号)
流程:
POST /storage/upload-url,purpose传polling_status_import(新增用途),文件名用.csv,拿到upload_url和file_key。- 用
PUT把 CSV 传到upload_url。CSV 格式:首行为表头,首列为 ICCID(卡,19 位或 20 位都可以)或 IMEI/虚拟号(设备),空行忽略,最多 50000 行。 POST /polling-status-imports:file_key(必须以polling-status-imports/开头)、asset_type(iot_card/device)、enable_polling、reason。返回任务(状态 1 待处理)。GET /polling-status-imports看任务列表与进度(状态:1 待处理、2 处理中、3 已完成、4 失败);GET /polling-status-imports/:id看逐行结果items(line、identifier、asset_id、status、status_name、reason,状态取值同 8.1)。
- 逐行处理规则与勾选批量相同,每行独立,部分成功不回滚;任务级失败(文件不是 CSV、编码无法识别、没有数据行等)看
error_message。
8.3 不轮询清单页面(新增,仅平台账号)
GET /card-polling-pauses,筛选参数:
| 参数 | 说明 |
|---|---|
asset_type |
iot_card / device |
carrier_id |
卡所属运营商账户 |
source |
关闭来源,取值见下表 |
status |
1 已关闭、2 已恢复 |
identifier |
ICCID 或 IMEI(精确) |
operator_id |
关闭操作人账号 ID |
start_time、end_time |
关闭时间范围(带时区的 RFC3339 秒级时间) |
返回每条记录:资产类型与 ID、identifier、运营商账户(carrier_id、carrier_name)、资产当前 enable_polling、卡当前 gateway_extend、status/status_name、close_source/close_source_name、close_reason、closed_by/closed_by_name、closed_at、import_task_id、restore_source/restore_source_name、restore_reason、restored_by/restored_by_name、restored_at。系统操作时操作人为 0(展示"系统")。
来源取值(关闭来源与恢复来源共用):
| 值 | 名称 |
|---|---|
single |
单资产接口 |
batch |
勾选批量 |
import |
文件导入 |
risk_auto |
风险停机或已销户自动关闭 |
cascade |
设备级联 |
order |
支付或下单生效(自动恢复) |
expiry_change |
改有效期(自动恢复) |
alert |
停机被拒告警处理 |
history |
历史数据(上线时补写的存量) |
- 每个资产同时只有一条"已关闭"记录;恢复后该记录标为"已恢复"并保留,再次关闭会新增一条,所以同一资产可能有多条历史。
- 列表勾选批量开启:直接复用 8.1 的批量接口(
enable_polling=true)。 - 导出:统一导出任务,场景
polling_pause,query.filters与本接口筛选参数相同。
8.4 卡列表、设备列表的改动
| 接口 | 变化 |
|---|---|
GET /iot-cards/standalone |
新增筛选参数 enable_polling(true 轮询中、false 已关闭,不传不过滤);返回原本就有 enable_polling |
GET /devices |
新增筛选参数 enable_polling;返回新增字段 enable_polling |
卡导出(场景 iot_card)、设备导出(场景 device) |
支持 enable_polling 筛选;导出文件最后一列新增「是否轮询」 |
PATCH /assets/:identifier/polling-status(单资产开关,原有) |
行为变化:网关扩展状态为风险停机或已销户的卡不能开启,返回 403;开关会写入不轮询清单(来源"单资产接口") |
8.5 失败告警:停机被拒视图与批量关闭轮询(新增)
GET /polling-failure-alerts?view=stop_refused:停复机方向为停机,且错误类型为终态或业务错误、或停机失败次数达到阈值的告警。- 这个视图只认
carrier_id、status、iccid、start_time、end_time筛选,会忽略check_type、error_category、alert_level,页面切到该视图时请隐藏这三个筛选项。 - 额外返回:
device_id(所属设备)、network_status、stop_reason、enable_polling(是否已关闭轮询)、has_package(是否有生效套餐)、handled_by_name。上游返回信息在last_error中。 - 导出:统一导出任务,场景
polling_stop_refused_alert,query.filters为carrier_id、status、iccid、start_time、end_time。
- 这个视图只认
POST /polling-failure-alerts/close-polling(仅平台账号):alert_ids(1~500)、reason。关闭告警对应卡本身的轮询(清单来源"停机被拒告警处理"),成功或已关闭的告警状态改为"已关闭轮询"。返回格式同 8.1;不存在或不是卡级告警的 ID 以asset_id=0、状态 4 返回。
8.6 开关轮询的确认框文案
GET /polling-status/impact 返回 disable(关闭的影响)与 enable(开启的影响)两组文案,前端在关闭、开启轮询的确认框中直接展示,不要写死。批量接口的返回 impact 是同一份内容。
关闭的影响(当前内容):不再查询上游;流量用完、实名不满足不自动停机,套餐激活、流量重置后不自动复机;套餐到期、退款后无可用套餐仍会停机;订单套餐生效、后台改有效期后有生效套餐会自动恢复轮询并按规则复机;人工停复机照常;设备关闭时设备下所有卡同样适用。
8.7 自动恢复轮询(无接口变化,影响页面展示)
以下操作会自动把已关闭轮询的卡或设备恢复轮询(风险停机、已销户的卡除外),清单里能看到对应的恢复来源,页面不需要额外处理:
- 订单套餐生效:客户支付成功、后台下单、批量下单、OpenAPI 钱包下单(来源
order); - 后台修改套餐有效期后资产有未到期的生效套餐(来源
expiry_change)。
9. 系统配置(/system-configs)新增 polling 模块
GET /system-configs?module=polling 可列出以下配置,修改用 PUT /system-configs/:key(JSON 类配置会做结构校验,非法时返回错误说明)。
| 配置键 | 类型 | 默认 | 说明 |
|---|---|---|---|
polling.gateway.rate_limit_mode |
string | observe |
网关限流模式:observe 只统计不拦截,enforce 拦截 |
polling.gateway.default_qps |
int | 10 | 未被启用限流组覆盖的卡网关操作的默认每秒请求上限 |
polling.gateway.rate_limited_retry_delay_seconds |
int | 5 | 任务遇限流后的固定重试延迟(秒) |
polling.gateway.rate_limit_defer_alert_seconds |
int | 600 | 同一任务因限流累计推迟超过该时长时写告警 |
polling.stop_resume_record.retention_months |
int | 6 | 停复机记录保留月数 |
polling.stop_resume_record.premake_months |
int | 3 | 停复机记录提前创建未来分区的月数 |
polling.scheduler.mode |
string | legacy |
调度模式:legacy 旧分片调度,carrier 按运营商账户调度 |
polling.scheduler.step_order |
json | ["card_status","carddata","realname","package"] |
卡任务步骤顺序 |
polling.scheduler.step_timeout_seconds |
json | {"card_status":15,"carddata":15,"realname":15,"package":20} |
各检查类型单步超时(秒) |
polling.scheduler.task_timeout_margin_seconds |
int | 10 | 卡任务总超时余量(秒) |
polling.scheduler.skip_package_after_flow |
bool | true | 同轮流量步骤已触发停复机评估时跳过套餐步骤 |
polling.failure.backoff_seconds |
json | {"default":[60,300,900,1800,3600]} |
失败退避序列(秒,递增),可按检查类型覆盖 |
polling.failure.alert_fail_count |
json | {"default":5} |
连续失败告警阈值,可按检查类型覆盖 |
polling.failure.alert_fail_duration_seconds |
int | 21600 | 持续失败时长告警阈值(秒) |
polling.failure.immediate_alert_categories |
json | ["account_config"] |
首次出现即告警的错误类别 |
polling.failure.account_alert_window_seconds |
int | 600 | 账户级告警统计窗口(秒) |
polling.failure.account_alert_threshold |
int | 50 | 账户级告警阈值 |
polling.stop_resume.queue_enabled |
bool | false | 自动停复机经停复机指令队列执行(全局开关) |
polling.stop_resume.unknown_alert_threshold |
int | 3 | 停复机连续结果未知告警阈值 |
polling.stop_resume.backoff_seconds |
json | [600,900,1800,3600] |
停复机失败退避序列(秒,递增) |
polling.stop_resume.alert_fail_count |
int | 5 | 停复机连续失败告警阈值 |
module 参数和返回的 module 枚举新增 polling。
10. 导出场景汇总
POST /export-tasks 的 scene、GET /export-tasks 的 scene 筛选新增:
| 场景 | 说明 | query.filters |
|---|---|---|
polling_pause |
不轮询清单(仅平台账号) | 同 GET /card-polling-pauses |
polling_stop_refused_alert |
停机被拒告警(仅平台账号) | carrier_id、status、iccid、start_time、end_time |
stop_resume_rule_dry_run |
停复机规则演练明细(第 4 个提案,建议走 POST /stop-resume-rule/dry-run/export) |
同演练接口 |
原有场景 iot_card、device 支持 enable_polling 筛选,导出最后一列新增「是否轮询」。历史导出任务重新导出时列不变。
11. 前端改动清单(按优先级)
- 轮询配置页:去掉保护期间隔;加资产状态、套餐状态、重置日前两个字段;间隔支持"0"与"空"两种;修改时支持
clear_fields;展示warnings;匹配预览与优先级拖拽;重算到期。(第 2 个提案上线即需要) - 资产详情(后台与 C 端):去掉保护期状态展示。(第 3 个提案)
- 运营商账户编辑:实名管控开关与 0→1 二次确认。(第 4 个提案)
- 系统配置页:支持
polling模块与 JSON 类配置的编辑。 - 新增页面:网关限流组、错误分类规则(含测试)、停复机记录、网关调用监控、停复机规则演练、运营商账户调度参数、请求检查场景、失败告警(含账户汇总)、按账户队列监控、单卡轮询状态。
- 卡列表、设备列表:是否轮询筛选与列、批量开关轮询(含逐项结果展示和确认框文案)。
- 不轮询清单页(筛选、导出、勾选批量开启)与文件导入页(上传、任务列表、逐行结果)。
- 失败告警页:停机被拒视图(切换时隐藏三个筛选项)、导出、勾选批量关闭轮询。
- 轮询并发配置页:加"仅旧调度生效"提示。
附录:新增接口字段表(由接口文档生成)
以下路径省略前缀 /api/admin。字段说明与接口文档一致;如有出入,以测试环境接口文档为准。
DELETE /gateway-error-classifications/{id} 删除上游错误分类规则(仅超级管理员)
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| path | id |
integer | 是 | ID |
DELETE /polling-carrier-params/{carrier_id} 删除运营商账户调度参数(恢复全局默认,仅超级管理员)
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| path | carrier_id |
integer | 是 | 运营商账户ID |
DELETE /polling-rate-limit-groups/{id} 删除网关限流组(仅超级管理员)
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| path | id |
integer | 是 | ID |
GET /card-polling-pauses 查询不轮询清单(仅平台账号)
每个资产只有一条已关闭记录,恢复后保留历史;导出使用统一导出任务,场景 polling_pause,筛选参数同本接口。
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| query | page |
integer | 页码 | |
| query | page_size |
integer | 每页数量 | |
| query | asset_type |
string | 资产类型 (iot_card:卡, device:设备) | |
| query | carrier_id |
integer | 卡所属运营商账户ID | |
| query | source |
string | 关闭来源 (single:单资产接口, batch:勾选批量, import:文件导入, risk_auto:风险停机或已销户自动关闭, cascade:设备级联, order:支付或下单生效, expiry_change:改有效期, alert:停机被拒告警处理, history:历史数据) | |
| query | status |
integer | 状态 (1:已关闭, 2:已恢复) | |
| query | identifier |
string | ICCID 或 IMEI(精确) | |
| query | operator_id |
integer | 关闭操作人账号ID | |
| query | start_time |
string | 关闭时间起始(带时区的 RFC3339 秒级时间) | |
| query | end_time |
string | 关闭时间结束(带时区的 RFC3339 秒级时间) |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
items |
array | 清单记录 |
items[].asset_id |
integer | 资产ID |
items[].asset_type |
string | 资产类型 (iot_card:卡, device:设备) |
items[].carrier_id |
integer | 卡所属运营商账户ID(设备为 0) |
items[].carrier_name |
string | 运营商账户名称 |
items[].close_reason |
string | 关闭原因 |
items[].close_source |
string | 关闭来源 |
items[].close_source_name |
string | 关闭来源名称 |
items[].closed_at |
string | 关闭时间 |
items[].closed_by |
integer | 关闭操作人账号ID(系统为 0) |
items[].closed_by_name |
string | 关闭操作人 |
items[].enable_polling |
boolean | 资产当前轮询开关 |
items[].gateway_extend |
string | 卡当前网关扩展状态(设备为空) |
items[].id |
integer | 记录ID |
items[].identifier |
string | ICCID 或 IMEI |
items[].import_task_id |
integer | 文件导入任务ID(非导入为 0) |
items[].restore_reason |
string | 恢复原因 |
items[].restore_source |
string | 恢复来源 |
items[].restore_source_name |
string | 恢复来源名称 |
items[].restored_at |
string | 恢复时间 |
items[].restored_by |
integer | 恢复操作人账号ID(系统为 0) |
items[].restored_by_name |
string | 恢复操作人 |
items[].status |
integer | 状态 (1:已关闭, 2:已恢复) |
items[].status_name |
string | 状态名称 |
page |
integer | 当前页 |
size |
integer | 每页数量 |
total |
integer | 总数 |
GET /card-stop-resume-records 查询停复机记录(时间范围必填,跨度不超过 31 天)
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| query | page |
integer | 页码 | |
| query | page_size |
integer | 每页数量 | |
| query | iccid |
string | ICCID | |
| query | carrier_id |
integer | 运营商账户ID | |
| query | action |
string | 动作 (stop:停机, start:复机) | |
| query | source |
string | 来源 | |
| query | result |
string | 结果 (success:成功, failed:失败, unknown:结果未知, already_target:已是目标状态, skipped:跳过) | |
| query | error_category |
string | 错误类别 | |
| query | start_time |
string | 是 | 开始时间(必填,RFC3339) |
| query | end_time |
string | 是 | 结束时间(必填,RFC3339,跨度不超过 31 天) |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
items |
array | 记录列表 |
items[].action |
string | 动作 (stop:停机, start:复机) |
items[].action_name |
string | 动作名称 |
items[].attempt |
integer | 尝试序号 |
items[].card_id |
integer | IoT卡ID |
items[].carrier_id |
integer | 运营商账户ID |
items[].command_id |
string | 停复机命令标识,同一命令的多次尝试相同 |
items[].created_at |
string | 记录时间 |
items[].duration_ms |
integer | 耗时(毫秒) |
items[].error_category |
string | 错误类别 |
items[].error_category_name |
string | 错误类别名称 |
items[].iccid |
string | ICCID |
items[].id |
integer | 记录ID |
items[].provider_code |
string | 上游返回码 |
items[].provider_message |
string | 上游返回信息(已截断) |
items[].reason |
string | 停机原因 |
items[].result |
string | 结果 (success:成功, failed:失败, unknown:结果未知, already_target:已是目标状态, skipped:跳过) |
items[].scene |
string | 场景 |
items[].source |
string | 来源 |
page |
integer | 当前页 |
size |
integer | 每页数量 |
total |
integer | 总数 |
GET /gateway-error-classifications 查询上游错误分类规则列表
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| query | page |
integer | 页码 | |
| query | page_size |
integer | 每页数量 | |
| query | category |
string | 类别筛选 (rate_limited_upstream:上游频率限制, terminal:终态不可操作, already_target:已是目标状态, transient:临时故障, business:业务错误, account_config:账户配置错误) | |
| query | status |
integer | 状态 (0:停用, 1:启用) | |
| query | keyword |
string | 关键字模糊搜索 |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
items |
array | 规则列表 |
items[].auto_disable_polling |
boolean | 命中后自动关闭该卡轮询 |
items[].category |
string | 类别 |
items[].category_name |
string | 类别名称 |
items[].created_at |
string | 创建时间 |
items[].id |
integer | 规则ID |
items[].keyword |
string | 匹配关键字或正则 |
items[].match_type |
string | 匹配方式 (contains:包含, prefix:前缀, regex:正则) |
items[].maybe_accepted |
boolean | 上游可能已受理 |
items[].operations |
array | 适用操作,为空表示全部 |
items[].priority |
integer | 匹配优先级 |
items[].remark |
string | 备注 |
items[].status |
integer | 状态 (0:停用, 1:启用) |
items[].updated_at |
string | 更新时间 |
page |
integer | 当前页 |
size |
integer | 每页数量 |
total |
integer | 总数 |
GET /iot-cards/{id}/polling-state 查询单卡轮询状态
各检查类型下次到期、最近成功、连续失败与最近错误、是否执行中;停复机出口开关、当前停复机指令(动作、原因、场景、版本、失败次数、待确认、下次可执行时间)与最近一次停复机调用时间;只读。
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| path | id |
integer | 是 | 卡ID |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
card_id |
integer | 卡ID |
carrier_id |
integer | 运营商账户ID |
claim_expire_at |
string | 处理中标记到期时间 |
enable_polling |
boolean | 卡轮询开关 |
iccid |
string | ICCID |
last_stop_resume_call_at |
string | 最近一次停复机网关调用时间(单卡最小重试间隔依据) |
priority_mark |
boolean | 执行中收到请求检查,收尾后进入优先队列 |
queue |
string | 所在队列 (priority:优先, queue:普通, none:不在轮询中) |
queue_score_at |
string | 队列中下次可领取时间 |
running |
boolean | 是否执行中 |
scheduler_mode |
string | 当前调度模式 (legacy:旧分片调度, carrier:按运营商账户调度) |
stop_resume_command |
object | |
stop_resume_command.action |
string | 动作 (stop:停机, start:复机) |
stop_resume_command.fail_count |
integer | 连续失败次数 |
stop_resume_command.last_error |
string | 最近错误(类别/信息) |
stop_resume_command.next_at |
string | 下次可执行时间(空表示不在队列中) |
stop_resume_command.pending |
boolean | 结果未知,待确认 |
stop_resume_command.reason |
string | 停机原因 |
stop_resume_command.scenes |
array | 触发场景 |
stop_resume_command.source |
string | 请求来源 |
stop_resume_command.unknown |
integer | 连续结果未知次数 |
stop_resume_command.version |
integer | 指令版本 |
stop_resume_command.written_at |
string | 最近写入时间 |
stop_resume_queue_enabled |
boolean | 停复机出口开关是否开启 |
types |
array | 各检查类型状态 |
types[].check_type |
string | 检查类型 |
types[].check_type_name |
string | 检查类型名称 |
types[].fail_count |
integer | 连续失败次数 |
types[].first_failed_at |
string | 首次失败时间 |
types[].last_error |
string | 最近错误(类别/信息) |
types[].last_success_at |
string | 最近一次成功时间 |
types[].next_due_at |
string | 下次到期时间 |
types[].pending_confirm |
array | 待执行的延迟确认(秒) |
GET /iot-cards/{id}/stop-resume-records 查询单卡停复机历史
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| query | page |
integer | 页码 | |
| query | page_size |
integer | 每页数量 | |
| query | start_time |
string | 开始时间(RFC3339),为空取最近 31 天 | |
| query | end_time |
string | 结束时间(RFC3339),为空取当前 | |
| path | id |
integer | 是 | IoT卡ID |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
items |
array | 记录列表 |
items[].action |
string | 动作 (stop:停机, start:复机) |
items[].action_name |
string | 动作名称 |
items[].attempt |
integer | 尝试序号 |
items[].card_id |
integer | IoT卡ID |
items[].carrier_id |
integer | 运营商账户ID |
items[].command_id |
string | 停复机命令标识,同一命令的多次尝试相同 |
items[].created_at |
string | 记录时间 |
items[].duration_ms |
integer | 耗时(毫秒) |
items[].error_category |
string | 错误类别 |
items[].error_category_name |
string | 错误类别名称 |
items[].iccid |
string | ICCID |
items[].id |
integer | 记录ID |
items[].provider_code |
string | 上游返回码 |
items[].provider_message |
string | 上游返回信息(已截断) |
items[].reason |
string | 停机原因 |
items[].result |
string | 结果 (success:成功, failed:失败, unknown:结果未知, already_target:已是目标状态, skipped:跳过) |
items[].scene |
string | 场景 |
items[].source |
string | 来源 |
page |
integer | 当前页 |
size |
integer | 每页数量 |
total |
integer | 总数 |
GET /polling-carrier-params 查询运营商账户调度参数列表
未单独配置的账户返回全局默认并标记 is_default。
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
default_card_max_in_flight |
integer | 全局默认每进程 max_in_flight |
default_inflight_limit |
integer | 全局默认执行上限 |
items |
array | 各运营商账户调度参数 |
items[].card_max_in_flight |
integer | 生效的每进程卡任务 max_in_flight |
items[].carrier_id |
integer | 运营商账户ID |
items[].carrier_name |
string | 运营商账户名称 |
items[].configured_card_max_in_flight |
integer | 单独配置的每进程 max_in_flight,空表示使用默认 |
items[].configured_inflight_limit |
integer | 单独配置的执行上限,空表示使用默认 |
items[].consume_capacity |
integer | 当前订阅进程 max_in_flight 之和(执行上限不应超过该值) |
items[].inflight_limit |
integer | 生效的执行上限(跨 Worker 实例同时执行卡任务数) |
items[].is_default |
boolean | 是否未单独配置、全部使用全局默认 |
items[].priority_max_ratio |
number | 优先队列每轮最大占比(0~1),空表示不限 |
items[].sr_inflight_limit |
integer | 停复机执行上限(停复机指令队列使用),空表示默认 |
items[].stop_resume_confirm_delay |
integer | 停复机结果未知后确认延迟(秒),空表示默认 |
items[].stop_resume_max_in_flight |
integer | 每进程停复机 max_in_flight(停复机指令队列使用),空表示默认 |
items[].stop_resume_min_interval |
integer | 单卡两次停复机调用最小间隔(秒),空表示默认 |
subscriber_processes |
integer | 订阅卡任务的 Worker 进程数 |
GET /polling-carrier-params/{carrier_id} 查询运营商账户调度参数
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| path | carrier_id |
integer | 是 | 运营商账户ID |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
card_max_in_flight |
integer | 生效的每进程卡任务 max_in_flight |
carrier_id |
integer | 运营商账户ID |
carrier_name |
string | 运营商账户名称 |
configured_card_max_in_flight |
integer | 单独配置的每进程 max_in_flight,空表示使用默认 |
configured_inflight_limit |
integer | 单独配置的执行上限,空表示使用默认 |
consume_capacity |
integer | 当前订阅进程 max_in_flight 之和(执行上限不应超过该值) |
inflight_limit |
integer | 生效的执行上限(跨 Worker 实例同时执行卡任务数) |
is_default |
boolean | 是否未单独配置、全部使用全局默认 |
priority_max_ratio |
number | 优先队列每轮最大占比(0~1),空表示不限 |
sr_inflight_limit |
integer | 停复机执行上限(停复机指令队列使用),空表示默认 |
stop_resume_confirm_delay |
integer | 停复机结果未知后确认延迟(秒),空表示默认 |
stop_resume_max_in_flight |
integer | 每进程停复机 max_in_flight(停复机指令队列使用),空表示默认 |
stop_resume_min_interval |
integer | 单卡两次停复机调用最小间隔(秒),空表示默认 |
GET /polling-check-scenes 查询请求检查场景
业务事件与读入口在按运营商账户调度时按场景请求检查;场景由代码预置。
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
[].check_types |
array | 检查类型 (card_status:卡状态, carddata:流量, realname:实名) |
[].confirm_delays |
array | 延迟确认序列(秒),空表示只立即检查一次 |
[].cooldown |
integer | 冷却时长(秒),最近一次成功检查未超过该时长则不请求;空表示不冷却 |
[].scene |
string | 场景编码 (order_paid:订单支付, package_activated:套餐激活, stop_resume_succeeded:停复机成功, device_operation:设备操作, auto_renewal_purchase:自动续费购包, client_asset_detail:C 端资产详情, admin_asset_realtime:后台资产实时状态, realname_link:实名链接) |
[].scene_name |
string | 场景名称 |
[].updated_at |
string | 更新时间 |
GET /polling-configs/match-preview 预览卡的轮询配置匹配结果(按当前配置)
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| query | iccid |
string | 是 | 要预览的卡 ICCID |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
card |
object | |
card.asset_status |
integer | 资产状态 (1:在库, 2:已销售, 3:已换货, 4:已停用) |
card.card_category |
string | 卡业务类型 (normal:普通卡, industry:行业卡) |
card.card_condition |
string | 卡状态条件 (not_real_name:未实名, activated:已激活, suspended:已停用) |
card.card_id |
integer | IoT卡ID |
card.carrier_id |
integer | 运营商账户ID |
card.enable_polling |
boolean | 是否开启轮询 |
card.iccid |
string | ICCID |
card.package_state |
string | 套餐状态 (active:有生效套餐, depleted:套餐已用完, pending:只有待生效套餐, none:无套餐),解析失败为空 |
card.package_state_name |
string | 套餐状态名称 |
intervals |
array | 各检查类型最终结果 |
intervals[].config_id |
integer | 给出取值的配置ID |
intervals[].config_name |
string | 给出取值的配置名称 |
intervals[].inherited |
boolean | 是否继承自非首个命中的配置(首个命中配置该项为空) |
intervals[].interval |
integer | 间隔(秒),仅 mode=interval 时有值 |
intervals[].mode |
string | 结果 (interval:按间隔检查, disabled:不检查, unmatched:没有任何配置给出取值,不检查) |
intervals[].task_type |
string | 检查类型 (polling:realname:实名, polling:carddata:流量, polling:package:套餐, polling:card_status:卡状态) |
intervals[].task_type_name |
string | 检查类型名称 |
matched |
array | 命中的配置(按优先级、ID 升序) |
matched[].config_name |
string | 配置名称 |
matched[].draft |
boolean | 是否为预览中的未保存配置 |
matched[].id |
integer | 配置ID |
matched[].priority |
integer | 优先级 |
GET /polling-configs/recalculate-due/{task_id} 查询重算轮询到期时间任务进度
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| path | task_id |
string | 是 | 重算任务ID |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
advanced |
integer | 被提前的检查项数 |
carrier_id |
string | 限定的运营商账户ID,为空表示全部 |
created_at |
string | 创建时间 |
error |
string | 失败原因 |
finished_at |
string | 结束时间 |
processed |
integer | 已处理的卡数 |
started_at |
string | 开始时间 |
status |
string | 状态 (pending:已入队, running:执行中, completed:已完成, failed:失败) |
task_id |
string | 重算任务ID |
total |
integer | 需处理的卡数 |
GET /polling-failure-alerts 查询卡轮询失败告警列表
view=stop_refused 为停机被拒视图:停复机方向为停机,且错误类型为终态或业务错误、或停机失败次数达到停复机告警阈值;该视图只按 carrier_id、status、iccid、start_time、end_time 筛选(忽略 check_type、error_category、alert_level),并额外返回 device_id、network_status、stop_reason、enable_polling、has_package、handled_by_name。导出使用统一导出任务,场景 polling_stop_refused_alert。
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| query | page |
integer | 页码 | |
| query | page_size |
integer | 每页数量 | |
| query | carrier_id |
integer | 运营商账户ID | |
| query | check_type |
string | 检查类型 (card_status:卡状态, carddata:流量, realname:实名, package:套餐, stop_resume:停复机, all:账户级) | |
| query | view |
string | 视图 (stop_refused:停机被拒:停复机方向为停机,且错误类型为终态或业务错误、或停机失败次数达到阈值) | |
| query | error_category |
string | 错误类别 | |
| query | status |
integer | 状态 (1:未处理, 2:已恢复, 3:已关闭轮询, 4:已处理) | |
| query | alert_level |
string | 告警级别 (card:卡级, carrier:账户级) | |
| query | iccid |
string | ICCID(精确) | |
| query | start_time |
string | 最近失败时间起始(带时区的 RFC3339 秒级时间) | |
| query | end_time |
string | 最近失败时间结束(带时区的 RFC3339 秒级时间) |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
items |
array | 告警列表 |
items[].alert_level |
string | 告警级别 (card:卡级, carrier:账户级) |
items[].card_id |
integer | 卡ID,账户级为 0 |
items[].carrier_id |
integer | 运营商账户ID |
items[].carrier_name |
string | 运营商账户名称 |
items[].check_type |
string | 检查类型 |
items[].check_type_name |
string | 检查类型名称 |
items[].created_at |
string | 创建时间 |
items[].device_id |
integer | 卡绑定的设备ID(停机被拒视图) |
items[].enable_polling |
boolean | 卡当前是否轮询(停机被拒视图) |
items[].error_category |
string | 最近错误类别 |
items[].fail_count |
integer | 连续失败次数;账户级为窗口内告警数 |
items[].first_failed_at |
string | 首次失败时间 |
items[].handle_remark |
string | 处理备注 |
items[].handled_at |
string | 处理时间 |
items[].handled_by |
integer | 处理人 |
items[].handled_by_name |
string | 处理人(停机被拒视图) |
items[].has_package |
boolean | 资产是否有生效中主套餐(停机被拒视图) |
items[].iccid |
string | ICCID |
items[].id |
integer | 告警ID |
items[].last_error |
string | 最近错误 |
items[].last_failed_at |
string | 最近失败时间 |
items[].network_status |
integer | 卡当前网络状态 (0:停机, 1:开机)(停机被拒视图) |
items[].recovered_at |
string | 自动恢复时间 |
items[].status |
integer | 状态 (1:未处理, 2:已恢复, 3:已关闭轮询, 4:已处理) |
items[].status_name |
string | 状态名称 |
items[].stop_reason |
string | 卡当前停机原因(停机被拒视图) |
page |
integer | 当前页 |
size |
integer | 每页数量 |
total |
integer | 总数 |
GET /polling-failure-alerts/summary 未处理卡轮询失败告警按运营商账户与错误类别汇总
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
[].carrier_id |
integer | 运营商账户ID |
[].carrier_name |
string | 运营商账户名称 |
[].error_category |
string | 错误类别 |
[].open_count |
integer | 未处理卡级告警数 |
GET /polling-failure-alerts/{id} 查询卡轮询失败告警详情
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| path | id |
integer | 是 | 告警ID |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
alert_level |
string | 告警级别 (card:卡级, carrier:账户级) |
card_id |
integer | 卡ID,账户级为 0 |
carrier_id |
integer | 运营商账户ID |
carrier_name |
string | 运营商账户名称 |
check_type |
string | 检查类型 |
check_type_name |
string | 检查类型名称 |
created_at |
string | 创建时间 |
device_id |
integer | 卡绑定的设备ID(停机被拒视图) |
enable_polling |
boolean | 卡当前是否轮询(停机被拒视图) |
error_category |
string | 最近错误类别 |
fail_count |
integer | 连续失败次数;账户级为窗口内告警数 |
first_failed_at |
string | 首次失败时间 |
handle_remark |
string | 处理备注 |
handled_at |
string | 处理时间 |
handled_by |
integer | 处理人 |
handled_by_name |
string | 处理人(停机被拒视图) |
has_package |
boolean | 资产是否有生效中主套餐(停机被拒视图) |
iccid |
string | ICCID |
id |
integer | 告警ID |
last_error |
string | 最近错误 |
last_failed_at |
string | 最近失败时间 |
network_status |
integer | 卡当前网络状态 (0:停机, 1:开机)(停机被拒视图) |
recovered_at |
string | 自动恢复时间 |
status |
integer | 状态 (1:未处理, 2:已恢复, 3:已关闭轮询, 4:已处理) |
status_name |
string | 状态名称 |
stop_reason |
string | 卡当前停机原因(停机被拒视图) |
GET /polling-options 查询轮询与网关限流枚举
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
error_categories |
array | 上游错误分类类别 |
error_categories[].label |
string | 中文名称 |
error_categories[].value |
string | 取值 |
exempt_sources |
array | 限流豁免来源 |
exempt_sources[].label |
string | 中文名称 |
exempt_sources[].value |
string | 取值 |
gateway_operations |
array | 卡网关操作 |
gateway_operations[].label |
string | 中文名称 |
gateway_operations[].value |
string | 取值 |
match_types |
array | 错误分类匹配方式 |
match_types[].label |
string | 中文名称 |
match_types[].value |
string | 取值 |
rate_limit_modes |
array | 限流模式 |
rate_limit_modes[].label |
string | 中文名称 |
rate_limit_modes[].value |
string | 取值 |
stop_resume_actions |
array | 停复机动作 |
stop_resume_actions[].label |
string | 中文名称 |
stop_resume_actions[].value |
string | 取值 |
stop_resume_results |
array | 停复机记录结果 |
stop_resume_results[].label |
string | 中文名称 |
stop_resume_results[].value |
string | 取值 |
GET /polling-rate-limit-groups 查询网关限流组列表
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| query | page |
integer | 页码 | |
| query | page_size |
integer | 每页数量 | |
| query | carrier_id |
integer | 运营商账户ID筛选 | |
| query | only_global |
boolean | 只看全局组 | |
| query | status |
integer | 状态 (0:停用, 1:启用) |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
items |
array | 限流组列表 |
items[].carrier_id |
integer | 运营商账户ID,为空表示全局组 |
items[].carrier_name |
string | 运营商账户名称,全局组为空 |
items[].created_at |
string | 创建时间 |
items[].group_code |
string | 组标识 |
items[].group_name |
string | 组名称 |
items[].high_priority_operations |
array | 高优先级操作 |
items[].id |
integer | 限流组ID |
items[].max_qps |
integer | 每秒请求上限 |
items[].operations |
array | 组内操作 (query_flow:查流量, query_status:查状态, query_realname:查实名, stop:停机, start:复机) |
items[].reserved_qps |
integer | 预留给高优先级操作的额度 |
items[].status |
integer | 状态 (0:停用, 1:启用) |
items[].status_name |
string | 状态名称 |
items[].updated_at |
string | 更新时间 |
page |
integer | 当前页 |
size |
integer | 每页数量 |
total |
integer | 总数 |
GET /polling-rate-limit-groups/{id} 查询网关限流组详情
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| path | id |
integer | 是 | ID |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
carrier_id |
integer | 运营商账户ID,为空表示全局组 |
carrier_name |
string | 运营商账户名称,全局组为空 |
created_at |
string | 创建时间 |
group_code |
string | 组标识 |
group_name |
string | 组名称 |
high_priority_operations |
array | 高优先级操作 |
id |
integer | 限流组ID |
max_qps |
integer | 每秒请求上限 |
operations |
array | 组内操作 (query_flow:查流量, query_status:查状态, query_realname:查实名, stop:停机, start:复机) |
reserved_qps |
integer | 预留给高优先级操作的额度 |
status |
integer | 状态 (0:停用, 1:启用) |
status_name |
string | 状态名称 |
updated_at |
string | 更新时间 |
GET /polling-stats/carrier-queues 按运营商账户的轮询队列与执行监控
按运营商账户调度的各账户队列长度、已到期数、执行中、上一分钟 QPS、限流等待与拒绝、处理中标记到期、未处理告警;停复机指令队列长度、已到期、执行中、待确认,近 1 小时停复机成功、失败、重试、结果未知数。
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
init_state |
string | 新结构初始化状态 (running / done,空表示未初始化) |
items |
array | 各运营商账户监控 |
items[].carrier_id |
integer | 运营商账户ID |
items[].carrier_name |
string | 运营商账户名称 |
items[].due_count |
integer | 已到期卡数(优先 + 普通) |
items[].expired_claims_1h |
integer | 近 1 小时处理中标记到期次数(执行崩溃或超时) |
items[].inflight_limit |
integer | 执行上限 |
items[].open_alerts |
integer | 未处理卡级失败告警数 |
items[].open_alerts_by_category |
object | 未处理卡级失败告警数(按错误类别) |
items[].priority_length |
integer | 优先队列长度 |
items[].qps_last_minute |
number | 上一分钟实际网关调用 QPS(查询类) |
items[].queue_length |
integer | 普通队列长度 |
items[].rate_limit_waits |
integer | 上一分钟限流等待次数 |
items[].rate_limited |
integer | 上一分钟限流拒绝或等待超时次数 |
items[].running |
integer | 执行中卡任务数 |
items[].stop_resume_due |
integer | 已到期停复机指令数 |
items[].stop_resume_failed_1h |
integer | 近 1 小时停复机失败数(计入连续失败或终态) |
items[].stop_resume_pending |
integer | 结果未知待确认的停复机指令数(按队列前 500 条统计) |
items[].stop_resume_queue_length |
integer | 停复机指令队列长度 |
items[].stop_resume_retry_1h |
integer | 近 1 小时停复机推后重试数(限流、频率限制、最小间隔) |
items[].stop_resume_running |
integer | 执行中停复机指令数 |
items[].stop_resume_success_1h |
integer | 近 1 小时停复机成功数 |
items[].stop_resume_unknown_1h |
integer | 近 1 小时停复机结果未知数 |
scheduler_mode |
string | 当前调度模式 |
GET /polling-stats/carriers 按运营商账户汇总网关调用
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| query | minutes |
integer | 统计最近多少分钟,默认 15,最大 60 |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
carriers |
array | 有调用的运营商账户汇总 |
carriers[].carrier_id |
integer | 运营商账户ID(0 表示无法解析账户的卡) |
carriers[].carrier_name |
string | 运营商账户名称 |
carriers[].operations |
array | 各操作汇总 |
carriers[].operations[].attempts |
integer | 实际发出的请求数 |
carriers[].operations[].avg_duration_ms |
number | 平均耗时(毫秒) |
carriers[].operations[].avg_qps |
number | 平均每秒请求数 |
carriers[].operations[].exempt |
object | 按豁免来源的调用量 (manual_click/channel_threshold/auto_renewal/manual_refresh) |
carriers[].operations[].failures |
object | 按错误类别的失败数(network/timeout/http/invalid_response/upstream:<类别>) |
carriers[].operations[].operation |
string | 操作 (query_flow:查流量, query_status:查状态, query_realname:查实名, stop:停机, start:复机) |
carriers[].operations[].operation_name |
string | 操作名称 |
carriers[].operations[].p95_duration_ms |
integer | p95 耗时上界(毫秒,按分桶近似),-1 表示超过最大分桶 |
carriers[].operations[].peak_minute_qps |
number | 峰值分钟的平均每秒请求数 |
carriers[].operations[].rate_limited |
integer | 被限流拒绝的次数(拦截模式) |
carriers[].operations[].success |
integer | 成功数 |
carriers[].operations[].success_rate |
number | 成功率(0~1) |
carriers[].operations[].would_limit |
integer | 超过限流组上限的次数(只统计模式下为本应被限流次数) |
minutes |
integer | 统计窗口(分钟) |
mode |
string | 当前限流模式 (observe:只统计, enforce:拦截) |
GET /polling-stats/carriers/{carrier_id}/trend 查询单个运营商账户的网关调用趋势
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| query | minutes |
integer | 统计最近多少分钟,默认 60,最大 10080(7 天) | |
| query | bucket_minutes |
integer | 聚合粒度(分钟),默认 1 | |
| path | carrier_id |
integer | 是 | 运营商账户ID(0 表示无法解析账户的卡) |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
carrier_id |
integer | 运营商账户ID |
points |
array | 时间桶列表 |
points[].operations |
array | 各操作在该时间桶的汇总 |
points[].operations[].attempts |
integer | 实际发出的请求数 |
points[].operations[].avg_duration_ms |
number | 平均耗时(毫秒) |
points[].operations[].avg_qps |
number | 平均每秒请求数 |
points[].operations[].exempt |
object | 按豁免来源的调用量 (manual_click/channel_threshold/auto_renewal/manual_refresh) |
points[].operations[].failures |
object | 按错误类别的失败数(network/timeout/http/invalid_response/upstream:<类别>) |
points[].operations[].operation |
string | 操作 (query_flow:查流量, query_status:查状态, query_realname:查实名, stop:停机, start:复机) |
points[].operations[].operation_name |
string | 操作名称 |
points[].operations[].p95_duration_ms |
integer | p95 耗时上界(毫秒,按分桶近似),-1 表示超过最大分桶 |
points[].operations[].peak_minute_qps |
number | 峰值分钟的平均每秒请求数 |
points[].operations[].rate_limited |
integer | 被限流拒绝的次数(拦截模式) |
points[].operations[].success |
integer | 成功数 |
points[].operations[].success_rate |
number | 成功率(0~1) |
points[].operations[].would_limit |
integer | 超过限流组上限的次数(只统计模式下为本应被限流次数) |
points[].time |
string | 时间桶起点(上海时区,yyyy-MM-dd HH:mm) |
GET /polling-stats/pre-reset 重置日前加密查流量效果统计
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
carriers |
array | 有开启轮询卡的运营商账户 |
carriers[].carrier_id |
integer | 运营商账户ID |
carriers[].carrier_name |
string | 运营商账户名称 |
carriers[].previous |
object | |
carriers[].previous.active_package_cards |
integer | 当前有生效套餐的轮询卡数 |
carriers[].previous.checked_in_window |
integer | 窗口内查到过流量的卡数(近似去重计数) |
carriers[].previous.last_offset_buckets |
object | 每张卡窗口内最后一次查询距重置时刻的分布(分钟):le_5/le_15/le_30/le_60/gt_60 |
carriers[].previous.not_checked_in_window |
integer | 有生效套餐但窗口内未查到流量的卡数(近似,最小为 0) |
carriers[].previous.reset_at |
string | 重置时刻(上海时区) |
carriers[].upcoming |
object | |
carriers[].upcoming.active_package_cards |
integer | 当前有生效套餐的轮询卡数 |
carriers[].upcoming.checked_in_window |
integer | 窗口内查到过流量的卡数(近似去重计数) |
carriers[].upcoming.last_offset_buckets |
object | 每张卡窗口内最后一次查询距重置时刻的分布(分钟):le_5/le_15/le_30/le_60/gt_60 |
carriers[].upcoming.not_checked_in_window |
integer | 有生效套餐但窗口内未查到流量的卡数(近似,最小为 0) |
carriers[].upcoming.reset_at |
string | 重置时刻(上海时区) |
GET /polling-stats/tiers 分层轮询统计(结果缓存 5 分钟)
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
by_config |
array | 按首个命中配置统计 |
by_config[].cards |
integer | 卡数 |
by_config[].config_id |
integer | 首个命中的配置ID,0 表示未匹配任何配置 |
by_config[].config_name |
string | 首个命中的配置名称 |
by_package_state |
object | 按套餐状态统计 (active/depleted/pending/none/unknown) |
computed_at |
string | 统计时间(结果缓存 5 分钟) |
total_cards |
integer | 开启轮询的卡数 |
unmatched_in_stock |
integer | 未匹配任何配置的在库卡数(应告警) |
unmatched_sold_no_package |
integer | 未匹配任何配置的已销售无套餐卡数(应告警) |
GET /polling-status-imports 查询轮询开关导入任务
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| query | page |
integer | 页码 | |
| query | page_size |
integer | 每页数量 | |
| query | status |
integer | 任务状态 (1:待处理, 2:处理中, 3:已完成, 4:失败) |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
items |
array | 任务列表 |
items[].asset_type |
string | 资产类型 (iot_card:卡, device:设备) |
items[].completed_at |
string | 完成时间 |
items[].created_at |
string | 创建时间 |
items[].creator_name |
string | 创建人 |
items[].enable_polling |
boolean | 目标状态 |
items[].error_message |
string | 任务级失败原因 |
items[].fail_count |
integer | 失败行数 |
items[].file_name |
string | 文件名 |
items[].id |
integer | 任务ID |
items[].reason |
string | 原因 |
items[].skip_count |
integer | 跳过行数 |
items[].started_at |
string | 开始处理时间 |
items[].status |
integer | 任务状态 (1:待处理, 2:处理中, 3:已完成, 4:失败) |
items[].status_name |
string | 任务状态名称 |
items[].success_count |
integer | 成功行数 |
items[].task_no |
string | 任务编号 |
items[].total_count |
integer | 数据行数 |
page |
integer | 当前页 |
size |
integer | 每页数量 |
total |
integer | 总数 |
GET /polling-status-imports/{id} 查询轮询开关导入任务详情(含逐行结果)
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| path | id |
integer | 是 | 导入任务ID |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
asset_type |
string | 资产类型 (iot_card:卡, device:设备) |
completed_at |
string | 完成时间 |
created_at |
string | 创建时间 |
creator_name |
string | 创建人 |
enable_polling |
boolean | 目标状态 |
error_message |
string | 任务级失败原因 |
fail_count |
integer | 失败行数 |
file_name |
string | 文件名 |
id |
integer | 任务ID |
items |
array | 逐行结果 |
items[].asset_id |
integer | 资产ID(未找到为 0) |
items[].identifier |
string | ICCID 或 IMEI |
items[].line |
integer | 行号(自数据首行起计) |
items[].reason |
string | 跳过或失败原因 |
items[].status |
integer | 结果 (1:成功, 2:跳过, 3:失败, 4:无权限或资产不存在) |
items[].status_name |
string | 结果名称 |
reason |
string | 原因 |
skip_count |
integer | 跳过行数 |
started_at |
string | 开始处理时间 |
status |
integer | 任务状态 (1:待处理, 2:处理中, 3:已完成, 4:失败) |
status_name |
string | 任务状态名称 |
success_count |
integer | 成功行数 |
task_no |
string | 任务编号 |
total_count |
integer | 数据行数 |
GET /polling-status/impact 开关轮询影响说明
供前端关闭与开启轮询的确认框展示。
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
disable |
array | 关闭轮询的影响 |
enable |
array | 开启轮询的影响 |
GET /stop-resume-rule/dry-run 停复机规则演练
对全部开机与停机卡按停复机新规则只判断不执行(不调用网关、不写任何状态),不受停复机总开关影响。返回按运营商账户 × 当前停机原因 × 判断结果 × 原因的汇总,以及按卡ID升序的分页明细;可按运营商账户与停机原因筛选,可用 assume_control_on / assume_control_off 假设通道实名管控配置预演。全量扫描较慢,生产使用请按运营商账户筛选或使用导出。仅超级管理员与平台账号可用。
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| query | carrier_id |
integer | 运营商账户ID,不传为全部 | |
| query | stop_reason |
string | 停机原因筛选:传停机原因编码(如 not_realname、carrier_stopped、manual),传 none 表示停机原因为空,不传为全部 | |
| query | assume_control_on |
string | 假设开启实名管控的运营商账户ID,逗号分隔;只用于预演,不改实际配置 | |
| query | assume_control_off |
string | 假设关闭实名管控的运营商账户ID,逗号分隔;只用于预演,不改实际配置 | |
| query | result |
string | 明细按判断结果筛选 (will_resume:将复机, will_stop:将停机, no_action:不动作),汇总不受影响 | |
| query | page |
integer | 明细页码,默认1 | |
| query | page_size |
integer | 明细每页数量,默认20,最大500 |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
items |
array | 明细(按卡ID升序分页) |
items[].card_category |
string | 卡类别 |
items[].card_id |
integer | 卡ID |
items[].carrier_id |
integer | 运营商账户ID |
items[].carrier_name |
string | 运营商账户名称 |
items[].device_id |
integer | 有效绑定设备ID,独立卡为 0 |
items[].iccid |
string | ICCID |
items[].network_status |
integer | 当前网络状态 (0:停机, 1:开机) |
items[].realname_ok |
boolean | 按(假设的)通道实名管控是否满足实名条件 |
items[].reason |
string | 将停机时为目标停机原因,不动作时为不动作原因 |
items[].reason_name |
string | 原因名称 |
items[].result |
string | 判断结果 |
items[].result_name |
string | 判断结果名称 |
items[].stop_reason |
string | 当前停机原因 |
items[].stop_reason_name |
string | 当前停机原因名称 |
page |
integer | 当前页 |
size |
integer | 每页数量 |
summary |
array | 按运营商账户 × 当前停机原因 × 判断结果 × 原因汇总 |
summary[].carrier_id |
integer | 运营商账户ID |
summary[].carrier_name |
string | 运营商账户名称 |
summary[].count |
integer | 卡数 |
summary[].reason |
string | 将停机时为目标停机原因,不动作时为不动作原因 (polling_suspended:暂停轮询, conditions_met:满足开机条件, no_package:无套餐, traffic_exhausted:流量已用完, not_realname:未实名, threshold_locked:持通道阈值锁, carrier_missing:所属通道不存在) |
summary[].reason_name |
string | 原因名称 |
summary[].result |
string | 判断结果 (will_resume:将复机, will_stop:将停机, no_action:不动作) |
summary[].result_name |
string | 判断结果名称 |
summary[].stop_reason |
string | 当前停机原因,空表示无 |
summary[].stop_reason_name |
string | 当前停机原因名称 |
total |
integer | 明细总数(按 result 筛选后) |
totals |
object | |
totals.no_action |
integer | 不动作卡数 |
totals.total |
integer | 参与演练的开机与停机卡数 |
totals.will_resume |
integer | 将复机卡数 |
totals.will_stop |
integer | 将停机卡数 |
POST /devices/batch-update-polling-status 勾选批量开关设备轮询
单次最多500个;设备沿用级联到设备下各卡(开启时跳过风险停机、已销户的卡)。
关闭轮询的影响:关闭后不再查询上游卡状态、流量与实名;流量用完、实名不满足时不自动停机,套餐激活、流量重置后不自动复机; 套餐到期、退款后无可用套餐时仍会自动停机;订单套餐生效、后台修改有效期后资产有生效套餐时会自动恢复轮询并按规则复机;人工停复机照常;设备关闭时设备下所有卡同样适用。
开启轮询的影响:按轮询配置查询上游并按规则自动停复机,人工停机不享有豁免;网关扩展状态为风险停机或已销户的卡不能开启轮询(逐项返回跳过原因,不提供强制参数)。
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
asset_ids |
array | 资产ID列表(卡ID或设备ID),单次最多500个,不能重复 | |
enable_polling |
boolean | 目标状态 (true:开启轮询, false:关闭轮询) | |
reason |
string | 原因,写入不轮询清单 |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
fail_count |
integer | 失败数(含无权限或资产不存在) |
impact |
array | 本次目标状态的影响说明 |
items |
array | 逐项结果 |
items[].asset_id |
integer | 资产ID |
items[].identifier |
string | 资产标识(卡为 ICCID,设备为 IMEI 或虚拟号) |
items[].reason |
string | 跳过或失败原因 |
items[].status |
integer | 结果 (1:成功, 2:跳过, 3:失败, 4:无权限或资产不存在) |
items[].status_name |
string | 结果名称 |
skip_count |
integer | 跳过数(已是目标状态、风险停机或已销户不能开启) |
success_count |
integer | 成功数 |
POST /gateway-error-classifications 新建上游错误分类规则(仅超级管理员)
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
auto_disable_polling |
boolean | 命中后自动关闭该卡轮询(停复机不重试、回写网关扩展状态),仅类别为 terminal 时可勾选;更新时不传保留原值 | |
category |
string | 是 | 类别 (rate_limited_upstream:上游频率限制, terminal:终态不可操作, already_target:已是目标状态, transient:临时故障, business:业务错误, account_config:账户配置错误) |
keyword |
string | 是 | 匹配关键字或正则 |
match_type |
string | 是 | 匹配方式 (contains:包含, prefix:前缀, regex:正则) |
maybe_accepted |
boolean | 上游可能已受理(如返回含调用成功、操作进行中、请求被合并) | |
operations |
array | 适用操作,为空表示全部 | |
priority |
integer | 匹配优先级,越小越先匹配 | |
remark |
string | 备注 | |
status |
integer | 状态 (0:停用, 1:启用),新建默认启用 |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
auto_disable_polling |
boolean | 命中后自动关闭该卡轮询 |
category |
string | 类别 |
category_name |
string | 类别名称 |
created_at |
string | 创建时间 |
id |
integer | 规则ID |
keyword |
string | 匹配关键字或正则 |
match_type |
string | 匹配方式 (contains:包含, prefix:前缀, regex:正则) |
maybe_accepted |
boolean | 上游可能已受理 |
operations |
array | 适用操作,为空表示全部 |
priority |
integer | 匹配优先级 |
remark |
string | 备注 |
status |
integer | 状态 (0:停用, 1:启用) |
updated_at |
string | 更新时间 |
POST /gateway-error-classifications/test 测试上游错误分类(不写数据)
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
draft |
object | ||
draft.auto_disable_polling |
boolean | 命中后自动关闭该卡轮询(停复机不重试、回写网关扩展状态),仅类别为 terminal 时可勾选;更新时不传保留原值 | |
draft.category |
string | 是 | 类别 (rate_limited_upstream:上游频率限制, terminal:终态不可操作, already_target:已是目标状态, transient:临时故障, business:业务错误, account_config:账户配置错误) |
draft.keyword |
string | 是 | 匹配关键字或正则 |
draft.match_type |
string | 是 | 匹配方式 (contains:包含, prefix:前缀, regex:正则) |
draft.maybe_accepted |
boolean | 上游可能已受理(如返回含调用成功、操作进行中、请求被合并) | |
draft.operations |
array | 适用操作,为空表示全部 | |
draft.priority |
integer | 匹配优先级,越小越先匹配 | |
draft.remark |
string | 备注 | |
draft.status |
integer | 状态 (0:停用, 1:启用),新建默认启用 | |
message |
string | 是 | 上游返回信息 |
operation |
string | 是 | 操作 (query_flow:查流量, query_status:查状态, query_realname:查实名, stop:停机, start:复机) |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
auto_disable_polling |
boolean | 命中后自动关闭该卡轮询 |
category |
string | 命中类别 |
category_name |
string | 命中类别名称 |
keyword |
string | 命中关键字,未命中为空 |
matched |
boolean | 是否命中规则;未命中时按业务错误处理 |
maybe_accepted |
boolean | 上游可能已受理 |
rule_id |
integer | 命中规则ID,未命中或命中草稿为 0 |
POST /iot-cards/batch-update-polling-status 勾选批量开关卡轮询
单次最多500个;按数据权限逐项处理并返回结果,每项同事务写轮询开关、不轮询清单与审计。
关闭轮询的影响:关闭后不再查询上游卡状态、流量与实名;流量用完、实名不满足时不自动停机,套餐激活、流量重置后不自动复机; 套餐到期、退款后无可用套餐时仍会自动停机;订单套餐生效、后台修改有效期后资产有生效套餐时会自动恢复轮询并按规则复机;人工停复机照常;设备关闭时设备下所有卡同样适用。
开启轮询的影响:按轮询配置查询上游并按规则自动停复机,人工停机不享有豁免;网关扩展状态为风险停机或已销户的卡不能开启轮询(逐项返回跳过原因,不提供强制参数)。
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
asset_ids |
array | 资产ID列表(卡ID或设备ID),单次最多500个,不能重复 | |
enable_polling |
boolean | 目标状态 (true:开启轮询, false:关闭轮询) | |
reason |
string | 原因,写入不轮询清单 |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
fail_count |
integer | 失败数(含无权限或资产不存在) |
impact |
array | 本次目标状态的影响说明 |
items |
array | 逐项结果 |
items[].asset_id |
integer | 资产ID |
items[].identifier |
string | 资产标识(卡为 ICCID,设备为 IMEI 或虚拟号) |
items[].reason |
string | 跳过或失败原因 |
items[].status |
integer | 结果 (1:成功, 2:跳过, 3:失败, 4:无权限或资产不存在) |
items[].status_name |
string | 结果名称 |
skip_count |
integer | 跳过数(已是目标状态、风险停机或已销户不能开启) |
success_count |
integer | 成功数 |
POST /polling-configs/match-preview 预览卡的轮询配置匹配结果(可带未保存修改,不写数据)
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
iccid |
string | 是 | 要预览的卡 ICCID |
overrides |
array | 未保存的修改,不写任何数据 | |
overrides[].asset_status |
integer | 资产状态匹配 (1:在库, 2:已销售, 3:已换货, 4:已停用),为空不限 | |
overrides[].card_category |
string | 卡业务类型 (normal:普通卡, industry:行业卡),为空不限 | |
overrides[].card_condition |
string | 卡状态条件 (not_real_name:未实名, activated:已激活, suspended:已停用),为空不限 | |
overrides[].card_status_check_interval |
integer | 卡状态检查间隔(秒),正数按间隔、0 不检查、空继承 | |
overrides[].carddata_check_interval |
integer | 流量检查间隔(秒),正数按间隔、0 不检查、空继承 | |
overrides[].carrier_id |
integer | 运营商账户ID,为空不限 | |
overrides[].config_name |
string | 草稿配置名称 | |
overrides[].disabled |
boolean | 假设该配置停用(不参与匹配),为 true 时其余字段忽略 | |
overrides[].id |
integer | 要覆盖的配置 ID,0 表示新增一条草稿配置 | |
overrides[].package_check_interval |
integer | 套餐检查间隔(秒),正数按间隔、0 不检查、空继承 | |
overrides[].package_state |
string | 套餐状态匹配 (active:有生效套餐, depleted:套餐已用完, pending:只有待生效套餐, none:无套餐),为空不限 | |
overrides[].pre_reset_carddata_interval |
integer | 重置日前窗口内的流量检查间隔(秒),与窗口长度同时配置才生效 | |
overrides[].pre_reset_window |
integer | 重置日前加密窗口长度(秒),与窗口内流量间隔同时配置才生效 | |
overrides[].priority |
integer | 优先级(数字越小越优先;与已有配置相同时排在已有配置之后) | |
overrides[].realname_check_interval |
integer | 实名检查间隔(秒),正数按间隔、0 不检查、空继承 |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
card |
object | |
card.asset_status |
integer | 资产状态 (1:在库, 2:已销售, 3:已换货, 4:已停用) |
card.card_category |
string | 卡业务类型 (normal:普通卡, industry:行业卡) |
card.card_condition |
string | 卡状态条件 (not_real_name:未实名, activated:已激活, suspended:已停用) |
card.card_id |
integer | IoT卡ID |
card.carrier_id |
integer | 运营商账户ID |
card.enable_polling |
boolean | 是否开启轮询 |
card.iccid |
string | ICCID |
card.package_state |
string | 套餐状态 (active:有生效套餐, depleted:套餐已用完, pending:只有待生效套餐, none:无套餐),解析失败为空 |
card.package_state_name |
string | 套餐状态名称 |
intervals |
array | 各检查类型最终结果 |
intervals[].config_id |
integer | 给出取值的配置ID |
intervals[].config_name |
string | 给出取值的配置名称 |
intervals[].inherited |
boolean | 是否继承自非首个命中的配置(首个命中配置该项为空) |
intervals[].interval |
integer | 间隔(秒),仅 mode=interval 时有值 |
intervals[].mode |
string | 结果 (interval:按间隔检查, disabled:不检查, unmatched:没有任何配置给出取值,不检查) |
intervals[].task_type |
string | 检查类型 (polling:realname:实名, polling:carddata:流量, polling:package:套餐, polling:card_status:卡状态) |
intervals[].task_type_name |
string | 检查类型名称 |
matched |
array | 命中的配置(按优先级、ID 升序) |
matched[].config_name |
string | 配置名称 |
matched[].draft |
boolean | 是否为预览中的未保存配置 |
matched[].id |
integer | 配置ID |
matched[].priority |
integer | 优先级 |
POST /polling-configs/recalculate-due 立即重算轮询到期时间(异步,只提前不推后,仅超级管理员)
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
carrier_id |
integer | 只处理该运营商账户的卡,为空处理全部开启轮询的卡 |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
advanced |
integer | 被提前的检查项数 |
carrier_id |
string | 限定的运营商账户ID,为空表示全部 |
created_at |
string | 创建时间 |
error |
string | 失败原因 |
finished_at |
string | 结束时间 |
processed |
integer | 已处理的卡数 |
started_at |
string | 开始时间 |
status |
string | 状态 (pending:已入队, running:执行中, completed:已完成, failed:失败) |
task_id |
string | 重算任务ID |
total |
integer | 需处理的卡数 |
POST /polling-failure-alerts/close-polling 告警页勾选批量关闭轮询(仅平台账号)
单次最多500条;关闭告警对应卡的轮询,清单来源记"停机被拒告警处理",告警状态改为已关闭轮询。停机被拒视图:GET /polling-failure-alerts?view=stop_refused,导出场景 polling_stop_refused_alert。
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
alert_ids |
array | 告警ID列表,单次最多500个 | |
reason |
string | 原因,写入不轮询清单 |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
fail_count |
integer | 失败数(含无权限或资产不存在) |
impact |
array | 本次目标状态的影响说明 |
items |
array | 逐项结果 |
items[].asset_id |
integer | 资产ID |
items[].identifier |
string | 资产标识(卡为 ICCID,设备为 IMEI 或虚拟号) |
items[].reason |
string | 跳过或失败原因 |
items[].status |
integer | 结果 (1:成功, 2:跳过, 3:失败, 4:无权限或资产不存在) |
items[].status_name |
string | 结果名称 |
skip_count |
integer | 跳过数(已是目标状态、风险停机或已销户不能开启) |
success_count |
integer | 成功数 |
POST /polling-rate-limit-groups 新建网关限流组(仅超级管理员)
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
carrier_id |
integer | 运营商账户ID,为空表示全局组 | |
group_code |
string | 是 | 组标识,同一账户内唯一 |
group_name |
string | 是 | 组名称 |
high_priority_operations |
array | 高优先级操作,必须属于组内操作,设置预留额度时必填 (query_flow:查流量, query_status:查状态, query_realname:查实名, stop:停机, start:复机) | |
max_qps |
integer | 是 | 每秒请求上限 |
operations |
array | 是 | 组内操作 (query_flow:查流量, query_status:查状态, query_realname:查实名, stop:停机, start:复机) |
reserved_qps |
integer | 预留给高优先级操作的额度,须小于每秒请求上限 | |
status |
integer | 状态 (0:停用, 1:启用),新建默认启用 |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
carrier_id |
integer | 运营商账户ID,为空表示全局组 |
carrier_name |
string | 运营商账户名称,全局组为空 |
created_at |
string | 创建时间 |
group_code |
string | 组标识 |
group_name |
string | 组名称 |
high_priority_operations |
array | 高优先级操作 |
id |
integer | 限流组ID |
max_qps |
integer | 每秒请求上限 |
operations |
array | 组内操作 (query_flow:查流量, query_status:查状态, query_realname:查实名, stop:停机, start:复机) |
reserved_qps |
integer | 预留给高优先级操作的额度 |
status |
integer | 状态 (0:停用, 1:启用) |
status_name |
string | 状态名称 |
updated_at |
string | 更新时间 |
POST /polling-status-imports 创建轮询开关文件导入任务(仅平台账号)
先调用 POST /api/admin/storage/upload-url(purpose 传 polling_status_import)上传 CSV;首行为表头,首列为 ICCID(卡)或 IMEI/虚拟号(设备)。异步逐行处理,规则同勾选批量,部分成功不回滚。
关闭轮询的影响:关闭后不再查询上游卡状态、流量与实名;流量用完、实名不满足时不自动停机,套餐激活、流量重置后不自动复机; 套餐到期、退款后无可用套餐时仍会自动停机;订单套餐生效、后台修改有效期后资产有生效套餐时会自动恢复轮询并按规则复机;人工停复机照常;设备关闭时设备下所有卡同样适用。
开启轮询的影响:按轮询配置查询上游并按规则自动停复机,人工停机不享有豁免;网关扩展状态为风险停机或已销户的卡不能开启轮询(逐项返回跳过原因,不提供强制参数)。
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
asset_type |
string | 资产类型 (iot_card:按 ICCID, device:按 IMEI 或虚拟号) | |
enable_polling |
boolean | 目标状态 (true:开启轮询, false:关闭轮询) | |
file_key |
string | 已上传的 CSV 文件 Key(必须以 polling-status-imports/ 开头);首列为 ICCID(卡)或 IMEI/虚拟号(设备),首行为表头 | |
reason |
string | 原因,写入不轮询清单 |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
asset_type |
string | 资产类型 (iot_card:卡, device:设备) |
completed_at |
string | 完成时间 |
created_at |
string | 创建时间 |
creator_name |
string | 创建人 |
enable_polling |
boolean | 目标状态 |
error_message |
string | 任务级失败原因 |
fail_count |
integer | 失败行数 |
file_name |
string | 文件名 |
id |
integer | 任务ID |
reason |
string | 原因 |
skip_count |
integer | 跳过行数 |
started_at |
string | 开始处理时间 |
status |
integer | 任务状态 (1:待处理, 2:处理中, 3:已完成, 4:失败) |
status_name |
string | 任务状态名称 |
success_count |
integer | 成功行数 |
task_no |
string | 任务编号 |
total_count |
integer | 数据行数 |
POST /stop-resume-rule/dry-run/export 导出停复机规则演练明细
创建异步导出任务(场景 stop_resume_rule_dry_run),一行对应一张卡的判断结果;筛选与假设配置同演练接口。仅超级管理员与平台账号可用。
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
assume_control_off |
string | 假设关闭实名管控的运营商账户ID,逗号分隔 | |
assume_control_on |
string | 假设开启实名管控的运营商账户ID,逗号分隔 | |
carrier_id |
integer | 运营商账户ID,不传为全部 | |
format |
string | 导出格式 (xlsx:Excel, csv:CSV),默认 xlsx | |
stop_reason |
string | 停机原因筛选,none 表示停机原因为空 |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
message |
string | 提示信息 |
status |
integer | 任务状态 (1:待处理, 2:处理中, 3:已完成, 4:已失败, 5:已取消) |
status_name |
string | 任务状态名称(中文) |
task_id |
integer | 导出任务ID |
task_no |
string | 任务编号 |
PUT /gateway-error-classifications/{id} 修改上游错误分类规则(仅超级管理员)
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| path | id |
integer | 是 | ID |
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
auto_disable_polling |
boolean | 命中后自动关闭该卡轮询(停复机不重试、回写网关扩展状态),仅类别为 terminal 时可勾选;更新时不传保留原值 | |
category |
string | 是 | 类别 (rate_limited_upstream:上游频率限制, terminal:终态不可操作, already_target:已是目标状态, transient:临时故障, business:业务错误, account_config:账户配置错误) |
keyword |
string | 是 | 匹配关键字或正则 |
match_type |
string | 是 | 匹配方式 (contains:包含, prefix:前缀, regex:正则) |
maybe_accepted |
boolean | 上游可能已受理(如返回含调用成功、操作进行中、请求被合并) | |
operations |
array | 适用操作,为空表示全部 | |
priority |
integer | 匹配优先级,越小越先匹配 | |
remark |
string | 备注 | |
status |
integer | 状态 (0:停用, 1:启用),新建默认启用 |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
auto_disable_polling |
boolean | 命中后自动关闭该卡轮询 |
category |
string | 类别 |
category_name |
string | 类别名称 |
created_at |
string | 创建时间 |
id |
integer | 规则ID |
keyword |
string | 匹配关键字或正则 |
match_type |
string | 匹配方式 (contains:包含, prefix:前缀, regex:正则) |
maybe_accepted |
boolean | 上游可能已受理 |
operations |
array | 适用操作,为空表示全部 |
priority |
integer | 匹配优先级 |
remark |
string | 备注 |
status |
integer | 状态 (0:停用, 1:启用) |
updated_at |
string | 更新时间 |
PUT /gateway-error-classifications/{id}/status 启停上游错误分类规则(仅超级管理员)
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| path | id |
integer | 是 | 规则ID |
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
status |
integer | 是 | 状态 (0:停用, 1:启用) |
PUT /polling-carrier-params/{carrier_id} 保存运营商账户调度参数(仅超级管理员)
字段为空表示该项使用全局默认;执行上限不得大于当前订阅进程 max_in_flight 之和;下一轮调度生效并写统一审计。
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| path | carrier_id |
integer | 是 | 运营商账户ID |
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
card_max_in_flight |
integer | 每进程卡任务 max_in_flight,空表示默认 | |
inflight_limit |
integer | 执行上限,空表示默认 | |
priority_max_ratio |
number | 优先队列每轮最大占比(0~1],空表示不限 | |
sr_inflight_limit |
integer | 停复机执行上限,空表示默认 | |
stop_resume_confirm_delay |
integer | 停复机结果未知确认延迟(秒),空表示默认 | |
stop_resume_max_in_flight |
integer | 每进程停复机 max_in_flight,空表示默认 | |
stop_resume_min_interval |
integer | 单卡停复机最小间隔(秒),空表示默认 |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
card_max_in_flight |
integer | 生效的每进程卡任务 max_in_flight |
carrier_id |
integer | 运营商账户ID |
carrier_name |
string | 运营商账户名称 |
configured_card_max_in_flight |
integer | 单独配置的每进程 max_in_flight,空表示使用默认 |
configured_inflight_limit |
integer | 单独配置的执行上限,空表示使用默认 |
consume_capacity |
integer | 当前订阅进程 max_in_flight 之和(执行上限不应超过该值) |
inflight_limit |
integer | 生效的执行上限(跨 Worker 实例同时执行卡任务数) |
is_default |
boolean | 是否未单独配置、全部使用全局默认 |
priority_max_ratio |
number | 优先队列每轮最大占比(0~1),空表示不限 |
sr_inflight_limit |
integer | 停复机执行上限(停复机指令队列使用),空表示默认 |
stop_resume_confirm_delay |
integer | 停复机结果未知后确认延迟(秒),空表示默认 |
stop_resume_max_in_flight |
integer | 每进程停复机 max_in_flight(停复机指令队列使用),空表示默认 |
stop_resume_min_interval |
integer | 单卡两次停复机调用最小间隔(秒),空表示默认 |
PUT /polling-check-scenes/{scene} 修改请求检查场景(仅超级管理员)
只可修改检查类型、延迟确认序列(递增)与冷却时长。
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| path | scene |
string | 是 | 场景编码 |
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
check_types |
array | 是 | 检查类型 (card_status:卡状态, carddata:流量, realname:实名) |
confirm_delays |
array | 延迟确认序列(秒,递增),空表示只立即检查一次 | |
cooldown |
integer | 冷却时长(秒),空表示不冷却 |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
check_types |
array | 检查类型 (card_status:卡状态, carddata:流量, realname:实名) |
confirm_delays |
array | 延迟确认序列(秒),空表示只立即检查一次 |
cooldown |
integer | 冷却时长(秒),最近一次成功检查未超过该时长则不请求;空表示不冷却 |
scene |
string | 场景编码 (order_paid:订单支付, package_activated:套餐激活, stop_resume_succeeded:停复机成功, device_operation:设备操作, auto_renewal_purchase:自动续费购包, client_asset_detail:C 端资产详情, admin_asset_realtime:后台资产实时状态, realname_link:实名链接) |
scene_name |
string | 场景名称 |
updated_at |
string | 更新时间 |
PUT /polling-configs/priorities 整体调整轮询配置优先级(仅超级管理员)
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
ordered_ids |
array | 是 | 按期望生效顺序排列的配置 ID 列表(排在前面的优先级更高);ID 须为正整数且不重复;系统按顺序把优先级重排为 1、2、3…,未列出的配置保持原优先级 |
PUT /polling-failure-alerts/{id}/status 标记卡轮询失败告警已处理
只有未处理告警可标记;需要关闭对应卡的轮询时使用 POST /polling-failure-alerts/close-polling(告警状态自动改为已关闭轮询)。
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| path | id |
integer | 是 | 告警ID |
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
remark |
string | 处理备注 | |
status |
integer | 是 | 目标状态 (4:已处理);关闭轮询请使用资产轮询开关接口 |
PUT /polling-rate-limit-groups/{id} 修改网关限流组(仅超级管理员)
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| path | id |
integer | 是 | ID |
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
carrier_id |
integer | 运营商账户ID,为空表示全局组 | |
group_code |
string | 是 | 组标识,同一账户内唯一 |
group_name |
string | 是 | 组名称 |
high_priority_operations |
array | 高优先级操作,必须属于组内操作,设置预留额度时必填 (query_flow:查流量, query_status:查状态, query_realname:查实名, stop:停机, start:复机) | |
max_qps |
integer | 是 | 每秒请求上限 |
operations |
array | 是 | 组内操作 (query_flow:查流量, query_status:查状态, query_realname:查实名, stop:停机, start:复机) |
reserved_qps |
integer | 预留给高优先级操作的额度,须小于每秒请求上限 | |
status |
integer | 状态 (0:停用, 1:启用),新建默认启用 |
返回 data:
| 字段 | 类型 | 说明 |
|---|---|---|
carrier_id |
integer | 运营商账户ID,为空表示全局组 |
carrier_name |
string | 运营商账户名称,全局组为空 |
created_at |
string | 创建时间 |
group_code |
string | 组标识 |
group_name |
string | 组名称 |
high_priority_operations |
array | 高优先级操作 |
id |
integer | 限流组ID |
max_qps |
integer | 每秒请求上限 |
operations |
array | 组内操作 (query_flow:查流量, query_status:查状态, query_realname:查实名, stop:停机, start:复机) |
reserved_qps |
integer | 预留给高优先级操作的额度 |
status |
integer | 状态 (0:停用, 1:启用) |
status_name |
string | 状态名称 |
updated_at |
string | 更新时间 |
PUT /polling-rate-limit-groups/{id}/status 启停网关限流组(仅超级管理员)
参数:
| 位置 | 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
| path | id |
integer | 是 | 限流组ID |
请求体:
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
status |
integer | 是 | 状态 (0:停用, 1:启用);停用后组内操作回落为默认每秒请求上限 |