大疆司空平台接入实战：Java SDK 开发指南

前言大疆司空 2DJI FlightHub 2是大疆创新推出的一款无人机任务管理平台支持航线规划、任务调度、实时指挥和数据管理等功能。通过其开放的OpenAPI接口开发者可以将无人机巡检、航拍等能力集成到自有业务系统中。在电力巡检、光伏巡检、智慧城市测绘等场景中企业通常需要将大疆司空的能力与自有业务系统深度整合实现自动化作业流程。本文将基于实际项目开发经验详细介绍如何通过 Java 接入大疆司空 2 平台涵盖认证方式、核心 API 调用、Webhook 事件处理等关键内容。如果你在接入过程中遇到403 无权限异常可以先阅读姊妹篇大疆OpenAPI 403无权限异常排查指南一、开发环境准备1.1 前置依赖开发大疆司空 SDK 需要准备以下环境依赖项版本要求说明JDK1.8Java 开发环境OkHttp4.10.0HTTP 客户端Jackson2.15JSON 处理Lombok1.18简化代码编写1.2 Maven 依赖配置dependenciesdependencygroupIdcom.squareup.okhttp3/groupIdartifactIdokhttp/artifactIdversion4.12.0/version/dependencydependencygroupIdcom.fasterxml.jackson.core/groupIdartifactIdjackson-databind/artifactIdversion2.15.4/version/dependencydependencygroupIdorg.projectlombok/groupIdartifactIdlombok/artifactIdversion1.18.30/versionscopeprovided/scope/dependency/dependencies1.3 获取开发者权限接入大疆司空 OpenAPI 需要以下步骤注册大疆开发者账号访问 大疆开发者平台 注册账号创建企业组织在大疆司空控制台创建企业组织创建应用申请 OpenAPI 权限并获取 AppKey生成 Token由项目管理员生成访问令牌提示Token 必须由项目管理员生成普通成员生成的 Token 无法调用 API。二、认证方式大疆司空 2 API 采用基于 Token 的认证机制主要支持两种方式1. X-User-Token推荐DjiFlightSdksdknewDjiFlightSdk(your-user-token);适用于绝大部分接口推荐优先使用。2. X-User-Token X-Organization-KeyDjiFlightSdksdknewDjiFlightSdk(your-user-token,your-organization-key);组织级认证适用于跨组织资源访问场景。三、SDK 核心架构设计3.1 基础类设计Slf4jpublicclassDjiFlightSdk{privatestaticfinalStringBASE_URLhttps://es-flight-api-cn.djigate.com;privatestaticfinalStringHEADER_USER_TOKENX-User-Token;privatestaticfinalStringHEADER_ORG_KEYX-Organization-Key;privatestaticfinalStringHEADER_PROJECT_UUIDX-Project-Uuid;privatefinalOkHttpClientclient;privatefinalObjectMapperobjectMapper;privateStringuserToken;privateStringorganizationKey;publicDjiFlightSdk(StringuserToken){this(userToken,null);}publicDjiFlightSdk(StringuserToken,StringorganizationKey){this.userTokenuserToken;this.organizationKeyorganizationKey;this.clientbuildOkHttpClient();this.objectMapperbuildObjectMapper();}}关键组件OkHttpClient处理 HTTP 请求配置 30 秒超时和请求/响应日志拦截器ObjectMapper处理 JSON 序列化支持 snake_case 到 camelCase 的自动映射请求头管理统一处理认证头和项目头3.2 HTTP 客户端配置privateOkHttpClientbuildOkHttpClient(){HttpLoggingInterceptorinterceptornewHttpLoggingInterceptor();interceptor.setLevel(HttpLoggingInterceptor.Level.BODY);returnnewOkHttpClient.Builder().connectTimeout(Duration.ofSeconds(30)).readTimeout(Duration.ofSeconds(30)).writeTimeout(Duration.ofSeconds(30)).addInterceptor(interceptor).build();}privateObjectMapperbuildObjectMapper(){ObjectMappermappernewObjectMapper();mapper.setPropertyNamingStrategy(PropertyNamingStrategies.SNAKE_CASE_TO_CAMEL_CASE);returnmapper;}3.3 响应解析大疆司空 2 API 响应格式统一为{code:0,message:,data:{...}}SDK 提供两种解析方法// 适用于创建任务等嵌套结构privateTTparseResponse(Responseresponse,ClassTclazz)throwsIOException{Stringbodyresponse.body().string();JsonNodenodeobjectMapper.readTree(body);returnobjectMapper.treeToValue(node.get(data),clazz);}// 适用于列表等扁平结构privateTTparseSimpleResponse(Responseresponse,ClassTclazz)throwsIOException{Stringbodyresponse.body().string();returnobjectMapper.readValue(body,clazz);}四、请求头封装4.1 认证头处理privateRequest.BuilderaddAuthHeaders(Request.Builderbuilder){builder.addHeader(HEADER_USER_TOKEN,userToken);if(organizationKey!null!organizationKey.isEmpty()){builder.addHeader(HEADER_ORG_KEY,organizationKey);}returnbuilder;}4.2 项目头处理对于项目相关的 API需要在请求头中添加X-Project-UuidpublicProjectListResponsegetProjectList()throwsIOException{HttpUrlurlHttpUrl.parse(BASE_URL).newBuilder().addPathSegment(openapi).addPathSegment(v0.1).addPathSegment(project).build();RequestrequestaddAuthHeaders(newRequest.Builder()).url(url).get().build();Responseresponseclient.newCall(request).execute();returnparseResponse(response,ProjectListResponse.class);}五、核心 API 实现1. 创建飞行任务publicCreateTaskResponsecreateFlightTask(StringprojectUuid,CreateTaskRequestrequest)关键参数说明字段类型说明枚举值taskTypeString任务类型immediate, timed, recurring, continuousrthModeString返航模式intelligent, fixedwaylinePrecisionTypeString任务精度gps, rtkoutOfControlActionInFlightString失联动作lost_connection, continue_flightresumableStatusString断点续飞auto, manual特别注意所有枚举值在 V1.0 API 中均为String 类型而非早期版本的 Integer 类型。使用示例CreateTaskRequestreqCreateTaskRequest.builder().name(园区巡检任务).sn(机场 SN).waylineUuid(航线 UUID).timeZone(Asia/Shanghai).rthAltitude(50).rthMode(fixed).waylinePrecisionType(rtk).outOfControlActionInFlight(lost_connection).resumableStatus(auto).taskType(immediate).build();CreateTaskResponserespsdk.createFlightTask(项目 UUID,req);2. 获取项目列表publicProjectListResponsegetProjectList()通过X-User-Token自动获取当前组织下所有项目。5.3 获取航线列表publicWaylineListResponsegetWaylineList(StringprojectUuid)throwsIOException{HttpUrlurlHttpUrl.parse(BASE_URL).newBuilder().addPathSegment(openapi).addPathSegment(v0.1).addPathSegment(wayline).build();RequestrequestaddAuthHeaders(newRequest.Builder()).addHeader(HEADER_PROJECT_UUID,projectUuid).url(url).get().build();Responseresponseclient.newCall(request).execute();returnparseResponse(response,WaylineListResponse.class);}航线类型说明类型说明应用场景waypoint航点航线电力巡检、定点拍照mapping_2d正射采集建图航拍二维地图重建mapping_3d倾斜摄影三维模型重建mapping_strip带状航线公路、河道巡检facade斜面航线建筑立面测量solid几何体航线大型建筑物三维建模mapping_gobject贴近摄影精细结构采集负载镜头类型wide- 广角镜头适用于大面积测绘zoom- 变焦镜头适用于远距离细节检查ir- 红外镜头适用于电力巡检发热检测六、任务启动与状态查询6.1 创建飞行任务publicCreateTaskResponsecreateFlightTask(StringprojectUuid,CreateTaskRequestrequest)关键参数说明字段类型说明枚举值taskTypeString任务类型immediate, timed, recurring, continuousrthModeString返航模式intelligent, fixedwaylinePrecisionTypeString任务精度gps, rtkoutOfControlActionInFlightString失联动作lost_connection, continue_flightresumableStatusString断点续飞auto, manual特别注意所有枚举值在 V1.0 API 中均为String 类型而非早期版本的 Integer 类型。使用示例CreateTaskRequestreqCreateTaskRequest.builder().name(园区巡检任务).sn(机场 SN).waylineUuid(航线 UUID).timeZone(Asia/Shanghai).rthAltitude(50).rthMode(fixed).waylinePrecisionType(rtk).outOfControlActionInFlight(lost_connection).resumableStatus(auto).taskType(immediate).build();CreateTaskResponserespsdk.createFlightTask(项目 UUID,req);6.2 查询任务状态publicTaskStatusResponsegetTaskStatus(StringprojectUuid,StringtaskUuid)通过该接口可以实时查询任务的执行状态、当前进度、剩余电量等信息。七、Webhook 事件处理大疆司空 2 支持推送多种事件通知SDK 封装了完整的事件解析和处理逻辑。支持的事件类型notify_type事件说明flighttask_progress任务执行进度/状态变更drc_file_upload_complete指令任务媒体上传完成way_line_file_upload_complete航线任务媒体上传完成file_uploaded航线文件/3D 模型上传完成device_exit_return_home退出返航通知任务状态码状态码含义0待执行2执行中4终止5成功使用示例PostMapping(/dji/webhook)publicvoidhandle(RequestBodyStringjson)throwsException{DjiWebhookHandlerhandlernewDjiWebhookHandler();WebhookEventeventhandler.parseEvent(json);if(eventinstanceofFlightTaskProgressEventp){if(p.isCompleted()){log.info(任务完成{},p.getName());}elseif(p.isRunning()){log.info(任务执行中{}/{},p.getName(),p.getCurrentWaypointIndex());}}}7.3 完整业务处理示例PostMapping(/dji/webhook)publicvoidhandle(RequestBodyStringjson)throwsException{DjiWebhookHandlerhandlernewDjiWebhookHandler();WebhookEventeventhandler.parseEvent(json);if(eventinstanceofFlightTaskProgressEventp){if(p.isCompleted()){log.info(任务完成{},p.getName());// 任务完成后触发后续业务流程businessService.processTaskCompletion(p);}elseif(p.isRunning()){log.info(任务执行中{}/{},p.getName(),p.getCurrentWaypointIndex());// 更新前端任务进度websocketService.sendProgressUpdate(p);}}}八、数据类型与请求模型8.1 坐标格式大疆司空 API 使用WGS84 坐标系经纬度格式如下DatapublicclassCoordinate{privateDoublelatitude;// 纬度范围 -90 ~ 90privateDoublelongitude;// 经度范围 -180 ~ 180privateDoublealtitude;// 高度单位米}8.2 航点参数DatapublicclassWaypoint{privateCoordinatecoordinate;privateDoublespeed;privateDoublegimbalPitch;privateIntegeractionTime;privateListWaypointActionactions;}九、常见问题排查9.1 403 Forbidden现象调用 API 返回 403原因Token 权限不足或项目 UUID 错误解决方法确认 Token 有效且具有对应 API 的访问权限检查X-Project-Uuid头是否正确携带验证 Token 创建人仍然在项目成员列表中尝试由项目管理员重新生成 Token详细排查步骤请参考大疆OpenAPI 403无权限异常排查指南9.2 404 Not Found现象请求路径不存在原因API 版本变更导致路径错误解决使用正确的 V1.0 API 路径接口正确路径项目列表/openapi/v0.1/project航线列表/openapi/v0.1/wayline创建任务/openapi/v0.1/flight-task9.3 字段类型错误现象请求被拒绝或返回参数错误原因使用了旧的 Integer 枚举值解决确保所有枚举字段使用 String 类型如rtk而非1十、最佳实践10.1 异常封装在实际项目中建议对 API 调用进行统一的异常封装publicclassDjiApiExceptionextendsRuntimeException{privateIntegercode;privateStringmessage;publicDjiApiException(Integercode,Stringmessage){super(message);this.codecode;this.messagemessage;}}10.2 连接池优化对于高并发场景建议调整 OkHttp 连接池参数connectionPool(newConnectionPool(10,5,TimeUnit.MINUTES))总结接入大疆司空 2 平台开发业务系统需要注意以下关键点开发准备阶段确认开发环境和依赖版本由项目管理员生成正确的 Token测试获取项目列表接口验证认证开发集成阶段认证方式优先使用 X-User-TokenAPI 版本统一使用 V1.0 接口枚举值为 String 类型请求头项目相关 API 需添加 X-Project-UuidWebhook处理事件通知实现任务状态异步更新通过合理的 SDK 封装可以大大简化集成工作让业务代码专注于核心逻辑而非 HTTP 细节。后续我会继续分享更多大疆司空开发实战技巧包括航线上传、媒体文件下载等高级功能敬请关注。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源大疆开发者平台大疆司空官网全新司空 2 OpenAPI V1.0 文档大疆OpenAPI 403无权限异常排查指南