WebODM任务与正射接口

背景

项目已经把“面状图斑 -> 航拍照片 -> WebODM 正射影像 -> 第三方取图/发布”的链路设计清楚，并分别沉淀了面向 WebODM 的 API 流程文档和面向项目落地的任务生命周期设计。

已确认结论

• WebODM 标准 API 链路为：获取 Token -> 上传 ZIP 创建任务 -> 轮询进度 -> 下载 orthophoto.tif。
• 所有 WebODM 后续请求都要带 Authorization: JWT <token>。
• 任务完成后只有在 status == 40 且 available_assets 包含 orthophoto.tif 时，才允许下载正射成果。
• 项目落地层面额外设计了本地任务主表 kjzg_webodm_task 和日志表 kjzg_webodm_task_log，用于承接第三方状态推进。

标准 WebODM 接口要点

• Token： POST /api/token-auth/
• 创建任务： POST /api/projects/{project_id}/tasks/
• 查询进度： GET /api/projects/{project_id}/tasks/{task_id}/
• 下载正射： GET /api/projects/{project_id}/tasks/{task_id}/download/orthophoto.tif

关键状态码：

• null：NEW
• 10：QUEUED
• 20：RUNNING
• 30：FAILED
• 40：COMPLETED
• 50：CANCELED

项目生命周期口径

第三方系统先把任务推进到 status=3，表示任务就绪且 zip_path 已填充。之后本系统接管并推进：

• 4：WebODM 鉴权完成
• 5：WebODM 任务已创建
• 6：WebODM 处理中
• 7：WebODM 处理完成
• 8：已请求第三方发布
• 9：已接收发布回调
• 10：已写入 DSM
• -1：失败终态

任务与下载规则

• 轮询建议 10 到 30 秒一次，项目配置建议值为 15 秒。
• 轮询最好异步执行，避免阻塞推进接口线程。
• 下载接口在项目设计中暂不做额外鉴权，但要求 zip_path 等本地路径必须经过白名单校验。
• 失败任务允许手动重试，但只限于“本系统已接管过”的失败任务。

风险与来源差异

• 标准 WebODM 文档只关注 WebODM 自身接口；项目生命周期文档增加了第三方状态机、日志、重试和本地文件发布逻辑。
• progress 在 WebODM 原生接口中是 0.0~1.0，项目侧对外口径改成百分比 0~100。
• 下载接口“暂不设置鉴权”是项目设计口径，不应直接视为通用最佳实践。

待确认

• 第三方发布回调的最终 URL、成功码口径和失败补偿策略。
• kjzg_bgdc_tdgwh_dsm 的最终落库字段和数据归属。
• 下载接口是否会在正式环境补上鉴权。

参考来源