跳至主要內容

驱动管理系统 API 文档

大约 8 分钟

驱动管理系统 API 文档

概述

本文档描述了驱动管理系统的 gRPC API 接口，包含数据上传、驱动管理、设备事件处理、设备响应和设备日志管理等功能模块。

包信息

  • 包名: drive
  • Go 包: /drive
  • 语法版本: proto3

导入依赖

import "google/protobuf/any.proto";
import "google/protobuf/empty.proto";

通用消息类型

UpLoadData

数据上传结构体

字段类型描述
idstring数据ID
versionstring版本号
snstring序列号
timeint64时间戳
node_signstring节点标识
paramsmap<string, google.protobuf.Any>参数映射
sysSys系统信息

Sys

系统信息结构体

字段类型描述
ackint32确认码

ResponseData

响应数据结构体

字段类型描述
idstring响应ID
codeint32状态码
timeint64时间戳
messagestring消息
datagoogle.protobuf.Any数据

UploadResponse

上传响应结构体

字段类型描述
responseoneof响应类型
response.response_dataResponseData响应数据
response.emptygoogle.protobuf.Empty空响应

AddDriveData

添加驱动数据结构体

字段类型描述
driverNamestring驱动名称
driverSignstring驱动标识
driverNode_namestring驱动节点名称
driverNodeIpstring驱动节点IP
driverNodeSignstring驱动节点标识

AddDriveResponse

添加驱动响应结构体

字段类型描述
codeint32状态码
msgstring消息

EquipmentEvent

设备事件结构体

字段类型描述
idstring事件ID
versionstring版本号
snstring序列号
timeint64时间戳
sysSys系统信息
paramsmap<string, google.protobuf.Any>参数映射

EquipmentPush

设备响应结构体

字段类型描述
idstring响应ID
codeint32状态码
timeint64时间戳
versionstring版本号
datastring数据

EquipmentPushResponse

设备响应返回结构体

字段类型描述
idstring响应ID
codeint32状态码
msgstring消息

UploadEquipmentLogData

设备日志上传数据结构体

字段类型描述
idstring日志ID
versionstring版本号
snstring序列号
timeint64时间戳
sysSys系统信息
paramsrepeated LogEntry日志条目列表

LogEntry

日志条目结构体

字段类型描述
timeint64时间戳
logLevelstring日志级别
codestring日志代码
logContentstring日志内容

UploadEquipmentLogResponse

设备日志上传响应结构体

字段类型描述
idstring响应ID
codeint32状态码
msgstring消息

服务接口

驱动管理服务 (Drive)

1.1 数据上传（调试版）

方法: UploadData

描述: 上传数据调试用，支持流式传输

请求参数:

message UpLoadData {
  string id = 1;                                    // 数据ID
  string version = 2;                               // 版本号
  string sn = 3;                                    // 序列号
  int64 time = 4;                                   // 时间戳
  string node_sign = 7;                             // 节点标识
  map<string, google.protobuf.Any> params = 5;     // 参数映射
  Sys sys = 6;                                      // 系统信息
}

响应参数:

message UploadResponse {
  oneof response {
    ResponseData response_data = 1;                 // 响应数据
    google.protobuf.Empty empty = 2;                // 空响应
  }
}

1.2 数据上传（正式版）

方法: UploadDataV2

描述: 上传数据正式上线用，支持流式传输

请求参数:

message UpLoadData {
  string id = 1;                                    // 数据ID
  string version = 2;                               // 版本号
  string sn = 3;                                    // 序列号
  int64 time = 4;                                   // 时间戳
  string node_sign = 7;                             // 节点标识
  map<string, google.protobuf.Any> params = 5;     // 参数映射
  Sys sys = 6;                                      // 系统信息
}

响应参数:

message UploadResponse {
  oneof response {
    ResponseData response_data = 1;                 // 响应数据
    google.protobuf.Empty empty = 2;                // 空响应
  }
}

1.3 添加驱动信息

方法: AddDrive

描述: 添加新的驱动信息到系统

请求参数:

message AddDriveData {
  string driverName = 1;                            // 驱动名称
  string driverSign = 2;                            // 驱动标识
  string driverNode_name = 3;                       // 驱动节点名称
  string driverNodeIp = 4;                          // 驱动节点IP
  string driverNodeSign = 5;                        // 驱动节点标识
}

响应参数:

message AddDriveResponse {
  int32 code = 1;                                   // 状态码
  string msg = 2;                                   // 消息
}

1.4 上传设备事件

方法: UploadEquipmentEvent

描述: 上传设备事件，支持流式传输

请求参数:

message EquipmentEvent {
  string id = 1;                                    // 事件ID
  string version = 2;                               // 版本号
  string sn = 3;                                    // 序列号
  int64 time = 4;                                   // 时间戳
  Sys sys = 6;                                      // 系统信息
  map<string, google.protobuf.Any> params = 5;     // 参数映射
}

响应参数:

message UploadResponse {
  oneof response {
    ResponseData response_data = 1;                 // 响应数据
    google.protobuf.Empty empty = 2;                // 空响应
  }
}

1.5 驱动传递设备响应

方法: UploadEquipmentPush

描述: 驱动传递设备响应信息

请求参数:

message EquipmentPush {
  string id = 1;                                    // 响应ID
  int32 code = 2;                                   // 状态码
  int64 time = 4;                                   // 时间戳
  string version = 5;                               // 版本号
  string data = 3;                                  // 数据
}

响应参数:

message EquipmentPushResponse {
  string id = 1;                                    // 响应ID
  int32 code = 2;                                   // 状态码
  string msg = 3;                                   // 消息
}

1.6 上传设备日志

方法: UploadEquipmentLog

描述: 上传设备日志信息

请求参数:

message UploadEquipmentLogData {
  string id = 1;                                    // 日志ID
  string version = 2;                               // 版本号
  string sn = 3;                                    // 序列号
  int64 time = 4;                                   // 时间戳
  Sys sys = 6;                                      // 系统信息
  repeated LogEntry params = 7;                     // 日志条目列表
}

响应参数:

message UploadEquipmentLogResponse {
  string id = 1;                                    // 响应ID
  int32 code = 2;                                   // 状态码
  string msg = 3;                                   // 消息
}

状态码说明

状态码说明
200成功
400请求参数错误
401未授权
403权限不足
404资源不存在
500服务器内部错误

使用示例

数据上传示例

package main

import (
    "context"
    "log"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    pb "your_project/drive" // 替换为您的 proto 生成的包路径
    "google.golang.org/protobuf/types/known/anypb"
)

func uploadData() {
    // 建立 gRPC 连接
    conn, err := grpc.Dial("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
    if err != nil {
        log.Fatalf("连接失败: %v", err)
    }
    defer conn.Close()

    // 创建客户端
    client := pb.NewDriveClient(conn)

    // 创建数据上传请求
    uploadData := &pb.UpLoadData{
        Id:        "data_001",
        Version:   "1.0.0",
        Sn:        "SN123456789",
        Time:      1640995200, // 2022-01-01 00:00:00
        NodeSign:  "node_001",
        Sys: &pb.Sys{
            Ack: 1,
        },
        Params: map[string]*anypb.Any{
            "temperature": &anypb.Any{
                // 温度数据
            },
            "humidity": &anypb.Any{
                // 湿度数据
            },
        },
    }

    // 调用数据上传接口
    response, err := client.UploadDataV2(context.Background())
    if err != nil {
        log.Fatalf("数据上传失败: %v", err)
    }

    // 发送数据
    if err := response.Send(uploadData); err != nil {
        log.Fatalf("发送数据失败: %v", err)
    }

    // 关闭发送流
    if err := response.CloseSend(); err != nil {
        log.Fatalf("关闭发送流失败: %v", err)
    }

    // 接收响应
    uploadResponse, err := response.Recv()
    if err != nil {
        log.Fatalf("接收响应失败: %v", err)
    }

    log.Printf("数据上传成功: %+v", uploadResponse)
}

添加驱动示例

package main

import (
    "context"
    "log"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    pb "your_project/drive" // 替换为您的 proto 生成的包路径
)

func addDrive() {
    // 建立 gRPC 连接
    conn, err := grpc.Dial("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
    if err != nil {
        log.Fatalf("连接失败: %v", err)
    }
    defer conn.Close()

    // 创建客户端
    client := pb.NewDriveClient(conn)

    // 创建添加驱动请求
    addDriveData := &pb.AddDriveData{
        DriverName:      "温度传感器驱动",
        DriverSign:      "temp_sensor_driver",
        DriverNode_name: "温度传感器节点",
        DriverNodeIp:    "192.168.1.100",
        DriverNodeSign:  "temp_node_001",
    }

    // 调用添加驱动接口
    response, err := client.AddDrive(context.Background(), addDriveData)
    if err != nil {
        log.Fatalf("添加驱动失败: %v", err)
    }

    log.Printf("添加驱动成功，状态码: %d, 消息: %s", response.Code, response.Msg)
}

上传设备事件示例

package main

import (
    "context"
    "log"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    pb "your_project/drive" // 替换为您的 proto 生成的包路径
    "google.golang.org/protobuf/types/known/anypb"
)

func uploadEquipmentEvent() {
    // 建立 gRPC 连接
    conn, err := grpc.Dial("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
    if err != nil {
        log.Fatalf("连接失败: %v", err)
    }
    defer conn.Close()

    // 创建客户端
    client := pb.NewDriveClient(conn)

    // 创建设备事件请求
    equipmentEvent := &pb.EquipmentEvent{
        Id:      "event_001",
        Version: "1.0.0",
        Sn:      "SN123456789",
        Time:    1640995200, // 2022-01-01 00:00:00
        Sys: &pb.Sys{
            Ack: 1,
        },
        Params: map[string]*anypb.Any{
            "event_type": &anypb.Any{
                // 事件类型
            },
            "event_data": &anypb.Any{
                // 事件数据
            },
        },
    }

    // 调用上传设备事件接口
    response, err := client.UploadEquipmentEvent(context.Background())
    if err != nil {
        log.Fatalf("上传设备事件失败: %v", err)
    }

    // 发送事件数据
    if err := response.Send(equipmentEvent); err != nil {
        log.Fatalf("发送事件数据失败: %v", err)
    }

    // 关闭发送流
    if err := response.CloseSend(); err != nil {
        log.Fatalf("关闭发送流失败: %v", err)
    }

    // 接收响应
    uploadResponse, err := response.Recv()
    if err != nil {
        log.Fatalf("接收响应失败: %v", err)
    }

    log.Printf("设备事件上传成功: %+v", uploadResponse)
}

驱动传递设备响应示例

package main

import (
    "context"
    "log"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    pb "your_project/drive" // 替换为您的 proto 生成的包路径
)

func uploadEquipmentPush() {
    // 建立 gRPC 连接
    conn, err := grpc.Dial("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
    if err != nil {
        log.Fatalf("连接失败: %v", err)
    }
    defer conn.Close()

    // 创建客户端
    client := pb.NewDriveClient(conn)

    // 创建设备响应请求
    equipmentPush := &pb.EquipmentPush{
        Id:      "push_001",
        Code:    200,
        Time:    1640995200, // 2022-01-01 00:00:00
        Version: "1.0.0",
        Data:    `{"status": "success", "message": "设备响应正常"}`,
    }

    // 调用驱动传递设备响应接口
    response, err := client.UploadEquipmentPush(context.Background(), equipmentPush)
    if err != nil {
        log.Fatalf("传递设备响应失败: %v", err)
    }

    log.Printf("设备响应传递成功，响应ID: %s, 状态码: %d, 消息: %s", 
        response.Id, response.Code, response.Msg)
}

上传设备日志示例

package main

import (
    "context"
    "log"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"
    pb "your_project/drive" // 替换为您的 proto 生成的包路径
)

func uploadEquipmentLog() {
    // 建立 gRPC 连接
    conn, err := grpc.Dial("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
    if err != nil {
        log.Fatalf("连接失败: %v", err)
    }
    defer conn.Close()

    // 创建客户端
    client := pb.NewDriveClient(conn)

    // 创建设备日志上传请求
    uploadEquipmentLogData := &pb.UploadEquipmentLogData{
        Id:      "log_001",
        Version: "1.0.0",
        Sn:      "SN123456789",
        Time:    1640995200, // 2022-01-01 00:00:00
        Sys: &pb.Sys{
            Ack: 1,
        },
        Params: []*pb.LogEntry{
            {
                Time:       1640995200,
                LogLevel:   "INFO",
                Code:       "LOG001",
                LogContent: "设备启动成功",
            },
            {
                Time:       1640995260,
                LogLevel:   "WARN",
                Code:       "LOG002",
                LogContent: "温度传感器数据异常",
            },
        },
    }

    // 调用上传设备日志接口
    response, err := client.UploadEquipmentLog(context.Background(), uploadEquipmentLogData)
    if err != nil {
        log.Fatalf("上传设备日志失败: %v", err)
    }

    log.Printf("设备日志上传成功，响应ID: %s, 状态码: %d, 消息: %s", 
        response.Id, response.Code, response.Msg)
}

Golang 项目设置

1. 安装依赖

# 安装 gRPC 相关依赖
go get google.golang.org/grpc
go get google.golang.org/protobuf
go get google.golang.org/grpc/cmd/protoc-gen-go-grpc
go get google.golang.org/protobuf/cmd/protoc-gen-go

2. 生成 Go 代码

# 生成 Go 代码（替换路径为您的实际路径）
protoc --go_out=. --go_opt=paths=source_relative \
       --go-grpc_out=. --go-grpc_opt=paths=source_relative \
       drive.proto

3. 项目结构示例

your_project/
├── proto/
│   └── drive.proto
├── pb/
│   ├── drive.pb.go
│   └── drive_grpc.pb.go
├── client/
│   └── main.go
└── go.mod

4. go.mod 示例

module your_project

go 1.21

require (
    google.golang.org/grpc v1.60.1
    google.golang.org/protobuf v1.32.0
)

注意事项

  1. 流式传输接口（UploadData、UploadDataV2、UploadEquipmentEvent）需要正确处理流的发送和接收
  2. 时间戳字段使用 int64 类型，表示 Unix 时间戳
  3. 参数映射使用 google.protobuf.Any 类型，可以传输任意类型的数据
  4. 设备日志支持批量上传，使用 repeated LogEntry 结构
  5. 驱动节点信息包含名称、IP 和标识，用于系统识别和管理
  6. 示例中的 your_project/drive 需要替换为您的实际 proto 生成的包路径
  7. 服务端地址 localhost:50051 需要替换为实际的服务端地址
  8. 建议在生产环境中使用 TLS 加密连接
  9. 对于大量数据的流式传输，建议实现适当的错误处理和重试机制
许昌智能