# video-gateway-open

**Repository Path**: garrib/video-gateway-open

## Basic Information

- **Project Name**: video-gateway-open
- **Description**: 开放平台api
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-19
- **Last Updated**: 2026-02-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Video Gateway Open SDK

#### 介绍
视频网关开放平台Java SDK，支持平台授权和API调用功能。适配JitPack发布，使用JDK17开发。

#### 特性
- 🚀 基于Java内置HttpClient，无额外依赖
- 🔐 支持平台授权，token外部管理
- 📦 适配JitPack发布，易于集成
- 🧪 完整的单元测试覆盖
- 📝 详细的JavaDoc文档
- 🔧 简洁的API设计，易于使用

#### 软件架构
```
src/
├── main/java/com/github/garrib/videogateway/
│   ├── client/          # 客户端类
│   │   ├── VideoGatewayClient.java  # 授权客户端
│   │   └── ApiClient.java           # API请求客户端
│   ├── config/          # 配置类
│   │   └── DebugConfig.java         # 调试配置
│   ├── model/           # 数据模型
│   │   ├── AuthRequest.java         # 授权请求
│   │   ├── AuthResponse.java        # 授权响应
│   │   ├── ApiResponse.java         # 通用API响应
│   │   ├── PlayResult.java          # 播放结果
│   │   └── DeviceRemoteRecordInfo.java # 录像信息
│   └── util/            # 工具类
│       ├── HttpClientUtil.java      # HTTP客户端工具
│       └── SignatureUtil.java       # 签名工具
└── test/java/           # 测试代码和示例
    ├── client/          # 客户端测试
    ├── model/           # 模型测试
    ├── util/            # 工具测试
    └── demo/            # 使用示例
        └── ComprehensiveApiDemo.java # 综合API演示
```

#### 安装教程

##### Maven依赖
```xml
<dependency>
    <groupId>com.github.garrib</groupId>
    <artifactId>video-gateway-open-sdk</artifactId>
    <version>1.0.0</version>
</dependency>
```

##### Gradle依赖
```gradle
implementation 'com.github.garrib:video-gateway-open-sdk:1.0.0'
```

#### 使用说明

##### 1. 初始化客户端
```java
import com.github.garrib.videogateway.client.ApiClient;
import com.github.garrib.videogateway.client.VideoGatewayClient;

// 创建授权客户端实例
VideoGatewayClient authClient = new VideoGatewayClient(
    "https://api.example.com",  // 服务地址
    "your_appid",              // 应用ID
    "your_appsecret"           // 应用密钥
);

// 创建API客户端实例
ApiClient apiClient = new ApiClient("https://api.example.com");
```

##### 2. 平台授权
```java
import com.github.garrib.videogateway.model.AuthResponse;

try {
    // 执行授权
    AuthResponse authResponse = authClient.auth();
    
    if (authResponse.isSuccess()) {
        String token = authResponse.getData().getToken();
        System.out.println("授权成功，token: " + token);
        // 保存token供后续使用
    } else {
        System.out.println("授权失败: " + authResponse.getMessage());
    }
} catch (Exception e) {
    e.printStackTrace();
}
```

##### 3. 调用API接口（外部token管理）
```java
import com.github.garrib.videogateway.model.ApiResponse;

try {
    // 调用API（需要传入token）
    String token = "your_token_here"; // 从授权接口获取的token
    ApiResponse<String> response = apiClient.callApi(token, "/api/some/endpoint", String.class);
    
    if (response.isSuccess()) {
        System.out.println("API调用成功: " + response.getData());
    } else {
        System.out.println("API调用失败: " + response.getMessage());
    }
} catch (Exception e) {
    e.printStackTrace();
}
```

##### 4. 完整使用示例
```java
import com.github.garrib.videogateway.client.ApiClient;
import com.github.garrib.videogateway.client.VideoGatewayClient;
import com.github.garrib.videogateway.model.AuthResponse;
import com.github.garrib.videogateway.model.PlayResult;
import com.github.garrib.videogateway.model.DeviceRemoteRecordInfo;

// 初始化客户端
VideoGatewayClient authClient = new VideoGatewayClient(
    "https://your-server.com", 
    "YOUR_APPID", 
    "YOUR_APPSECRET"
);

ApiClient apiClient = new ApiClient(authClient.getBaseUrl());

// 外部维护token
String token = null;

try {
    // 1. 获取授权token
    AuthResponse authResponse = authClient.auth();
    if (authResponse.isSuccess()) {
        token = authResponse.getData().getToken();
        System.out.println("授权成功，token: " + token);
    }
    
    // 2. 获取设备播放地址
    String deviceId = "YOUR_DEVICE_ID";
    ApiResponse<PlayResult> playResponse = apiClient.getPlayUrl(token, deviceId, appid, appsecret);
    if (playResponse.isSuccess()) {
        PlayResult playResult = playResponse.getData();
        System.out.println("播放地址: " + playResult.getPlayUrl());
    }
    
    // 3. 获取录像列表
    Date endTime = new Date();
    Date startTime = new Date(endTime.getTime() - 24 * 60 * 60 * 1000L); // 最近1天
    
    ApiResponse<List<DeviceRemoteRecordInfo>> recordResponse = 
        apiClient.getRecordList(token, deviceId, startTime, endTime, appid, appsecret);
    if (recordResponse.isSuccess()) {
        List<DeviceRemoteRecordInfo> records = recordResponse.getData();
        System.out.println("录像数量: " + records.size());
    }
    
} catch (Exception e) {
    e.printStackTrace();
}
```

##### 5. 调试配置
```java
import com.github.garrib.videogateway.config.DebugConfig;

// 启用调试模式（默认开启）
DebugConfig.setDebugEnabled(true);

// 控制调试输出类型
DebugConfig.setPrintRequest(true);    // 打印请求信息
DebugConfig.setPrintResponse(true);   // 打印响应信息
DebugConfig.setPrintSignature(true);  // 打印签名信息

// 关闭调试模式
DebugConfig.setDebugEnabled(false);
```

#### API接口说明

##### 2.1 平台授权接口
- **URL**: `/api/portal/platform/auth`
- **方法**: POST
- **Content-Type**: application/json
- **功能**: 获取访问令牌

**请求头参数**:
- `appid`: 平台授权的appid (必选)
- `timestamp`: 时间戳(毫秒) (必选)
- `nonce`: 随机数(最大长度126位) (必选)
- `signature`: MD5(appid+timestamp+nonce+appsecret) (必选)

**请求体**: 空JSON对象 `{}`

**响应格式**:
```json
{
    "code": "0",
    "message": "success",
    "data": {
        "token": "5bad0c3f-5fe9-4499-b0d4-d8a1af6421d5"
    }
}
```

##### 2.2 获取设备播放地址接口
- **URL**: `/api/portal/platform/play`
- **方法**: POST
- **Content-Type**: application/json
- **功能**: 获取设备的实时播放地址

**请求头参数**:
- `Authorization`: Bearer token (必选)
- `appid`: 平台授权的appid (必选)
- `timestamp`: 时间戳(毫秒) (必选)
- `nonce`: 随机数 (必选)
- `signature`: MD5签名 (必选)

**请求体参数** (JSON):
- `deviceId`: 设备ID (必选)

**请求示例**:
```json
{
    "deviceId": "YOUR_DEVICE_ID"
}
```

**响应格式**:
```json
{
    "code": "0",
    "message": "success",
    "data": {
        "streamId": "qwhmSxhhuFLYqeHT-45010300001320000020-45010300001320000020-1-system",
        "httpFlvPlay": "http://your-server.com:port/rtp/stream-id.live.flv",
        "wsFlvPlay": "ws://your-server.com:port/rtp/stream-id.live.flv",
        "httpHlsPlay": "http://your-server.com:port/rtp/stream-id/hls.m3u8",
        "wsHlsPlay": "ws://your-server.com:port/rtp/stream-id/hls.m3u8",
        "httpTSPlay": "http://your-server.com:port/rtp/stream-id.live.ts",
        "wsTSPlay": "ws://your-server.com:port/rtp/stream-id.live.ts",
        "rtmpPlay": "rtmp://your-server.com:port/rtp/stream-id",
        "rtspPlay": "rtsp://your-server.com:port/rtp/stream-id",
        "http": {
            "streamId": "qwhmSxhhuFLYqeHT-45010300001320000020-45010300001320000020-1-system",
            "httpFlvPlay": "http://your-server.com:port/rtp/stream-id.live.flv",
            "wsFlvPlay": "ws://your-server.com:port/rtp/stream-id.live.flv",
            "httpHlsPlay": "http://your-server.com:port/rtp/stream-id/hls.m3u8",
            "wsHlsPlay": "ws://your-server.com:port/rtp/stream-id/hls.m3u8",
            "httpTSPlay": "http://your-server.com:port/rtp/stream-id.live.ts",
            "wsTSPlay": "ws://your-server.com:port/rtp/stream-id.live.ts",
            "rtmpPlay": "rtmp://your-server.com:port/rtp/stream-id",
            "rtspPlay": "rtsp://your-server.com:port/rtp/stream-id"
        },
        "https": {
            "streamId": "qwhmSxhhuFLYqeHT-45010300001320000020-45010300001320000020-1-system",
            "httpFlvPlay": "https://your-server.com:port/rtp/stream-id.live.flv",
            "wsFlvPlay": "wss://your-server.com:port/rtp/stream-id.live.flv",
            "httpHlsPlay": "https://your-server.com:port/rtp/stream-id/hls.m3u8",
            "wsHlsPlay": "wss://your-server.com:port/rtp/stream-id/hls.m3u8",
            "httpTSPlay": "https://your-server.com:port/rtp/stream-id.live.ts",
            "wsTSPlay": "wss://your-server.com:port/rtp/stream-id.live.ts",
            "rtmpPlay": "rtmps://your-server.com:port/rtp/stream-id",
            "rtspPlay": "rtsps://your-server.com:port/rtp/stream-id"
        }
    }
}
```

##### 2.3 获取设备录像列表接口
- **URL**: `/api/portal/platform/record/list`
- **方法**: POST
- **Content-Type**: application/json
- **功能**: 查询指定时间范围内的设备录像列表

**请求头参数**:
- `Authorization`: Bearer token (必选)
- `appid`: 平台授权的appid (必选)
- `timestamp`: 时间戳(毫秒) (必选)
- `nonce`: 随机数 (必选)
- `signature`: MD5签名 (必选)

**请求体参数** (JSON):
- `deviceId`: 设备ID (必选)
- `startTime`: 开始时间戳(毫秒) (必选)
- `endTime`: 结束时间戳(毫秒) (必选)

**请求示例**:
```json
{
    "deviceId": "YOUR_DEVICE_ID",
    "startTime": 1703123456789,
    "endTime": 1703209856789
}
```

**响应格式**:
```json
{
    "code": "0",
    "message": "success",
    "data": [
        {
            "fileName": "record_20231201_001.mp4",
            "startTime": "2023-12-01T08:00:00Z",
            "endTime": "2023-12-01T09:00:00Z",
            "fileSize": 104857600,
            "recordType": "timed",
            "deviceId": "device001",
            "channelId": "device001"
        }
    ]
}
```

#### 开发环境要求
- JDK 17+
- Maven 3.6+

#### 构建和测试
```bash
# 编译项目
mvn compile

# 运行测试
mvn test

# 打包
mvn package
```

#### 参与贡献

1.  Fork 本仓库
2.  新建 Feat_xxx 分支
3.  提交代码
4.  新建 Pull Request

#### 许可证
MIT License

#### 联系方式
- 项目地址: https://gitee.com/your-account/your-repo
- 作者: garrib