数据接入开放协议-GRPC接入

协议定义

一、接入认证

message VerifyRequest

{

string authToken = 1; // 接入管理分配的UUID

string endpointName = 2; // 定义的接入设备名

string endpointIdentify = 3; // 接入设备的ID

int64 leaseValue = 4; // 租约时间,接入侧申明数据上送间隔最大时间，单位为秒

}

message VerifyResponse

{

int32 errorCode = 1; // 结果码

string reason = 2; // 说明

string sessionID = 3; // 会话ID

}

二、接入元数据

1、全量刷新

message RefreshMetaRequest

{

repeated MetaTag tag = 1;

}

message RefreshMetaResponse

{

int32 errorCode = 1;

string reason = 2;

}

2、增加

message AddMetaRequest

{

repeated MetaTag tag = 1;

}

message AddMetaResponse

{

int32 errorCode = 1;

string reason = 2;

}

3、更新

message ModMetaRequest { repeated MetaTag tag = 1; } message ModMetaResponse { int32 errorCode = 1; string reason = 2; }

4、删除

message DelMetaRequest

{

repeated string tag = 1;

}

message DelMetaResponse

{

int32 errorCode = 1; string reason = 2;

}

三、实时数据

1、更新实时数据

message UpdateValueRequest

{

repeated NamedValue value = 1;

}

message UpdateValueResponse

{

int32 errorCode = 1;

string reason = 2;

}

2、续传历史数据

message RetransValueRequest

{

int64 sequenceNo = 1;

bytes gzValues = 2;

}

message RetransValueResponse

{

int64 sequenceNo = 1;

int32 errorCode = 2;

string reason = 3;

}

**特殊说明**：gzValues 是使用gz压缩的**ValueSequence**

四、系统对时

message SyncTimeRequest {

int64 localTimeStamp =1;

} message SyncTimeResponse

{

int64 localTimeStamp =1; int64 serverTimeStamp =2;

}

五、接口定义

service RtdService

{

rpc Verify (VerifyRequest) returns (VerifyResponse);

rpc RefreshMeta (RefreshMetaRequest) returns (RefreshMetaResponse);

rpc AddMeta (AddMetaRequest) returns (AddMetaResponse);

rpc ModMeta (ModMetaRequest) returns (ModMetaResponse);

rpc DelMeta (DelMetaRequest) returns (DelMetaResponse);

rpc UpdateValue (UpdateValueRequest) returns (UpdateValueResponse);

rpc NotifyEvent (RtdEvent) returns (google.protobuf.Empty);

rpc RetransValue (RetransValueRequest) returns (RetransValueResponse);

rpc SyncTime (SyncTimeRequest) returns (SyncTimeResponse);

}

六、接入认证

基于上述GRPC接口，调用Verify接口来执行接入认证。

参数：
请求：VerifyRequest
响应：VerifyResponse
说明：
通过GRPC的方式进行数据接入，必需要先进行接入认证。

接入认证返回值：errorCode等于100004表示接入成功，接入成功后可使用sessionID，来完成业务功能交互。未通过接入认证无法执行其他业务功能。
接入认证通过后,sessionID要求基于metaData,使用session为key，在调用他接口时作为传入信息。

七、业务功能

在调用业务功能前，必需要先通过接入认证，并获取正确的sessionID，sessionID要求通过metaData来传递到平台侧。

1、全量刷新元数据

参数：
请求：RefreshMetaRequest
响应：RefreshMetaResponse

说明：
接入侧应该在系统接入认证通过后，主动全量刷新一次当前的元数据，以确保位号数据与平台侧一致

2、增量更新元数据

参数：

• 增加
  请求：AddMetaRequest
  响应：AddMetaResponse
• 更新
  请求：ModMetaRequest
  响应：ModMetaResponse
• 删除
  请求：DelMetaRequest
  响应：DelMetaResponse

说明：
在接入侧运行期间，如果发生元数据变化，推荐使用增量的方式上送数据来实现与平台侧数据同步

3、更新实时数据

参数：
请求：UpdateValueRequest
响应：UpdateValueResponse
说明：
接入侧主动上送实时数据，如果上送的数据与元数据不一致，则数据将被丢弃

4、续传历史数据

参数：
请求：RetransValueRequest
响应：RetransValueResponse
说明：
如果接入侧由于某些原因无法上送实时数据，则可以先将数据进行本地缓存，待通讯恢复后执行续传操作

5、事件通知

参数：
请求：RtdEvent
响应：google.protobuf.Empty
说明：
预留接口，允许接入侧和平台数据应用端根据约定来上送特定数据。

6、系统对时

参数：
请求：SyncTimeRequest
响应：SyncTimeResponse
说明：
用于接入侧与平台侧进行系统对时