接口文档2（gRPC 版心跳上报）

说明：这是对“设备心跳上报”的 gRPC 版本接口设计文档，用于与现有 HTTP 接口共享同一套落库逻辑（写入 accounting.db 的 zapp_device 表）。

服务定义

gRPC HeartbeatService.ReportHeartbeat

请求参数

字段名	类型	必填	说明
`device_name`	string	是	设备唯一标识名称（如 "Android_01", "Camera_A"）
`timestamp`	int64	否	时间戳（支持秒或毫秒）。不传或为 0 时使用服务器接收时间。

响应字段

字段名	类型	说明
`code`	int32	业务状态码（成功为 200）
`message`	string	描述信息
`device_name`	string	设备名称
`status`	string	online
`last_heartbeat`	string	服务器记录的心跳时间（YYYY-MM-DD HH:MM:SS）

调用约定

service: apipy.heartbeat.v1.HeartbeatService
method: ReportHeartbeat
request type: google.protobuf.Struct
response type: google.protobuf.Struct

调用示例

Python

响应示例

Python

import time
import grpc
from google.protobuf import struct_pb2

channel = grpc.insecure_channel("your-host:50051")
call = channel.unary_unary(
    "/apipy.heartbeat.v1.HeartbeatService/ReportHeartbeat",
    request_serializer=struct_pb2.Struct.SerializeToString,
    response_deserializer=struct_pb2.Struct.FromString
)

req = struct_pb2.Struct()
req["device_name"] = "Python_Client_01"
req["timestamp"] = float(int(time.time()))

resp = call(req)
print(resp)

响应示例

{
  "code": 200,
  "message": "Heartbeat received",
  "data": {
    "device_name": "Python_Client_01",
    "status": "online",
    "last_heartbeat": "2026-03-15 22:10:05"
  }
}