设备与物模型管理 API 文档

概述

本文档基于 equipment_model.proto 描述设备与物模型管理的 gRPC API，包括：物模型管理、物模型属性管理、产品管理与发布、设备全生命周期管理、设备数据查询与控制等模块。

包信息

• 包名: equipment_model
• Go 包: equipment_model
• 语法版本: proto3

导入依赖

import "google/protobuf/any.proto";

通用实体与枚举

ThingModel（物模型）

字段	类型	说明
id	string	物模型ID
name	string	名称
logo	string	图标
table_name	string	模型标识符
create_at	string	创建时间
update_at	string	更新时间

ThingModelAttribute（物模型属性）

字段	类型	说明
physical_model_attribute_id	int64	属性ID
table_name	string	物模型标识符
type	ThingModelAttributeType	属性类型
readable_type	string	可读性（只读/读写）
name	string	属性名称
code	string	属性标识符
unit	string	单位
data_type	ThingModelAttributeDataType	数据类型
event_type	ThingModelAttributeEventType	事件类型（当 type=事件 时）
AttributeSetting	map<string, Any>	属性设置参数
ServiceSetting	map<string, Any>	服务设置参数

ThingModelAttributeType（属性类型）

• FUNCTIONAL_ATTRIBUTE: 功能属性
• EVENT_ATTRIBUTE: 事件属性
• SERVER_ATTRIBUTE: 服务属性
• STATIC_ATTRIBUTE: 静态属性

ThingModelAttributeDataType（数据类型）

• INT, FLOAT, ENUM, BOOL, DATE, VARCHAR

Product（产品）

字段	类型	说明
product_id	int32	产品ID
name	string	名称
table_name	string	物模型标识符
table_name_desc	string	物模型描述
table_name_logo	string	物模型图标
network_type	NetworkType	接入网络
network_type_desc	string	网络描述
type	ProductType	产品类型
type_desc	string	类型描述
desc	string	描述
code	string	编码
publish_status	PublishStatus	发布状态
created_at	string	创建时间
updated_at	string	更新时间

NetworkType / ProductType / PublishStatus

• NetworkType: WIFI, ETHERNET, CELLULAR, BLUETOOTH
• ProductType: DEVICE, GATEWAY, SENSOR, ACTUATOR, CONTROLLER
• PublishStatus: DRAFT, PUBLISHED

Equipment（设备）

字段	类型	说明
equipment_id	int64	设备ID
name	string	设备名称
equipment_sn	string	设备SN
product_id	int64	产品ID
product_name	string	产品名称
drive_sign	string	驱动标识
drive_name	string	驱动名称
sim_id	int64	SIM卡ID
sim_number	string	SIM卡号
lat	double	纬度
lng	double	经度
parent_id	int64	父设备ID
state	EquipmentState	设备状态（ONLINE/OFFLINE）
state_desc	string	状态描述
table_name	string	对应物模型表
static_attribute	StaticAttribute[]	静态属性列表
created_at	string	创建时间
last_update_at	string	最后更新时间

其他结构

• StaticAttribute: attr_name、attr_value、attr_code
• EquipmentControlInfo: 控制记录（cmd、step、request_id、content 等）
• SensorData: 实时或统计数据点（value、time、unit、data_type）
• ResultList: 历史统计数据行（value/avg/max/min 均为 Any）
• EquipmentOption / ProductAllOption: 下拉选项（label、value）

服务接口

1. 物模型服务（ThingModelService）

1.1 创建物模型 CreateThingModel

请求：CreateThingModelRequest

message CreateThingModelRequest {
  string access_token = 1;
  string name = 2;
  string table_name = 3; // 模型标识符
  string logo = 4;
}

响应：CreateThingModelResponse（code, message）

1.2 更新物模型 UpdateThingModel

请求：UpdateThingModelRequest（id, name, logo）

响应：UpdateThingModelResponse

1.3 删除物模型 DeleteThingModel

请求：DeleteThingModelRequest（id 或 table_name）

响应：DeleteThingModelResponse

1.4 获取物模型详情 GetThingModel

请求：GetThingModelRequest（id 或 table_name）

响应：GetThingModelResponse（ThingModel）

1.5 获取物模型列表 GetThingModelList

请求：GetThingModelListRequest（page, page_size, searchKey）

响应：GetThingModelListResponse（ThingModel[], total）

2. 物模型属性服务（ThingModelAttributeService）

2.1 创建属性 CreateThingModelAttribute

请求：CreateThingModelAttributeRequest

message CreateThingModelAttributeRequest{
  string access_token = 1;
  string table_name = 2;       // required
  string name = 3;             // required
  ThingModelAttributeType type = 4; // required
  ThingModelAttributeReadable readable_type = 5;
  string code = 6;             // required
  string unit = 7;
  ThingModelAttributeDataType data_type = 8;
  map<string, google.protobuf.Any> AttributeSetting = 9;
  map<string, google.protobuf.Any> ServiceSetting = 10;
}

响应：CreateThingModelAttributeResponse

2.2 更新属性 UpdateThingModelAttribute

请求：UpdateThingModelAttributeRequest（table_name, name, type, readable_type, unit, data_type, AttributeSetting）

响应：UpdateThingModelAttributeResponse

2.3 删除属性 DeleteThingModelAttribute

请求：DeleteThingModelAttributeRequest（physical_model_attribute_id）

响应：DeleteThingModelAttributeResponse

2.4 属性列表 ThingModelAttributeList

请求：ThingModelAttributeListRequest（table_name, page, page_size, type, searchKey）

响应：ThingModelAttributeListResponse（ThingModelAttribute[], total）

2.5 属性详情 ThingModelAttributeDetail

请求：ThingModelAttributeDetailRequest（physical_model_attribute_id）

响应：ThingModelAttributeDetailResponse（ThingModelAttribute）

3. 产品服务（ProductService）

• CreateProduct / UpdateProduct / DeleteProduct
• ProductList / ProductInfo
• PublishProduct / RemoveProduct / ProductPublished
• ProductAll（下拉选项列表）

关键请求示例：

message CreateProductRequest {
  string access_token = 1;
  string name = 2;                 // required
  string table_name = 3;           // optional
  NetworkType network_type = 4;    // required
  ProductType type = 5;            // required
  string desc = 6;                 // optional
  string code = 7;                 // required
  PublishStatus publish_status = 8;// optional
}

4. 设备服务（EquipmentService）

• CreateEquipment / UpdateEquipment / DeleteEquipment
• GetEquipmentList / GetEquipmentInfo
• ImportEquipment / EquipmentBatchInsert / DownloadEquipmentTemplate
• GetEquipmentChild / BindEquipmentChild / GetAllChildEquipment / RefreshEquipmentStatus
• GetEquipmentEvent / GetEquipmentLogs / GetEquipmentHistoryData
• GetEquipmentRealData
• EquipmentSetControl / EquipmentSetProperty

关键请求示例：

message CreateEquipmentRequest {
  string access_token = 1;
  string name = 2;                 // required
  string equipment_sn = 3;         // required
  int64 product_id = 4;            // required
  string drive_sign = 5;           // required
  string sim_number = 6;           // optional
  double lat = 7;                  // optional
  double lng = 8;                  // optional
  int64 parent_id = 9;             // optional
  repeated StaticAttribute static_attribute = 10; // optional
}

message EquipmentSetControlRequest {
  string access_token = 1;
  string equipment_sn = 2;                  // required
  map<string, google.protobuf.Any> params = 3; // 控制参数
  int32 is_sync = 4;                        // 是否同步
  int32 time_out = 5;                       // 超时时间
}

message GetEquipmentRealDataResponse {
  string code = 1;
  string message = 2;
  map<string, SensorData> real = 3; // 实时数据映射
}

状态码说明

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

使用示例（Go）

创建物模型示例

conn, _ := grpc.Dial("localhost:50051", grpc.WithTransportCredentials(insecure.NewCredentials()))
defer conn.Close()
cli := pb.NewThingModelServiceClient(conn)
resp, err := cli.CreateThingModel(ctx, &pb.CreateThingModelRequest{
  AccessToken: "token",
  Name:        "环境监测模型",
  TableName:   "env_model",
  Logo:        "https://example.com/logo.png",
})
_ = resp; _ = err

创建产品并发布示例

pcli := pb.NewProductServiceClient(conn)
_, _ = pcli.CreateProduct(ctx, &pb.CreateProductRequest{
  AccessToken:  "token",
  Name:         "温湿度网关",
  TableName:    "env_model",
  NetworkType:  pb.NetworkType_NETWORK_TYPE_ETHERNET,
  Type:         pb.ProductType_PRODUCT_TYPE_GATEWAY,
  Code:         "GW-ENV-01",
})
_, _ = pcli.PublishProduct(ctx, &pb.PublishProductRequest{AccessToken: "token", ProductId: 1})

创建设备示例

ecli := pb.NewEquipmentServiceClient(conn)
_, _ = ecli.CreateEquipment(ctx, &pb.CreateEquipmentRequest{
  AccessToken:  "token",
  Name:         "车间1#温湿度计",
  EquipmentSn:  "SN0001",
  ProductId:    1,
  DriveSign:    "modbus_tcp",
  StaticAttribute: []*pb.StaticAttribute{{
    AttrName:  "install_pos",
    AttrValue: "Room-A",
    AttrCode:  "pos",
  }},
})

获取实时数据示例

real, _ := ecli.GetEquipmentRealData(ctx, &pb.GetEquipmentRealDataRequest{
  AccessToken: "token",
  Sn:          "SN0001",
})
for code, point := range real.Real {
  fmt.Println(code, point.Value, point.Unit, point.Time)
}

下发控制示例（异步）

ctrl, _ := ecli.EquipmentSetControl(ctx, &pb.EquipmentSetControlRequest{
  AccessToken: "token",
  EquipmentSn: "SN0001",
  Params:      map[string]*anypb.Any{"set_temp": anypb.New(&wrapperspb.DoubleValue{Value: 26})},
  IsSync:      0,
  TimeOut:     10,
})
fmt.Println(ctrl.RequestId, ctrl.Success)

Golang 项目设置

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

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

注意事项

1. 需要认证的接口均要求携带 access_token。
2. 列表接口均支持分页与可选搜索参数，请根据需要传值。
3. 控制与属性设置的 params 使用 google.protobuf.Any，需与服务端约定好编码格式。
4. 历史数据统计结果 ResultList 的各统计字段为 Any，前后端需按约定解析。
5. 生产环境建议开启 TLS，并妥善处理超时与重试策略。