1. SDK
上云 API 2 知识库
  • 上云 API 2 FAQ
    • 上云 API 2 航线编辑器地图中机库位置与实际位置不一致
    • k3s 安装失败报错：x509: certificate signed by unknown authority
    • RC Pro 安装 Pilot 2 APP 时报错：未安装应用
    • 上云 API 2 中调用 SDK 的 getDeviceList 接口报错 404
    • 上云 API 2 在安装底座管理平台时报错：set password into system management failed: send request failed
    • 上云 API 2 安装底座报错：container loki is unhealthy
    • 在服务器手动部署 上云 API 2 底座后，访问底座管理平台报错：无法访问此网站
    • 在上云 API 2 管理平台更改一些配置后点击保存，一段时间后发现部分容器处于 Created 状态
    • 上云 API 2 在航线编辑器组件中创建航线报错：提交失败，请重试
    • 上云 API 2 执行 CodeMeter 安装脚本失败，提示 dpkg: error processing package codemeter-lite
    • 可视化部署底座时报错：install system management failed: exit status 1
    • 上云 API 2 底座安装 4G 增强图传服务后，4G 网络无法正常连接，设备无法通过 4G 链路上云
    • 上云 API 2 底座可视化部署安装过程中，提示缺少必要依赖包
    • 上云 API 2 航线编辑器，点击左上角返回按钮，无法退回上一级页面
    • 上云 API 2 订阅 subscribeDroneOpenProgress / CloseProgress 接口收不到数据
    • 上云 API 2 驾驶舱组件无法开启机场和无人机直播
    • 上云 API 2 通过 SDK 上传固件超时，提示连接失败
    • 上云 API 2 通过 SDK 提交固件升级后，查询进度无返回，前端组件页面进度停留在 0%
    • 上云 API 2 可视化部署安装底座，上传证书提示错误代码 7011：检测为非法证书
    • 使用上云 API 2 航线编辑组件创建航线保存失败，F12 控制台报错 ERR_CONNECTION_RESET
    • 使用上云 API 2 SDK 接口 createReconstruction 创建建模任务时需要传参 FolderId，这个 id 如何获取
    • 创建建模任务后 监听状态变更接口 listenReconstructionStatusChanged 返回的 state（建图文件状态）一直卡在 12（等待 Terra Cloud 资源中）
    • 如何使用上云 API 2 SDK 接口计算飞机镜头在地面上的覆盖面积
    • 将上云 API 2 航线预览页面封装成 Vue 组件后，切换路由再次进入时页面无法正常渲染
    • 上云 API 2 前端组件在开发环境正常，但部署到生产环境后页面报错 crypto.randomUUID is not a function
    • 使用上云 API 2 SDK 三维重建接口 createReconstruction 如何传参才能生成点云（LAS）？
    • 调用上云 API 2 SDK 接口 liveModule.start 开启直播偶现报错 213003 是什么原因
    • 运行上云 API 2 的 SDK Demo 失败，报错缺少 libatomic.so.1
    • 使用上云 API 2 SDK 接口 subscribeLiveStream() 订阅无人机直播视频帧，一段时间后直播卡顿或 SDK 收不到帧数据
    • 上云 API 2 SDK 初始化失败，日志报错 libVolcEngineRTC.so 加载失败
    • 在 上云 API 2 SDK 回调线程中调用 Future.get() 导致查询超时
    • 卸载上云 API2 底座后 AIO 管理后台仍可访问
    • 前端引入上云 API 2 前端组件的 paas.js 后，控制台输入 window.FH2 返回 undefined
    • 使用上云 API 2 SDK 收不到订阅的监听回调，日志报错 ws is not open / error -3
    • 使用上云 API 2 SDK 接口 createCustomizedFlightAreas 创建多边形限飞区失败，日志报错 err -5、230001
    • 在上云 API 2 前端设备管理组件上传固件失败，网页报错 TimeoutError
    • 建模任务创建后 listenReconstructionStatusChanged 立即回失败态（state=8）
    • 使用上云 API SDK 接口 getFlightTaskList 查询任务列表，传入空 sn 列表查不到任务数据
    • 使用上云 API 2 SDK 接口 createReconstruction 建模成功，但 getModelFileUrl 一直返回空 URL，成果 ZIP 无法生成
    • 一键起飞后实际飞行高度与设置预期不符，飞行器先爬升再下降
    • 上云 API 2 航线编辑器编辑保存后没有 Promise 回调，业务逻辑应写在哪里
    • 访问上云 API 2 前端组件的官方 HTML Demo 驾驶舱页面正常，改为 Vue 项目后驾驶舱页面能加载完成但显示状态异常
    • 前端组件在开发环境可以正常使用，但部署到生产环境后，部分 SDK 资源加载失败
    • 可视化页面部署安装时 「Terra 建模服务」下的「SERVER_IP」应该填内网 IP 还是外网 IP？
    • 飞行任务结束后媒体文件没有正常回传，调用 SDK 接口 getMediaFilesList 查询不到照片
    • 上云 API 2 如何设置航线编辑器组件的地图默认加载中心点
    • 上云 API 2 SDK 初始化正常但获取设备列表返回 ERROR_OPERATION_FAILED（httpCode=0 / errno=113 connect failed）
    • 使用上云 API 2 SDK 接口 getDroneInstance 获取不到飞行器实例
    • 已通过 SDK 获取负载控制权但负载操控接口返回 -6、负载监听无消息
    • 如何使用上云 API 2 SDK 接口 createReconstruction 生成高斯泼溅（3DGS）成果？
    • 使用上云 API 2 航线编辑器组件创建航线后未自动进入航线编辑界面，如何继续编辑航线？
    • 调用 getWaylineList 后业务接口已返回，异步查询结果还未回调
    • 在上云 API 2 可视化页面部署底座时设置密码后点击确定后页面无响应
    • 服务器异常停电，重启上云 API 2 底座服务容器之后报错：container pf-atc-service is unhealthy
    • 管理后台的密码忘记了怎么办？怎么修改管理后台的密码？
    • 在上云 API 2 底座安装包下的 env 文件中修改启用 HTTPS 相关配置后执行 ./setuptools update 报错
    • 在上云 API 2 的管理后台配置三方 Minio 后媒体管理航线管理异常
    • 使用上云 API 2 建模成功但调用 getQualityReport 接口返回状态始终为"质量报告生成中"
    • 在上云 API 2 可视化页面部署成功后 无法正常进入 AIO 管理后台，页面提示：请先激活再使用系统
    • 上云 API 2 底座部署过程中部分容器报错：unhealthy
    • 上云 API 2 手飞设备如何上云
    • 上云 API 2 底座管理平台首次激活扫码无反应，无法扫出激活码
  • 上云 API 2 常见 QA
    • 产品能力和设备运行与管控底座
    • 许可证相关
    • 安装部署
    • 设备上云
    • 前端组件
    • SDK
      • 01 接入与初始化
      • 02 飞行任务
      • 03 设备状态
      • 04 飞行控制
      • 05 媒体文件与建模
      • 06 直播与录制
      • 07 航线管理
      • 08 固件·RTK·飞行区
      • 09 信号地图
  1. SDK

02 飞行任务

Q：createFlightTask() 接口支持哪些任务执行模式？是否支持断点续飞？#

参数值说明
task_type1立即执行
task_type2定时执行
is_break_point_resumetrue断点续飞
isBreakPointResume（is_break_point_resume）用于标识当前创建的任务是否为断点续飞任务，该字段为非必填字段，默认值为 false。业务侧需根据实际任务场景判断任务类型，并在创建任务时传入对应值：
true：表示创建断点续飞任务；
false：表示创建新任务。

Q：上云 API 2 SDK 中 task_uuid、flight_id 和 track_id 分别代表什么？三者有何关联？#

字段含义备注
task_uuid航线任务的唯一标识符createFlightTask() 成功后返回
flight_id任务执行时的架次标识，一个航线任务可能有多个飞行架次-
track_id任务执行后的飞行轨迹 ID（36 位 UUID）-

Q：使用上云 API 2 SDK 创建航线任务时，beginAt/endAt 参数应如何填写？#

endAt/beginAt 填写秒级 Unix 时间戳，表示定时（条件）任务执行窗口的起止时间：
当 taskType = 2（条件/定时任务）时，beginAt 和 endAt 均为必填字段。endAt 表示任务的有效截止时间：任务需在该时间前满足条件并触发执行；超过该时间仍未触发时，任务将失效。

Q：在上云 API 2 中，FlightTaskModule.editFlightTask 编辑航线任务接口在哪些情况下无法使用？#

FlightTaskModule.editFlightTask 仅支持编辑 待开始（status = 0） 的航线任务。
限制：
status = 1～10：均不支持编辑。
taskType = 1（立即任务）：即使 status = 0，也不支持编辑。

Q：在上云 API 2 中，FlightTaskModule.getFlightTaskDetail 返回的 TaskDetail.getSn() 是机场 SN 还是无人机 SN？#

TaskDetail.getSn()：返回机场（Dock）的 SN。
TaskDetail.getDroneSn()：返回无人机的 SN。

Q：FlightTaskModule.getCommandTaskList 接口是否支持查询航线任务？如何查询一键起飞的历史任务列表、状态和时间？#

FlightTaskModule.getCommandTaskList 接口仅支持查询一键起飞任务（Command Task），不支持查询航线任务记录。如需查询航线任务列表，请调用 FlightTaskModule.getFlightTaskList。
调用 FlightTaskModule.getCommandTaskList(GetCommandTaskListParams, callback) 即可查询一键起飞历史任务列表，查询结果在回调函数中的 CommandTaskListItemData返回，其中：
CommandTaskListItemData.getStatus() 取值含义：
值含义
0待执行
1执行中
2已完成
3失败
4超时
CommandTaskListItemData.getCreatedAt()：任务创建时间。

Q：在上云 API 2 中，Dock.listenWaylineTaskEvent 回调数据包含哪些内容？如何获知飞机已到达某个航点？#

Dock.listenWaylineTaskEvent 回调数据中，WaylineTaskEvent.getAction() 字段枚举值如下：
getAction() 返回值含义
wayline_task_created任务创建
wayline_task_attr_updated任务属性更新
wayline_task_deleted任务删除
wayline_task_obstracle_changed障碍物变更
wayline_task_execute_output任务执行输出
此外，回调数据 WaylineTaskData 还包含航点执行进度字段：
字段说明
current_waypoint_index已飞完的航点索引（从 0 开始）
total_waypoints航线总航点数
建议结合 listenAircraftLocation() 获取实时 GPS 坐标，与 KMZ 航点坐标对比以精确判断航点到达情况。

Q：在上云 API 2 中，调用 FlightTaskModule.listenCommandTaskEvent 接口时，回调数据 CommandTaskData.status 字段支持哪些枚举值？#

FlightTaskModule.listenCommandTaskEvent 回调中，CommandTaskData.getStatus() 字段枚举值如下：
getStatus() 返回值含义
0待执行
1执行中
2已完成
3失败
4超时

Q：如何获取航线任务执行失败/异常时的详情和错误码？#

调用 Drone.listenFlightTasksException(callback) 监听，任务执行出现异常时会实时回调，回调数据类型为 FlightTaskException：
1.
通过 FlightTaskException.getExceptions() 获取异常详情列表，列表元素类型为 FlightTaskExceptionDetail。
2.
通过 getCode() 获取错误码，通过 getMessage() 获取错误描述。
3.
您可以调用 cancelListenFlightTasksException(listenId) 取消订阅。

Q：航线任务完成后如何查询任务执行时间、飞行时长、飞行里程和飞行轨迹？#

调用 FlightTaskModule.getFlightTaskTrack(GetFlightTaskTrackParams, callback) 接口，在 GetFlightTaskTrackParams 中传入 taskUuid，可通过回调返回的 GetFlightTaskTrackResults 获取：
GetFlightTaskTrackResults.getRunAt()：任务开始时间
GetFlightTaskTrackResults.getCompletedAt()：任务完成时间
GetFlightTaskTrackResults.getTrack().getFlightDuration()：飞行时长
GetFlightTaskTrackResults.getTrack().getFlightDistance()：飞行里程
GetFlightTaskTrackResults.getTrack().getTrackPoints()：飞行轨迹坐标点
注意： 任务刚结束时不能立即查询到飞行时长和飞行距离，飞行轨迹数据需经过异步处理，建议任务完成后延迟 5秒左右再查询，或通过轮询方式等待数据就绪。

Q：上云 API 2 SDK 是否支持定时任务和重复任务？#

上云 API 2 SDK 通过 FlightTaskModule.createFlightTask() 接口的 CreateTaskReq.taskType 字段设置任务执行模式，当前支持：
1：立即执行
2：定时执行（单次，需配置 beginAt 和 endAt）
当前暂不支持周期性重复任务，您可根据实际需求基于定时任务自行实现重复任务调度逻辑。

Q：如何监听航线任务执行阶段（起飞中/执行中/返航中/降落中等）？#

通过 listenFlightTaskStepCode() 监听任务所处阶段，如起飞中、执行中、返航中、降落中 等。可结合以下接口综合判断任务与飞行状态：
监听目标接口说明
飞机返航状态listenAircraftModeCode()返回值为 9 时表示飞机进入自动返航
航线任务状态listenWaylineTaskEvent()返回 status：2=执行中，5=成功
任务阶段状态listenFlightTaskStepCode()起飞中/执行中/返航中/降落中等

Q：创建航线任务中的“返航高度”参数如何设置？是相对高度还是绝对海拔高度？#

返航高度为相对起飞点高度（AGL，Above Ground Level），单位为米，需通过 SDK 接口设置。
下发航线任务前，请先完成返航高度设置；未设置返航高度时，航线任务无法正常执行。

Q：在上云 API 2 中，Workspace.listenWorkspaceDeviceChanged 接口在无人机上下线时会触发吗？#

不会，Workspace.listenWorkspaceDeviceChanged 仅在设备绑定和解绑时触发。

Q：上云 API 2 是否支持监听航线任务状态推送？#

支持。上云 API 2 SDK 提供以下任务状态推送接口：
事件类型接口获取方式
监听航线任务状态变化listenWaylineTaskEvent()drone.getFlightTaskControlModule()
监听任务执行异常listenFlightTasksException()drone.getDroneOsdModule()
监听一键起飞任务事件listenCommandTaskEvent()drone.getTakeoffModule()
上一页
01 接入与初始化
下一页
03 设备状态
Built with