跳到主要内容

建图

11.1 POST /v1/api/mapping/container/start​

以持久化任务形式启动建图。先确认导航环境已停止，扫描等设备依赖按部署配置就绪。

字段类型必填 / 说明
scene_namestring必填，遵循地图名称规则；作为输出地图名称
runtime_versionstring可选，从运行时镜像目录选择
runtime_imagestring请求结构保留；正常装配由运行时服务解析镜像，不保证使用客户端提供值
{"scene_name":"office_1f"}

响应 data：

{"task_id":"mapping-example-id","runtime_version":"version-from-device","runtime_image":"image-from-device","runtime_source":"config"}

接口最多约 5 秒检查快速失败，客户端超时应包含该等待。设备已有冲突任务：409/1007；名称非法：400/1001；启动或快速执行失败：500/3001；下游调用故障可为 502/1005。同名地图冲突等在任务执行阶段也可能表现为建图失败，不应只按地图 CRUD 错误映射判断。

11.2 POST /v1/api/mapping/container/stop​

无请求体。仅结束当前建图任务，触发容器停止与地图保存。返回 data=null 表示停止请求受理；没有可匹配建图任务时可能为 409/1007。

必须继续查询 /tasks/{task_id}。正常保存完成后 Status=2；保存校验失败为 Status=3，并检查 ErrorMsg。不要在 stop 返回后立即认为地图可导航，也不要用普通容器停止代替完整建图结束流程。

11.3 状态查询​

接口请求响应 data
GET /v1/api/mapping/container/status无ContainerState，同 5.3
POST /v1/api/mapping/status无请求体MappingStatus
GET /v1/api/mapping/health无{"healthy":true}
{"status":"mapping","perceptions_available":true,"map_available":true,"points_collected":120000,"scene_name":"office_1f","output_folder":"/workspace/maps/office_1f"}
MappingStatus 字段类型含义
statusstringinitializing / waiting_perception / waiting_map / mapping
perceptions_availableboolean感知是否可用；字段为复数 perceptions
map_availableboolean当前地图数据是否可用
points_collectedinteger已采集点云数量
scene_name、output_folderstring当前场景与输出目录

mapping/health 检查建图内部 API，不等于已经开始有效采集。

11.4 持久化建图结果​

启用持久化建图执行链路时，LocalTask.ResultJSON 可解析为：

字段类型说明
phasestringstarting / stopping / saved / failed / unknown 等执行阶段
stop_requestedboolean，可省略已请求停止
runtime_instance_idstring本次建图运行实例
scene_name、map_id、local_instance_idstring输出资源身份
saved_release_idstring，可省略保存完成的地图内容标识
errorstring，可省略诊断信息

unknown 表示需要恢复确认，不应直接重复启动。saved_release_id 证明文件保存，不证明导航容器已经加载该地图。