200 lines
4.4 KiB
Markdown
200 lines
4.4 KiB
Markdown
# 海康威视视频应用服务 API — Spring Boot 集成
|
||
|
||
## 功能概述
|
||
|
||
| 接口 | 说明 |
|
||
|------|------|
|
||
| `GET /api/cameras` | 分页获取摄像头资源列表 |
|
||
| `GET /api/cameras/{cameraIndexCode}` | 查询摄像头详情 |
|
||
| `GET /api/cameras/{cameraIndexCode}/preview-url` | 快捷获取实时预览播放地址 |
|
||
| `POST /api/cameras/preview-url` | 获取实时预览播放地址（完整参数） |
|
||
| `POST /api/cameras/playback-url` | 获取录像回放播放地址 |
|
||
|
||
---
|
||
|
||
## Web 监控界面
|
||
|
||
启动后访问 `http://localhost:8080` 即可打开视频监控界面：
|
||
|
||
- 左侧配置平台 IP / AppKey / AppSecret，点击「连接插件 & 初始化」
|
||
- 自动加载摄像头列表，点击任意摄像头即可播放实时视频
|
||
- 支持**实时预览** / **录像回放**切换
|
||
- 支持 1/4/9 分屏显示
|
||
- 抓图、本地录像等快捷操作
|
||
|
||
> **前提：** 在 Windows 客户端安装海康官方 `VideoWebPlugin.exe`，
|
||
> 并将 JS 插件文件放入 `src/main/resources/static/js/` 目录。
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 1. 配置 application.yml
|
||
|
||
```yaml
|
||
hikvision:
|
||
api:
|
||
host: https://192.168.1.100 # 平台IP或域名
|
||
app-key: your_app_key # 开放平台应用AppKey
|
||
app-secret: your_app_secret # 开放平台应用AppSecret
|
||
```
|
||
|
||
> AppKey/AppSecret 在海康 iSecure Center 开放平台 → 应用管理 → 创建应用 后获取。
|
||
|
||
### 2. 编译运行
|
||
|
||
```bash
|
||
mvn clean package -DskipTests
|
||
java -jar target/hikvision-video-api-1.0.0.jar
|
||
```
|
||
|
||
---
|
||
|
||
## 接口调用示例
|
||
|
||
### 获取摄像头列表
|
||
|
||
```bash
|
||
curl "http://localhost:8080/api/cameras?pageNo=1&pageSize=20"
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "success",
|
||
"data": {
|
||
"total": 100,
|
||
"pageNo": 1,
|
||
"pageSize": 20,
|
||
"totalPage": 5,
|
||
"list": [
|
||
{
|
||
"cameraIndexCode": "abc123",
|
||
"cameraName": "1号楼入口",
|
||
"onlineStatus": "1",
|
||
"installPlace": "1号楼大门"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 获取实时预览播放地址（RTSP）
|
||
|
||
```bash
|
||
curl "http://localhost:8080/api/cameras/abc123/preview-url?protocol=1"
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"url": "rtsp://192.168.1.100:554/openUrl/xxxtoken"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 获取实时预览播放地址（HLS）
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/cameras/preview-url \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"cameraIndexCode": "abc123",
|
||
"streamType": 0,
|
||
"protocol": 3,
|
||
"transmode": 1
|
||
}'
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"url": "https://192.168.1.100/openUrl/xxxtoken/index.m3u8"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 获取录像回放播放地址
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/cameras/playback-url \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"cameraIndexCode": "abc123",
|
||
"beginTime": "2024-01-01T00:00:00.000+08:00",
|
||
"endTime": "2024-01-01T01:00:00.000+08:00",
|
||
"protocol": 1,
|
||
"recordType": 0
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
## 协议类型说明
|
||
|
||
| protocol值 | 协议 | 说明 |
|
||
|------------|------|------|
|
||
| 1 | RTSP | 适合 VLC、ffmpeg 等本地播放 |
|
||
| 2 | RTMP | 适合 Flash/流媒体服务器转发 |
|
||
| 3 | HLS | 适合 Web 页面播放（video.js、hls.js） |
|
||
| 4 | FLV (HTTP-FLV) | 适合 Web 低延时播放（flv.js） |
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
src/main/java/com/hikvision/video/
|
||
├── HikvisionVideoApplication.java # 启动类
|
||
├── config/
|
||
│ └── HikvisionProperties.java # 配置读取
|
||
├── controller/
|
||
│ └── VideoController.java # REST接口
|
||
├── model/
|
||
│ └── HikModels.java # 请求/响应模型
|
||
├── service/
|
||
│ └── HikvisionVideoService.java # 业务逻辑 & API调用
|
||
└── util/
|
||
├── HikvisionSignUtil.java # HMAC-SHA256签名
|
||
└── HttpUtil.java # HTTP请求工具
|
||
```
|
||
|
||
---
|
||
|
||
## 签名说明
|
||
|
||
海康 API 采用 **HMAC-SHA256** 签名鉴权，签名字符串格式：
|
||
|
||
```
|
||
{METHOD}\n
|
||
{Accept}\n
|
||
{Content-Type}\n
|
||
x-ca-key:{AppKey}\n
|
||
x-ca-nonce:{随机UUID}\n
|
||
x-ca-timestamp:{毫秒时间戳}\n
|
||
{请求路径}
|
||
```
|
||
|
||
签名结果 Base64 编码后放入请求头 `X-Ca-Signature`。
|
||
|
||
---
|
||
|
||
## 常见错误码
|
||
|
||
| code | 含义 | 解决方案 |
|
||
|------|------|---------|
|
||
| 0 | 成功 | — |
|
||
| 401 | 鉴权失败 | 检查 AppKey/AppSecret 配置 |
|
||
| 1001 | 参数错误 | 检查 cameraIndexCode 是否存在 |
|
||
| 17004 | 摄像头离线 | 检查设备在线状态 |
|
||
| 10001 | 无权限 | 检查应用是否有摄像头访问权限 |
|