私有化 V2.0
私有化 OpenAPI V2.0 是一个基于 RESTful 规范的开放平台,旨在为开发者提供第三方私有云平台与司空 2 私有化版本之间的数据互通和业务集成能力。
通过 OpenAPI V2.0,开发者可以围绕设备管理、飞行任务管理、数据管理(媒体、模型、地图数据)等核心模块开展数据集成与二次开发,实现基于司空 2 的数据互通与管理、设备管理、任务调度及轻量实时控制等业务集成能力。
相比 V1.0,V2.0 以满足二次开发场景的完整业务流程为目标,系统性补充了上述核心模块的 API,将接口数量从 V1.0 的 67 个扩展至 300 多个。
此外,V2.0 优化了接口体系,将公有云与私有云接口文档分别维护,使接口分类更加清晰,便于开发者查阅和集成,也为后续接口的持续迭代提供支持。
功能列表
| 功能 | 说明 |
|---|---|
| 组织与项目管理 | 提供项目、成员、角色权限的查询与管理能力。 |
| 设备管理 | 支持设备查询与管理,如设备列表、实时状态、物模型影子、HMS 健康事件、网络与 RTK 配置等等能力,用于构建设备管理与配置系统。 |
| 飞行任务 | 支持创建飞行任务、查询任务列表与执行详情、飞行记录、AI 告警等能力,用于构建飞行任务管理系统。 |
| 实时控制 | 支持查询与获取云端控制权、下发指点飞行、POI 环绕、相机控制等指令,实现业务级、轻量化的实时控制能力。 |
| 直播 | 支持直播与旁路推流管理、切换镜头与画质等能力,用于构建直播管理系统。 |
| 媒体管理 | 支持媒体文件的查询、管理与下载能力,用于构建媒体管理系统。 |
| 模型管理 | 支持发起重建任务、管理模型资产,用于构建模型管理系统。 |
| 航线管理 | 支持获取航线列表、航线文件管理等能力,用于构建航线文件管理系统。 |
| 地图数据管理 | 支持标注管理、自定义飞行区管理、信号热力图查询等能力。 |
| 变化检测 | 支持发起变化分析任务、查询检测结果,适用于施工监测、巡检对比等场景。 |
| 开放建模 | 支持使用第三方平台的媒体数据发起建模任务。 |
接口文档
接口文档包括 OpenAPI 的功能列表,教程,接口列表和接口描述,详细内容请参阅:Open API 接口文档。
示例源码
部署示例源码并运行成功后,您即可体验基于 OpenAPI V2.0 开发的功能界面。通过示例源码,您还可以快速了解 OpenAPI 的接入方式及使用方法,加速开发与集成。
点击 「示例源码」 获取源码与接入指引。
产品架构

快速入门
环境搭建(司空 2 私有版特有)
请参考《大疆司空 2 私有版部署手册》中的《部署流程》部署私有版。
认证鉴权
请参考文档《认证鉴权教程》了解 OpenAPI 认证鉴权原理,获取x-user-token和X-Project-Uuid,这两个参数将在大部分接口的header字段中传入,用于确保 OpenAPI 的安全性和实现对司空 2 的访问控制。
注意:从私有化 V2.1 版本开始,组织 Token 支持多个,可以从:司空 2 控制台「我的组织 → 组织设置 → 开放性 Key 管理 」中去管理。可以为不同用户、租户、单位分配不同的 Key。
示例代码
1. 查询司空 2 实时控制服务状态
当司空 2 私有版正常部署后,调用接口查询实时控制服务状态: 查询司空 2 系统状态:
```http
GET /openapi/v2.0/drc/health HTTP/1.1
Host: 127.0.0.1:30812
X-Language: zh
X-Request-Id: 550e8400-e29b-41d4-a716-446655440000
X-Project-Uuid: xxxxxxxxxx
x-user-token: xxxxxxxx
接口返回0,则表示司空 2 实时控制服务正常运行:
```http
{
"code": 0,
"message": "OK",
"data": null
}
2. 获取组织下的项目列表
在司空 2 上创建组织,创建项目和绑定设备。请参考本说明书「平台基础 > 组织管理」章节在司空 2 中进行相关组织和项目创建操作, 然后调用 获取组织下的项目列表 接口获取已创建的项目列表。
GET /openapi/v2.0/manage/api/v1/organizations/{uuid}/projects?usage=complete&sort_column=create_time&sort_type=desc&page=1&page_size=20 HTTP/1.1
Host: 127.0.0.1:30812
X-Language: zh
X-Request-Id: 550e8400-e29b-41d4-a716-446655440000
X-Project-Uuid: xxxxxxxxxx
x-user-token: xxxxxxxx
返回已创建的项目列表:
```http
{
"code": 0,
"message": "OK",
"data": {
"list": [
{
"name": "c2c_test",
"introduction": "a",
"uuid": "b2c3d4e5-6789-0123-bcde-f12345678901",
"project_id": "PRJ202401001",
"org_uuid": "a1b2c3d4-5678-9012-abcd-ef1234567890",
"status": "active",
"c2c_enable": true,
"dock_rotation_disabled": false,
"c2c_task_enable": true,
"created_at": 1700000000,
"updated_at": 1700100000
}
]
}
}
3. 开启直播功能
请参考本说明书章节文档《设备管理》在司空 2 中进行相设备绑定操作, 然后参考文档《直播管理教程》接口开启直播推流。
```http
POST /openapi/v2.0/drc/api/v2/projects/{proj_uuid}/live-channels/stream/start HTTP/1.1
Host: 127.0.0.1:30812
X-Project-Uuid: xxxxxxxxxx
X-Language: zh
X-Request-Id: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json
x-user-token: xxxxxxxx
Content-Length: 130
{
"sn": "1ZNBH1Dxxxxxxx",
"camera": "165-0-7",
"video": "normal-0",
"gateway_sn": "7CTDM3Dxxxxxxx",
"video_quality": 0
}
接口返回 0 表示推流任务已成功下发,设备将按配置开始向媒体服务器推流:
```c
{
"code": 0,
"message": "OK",
"data": null
}