gNMI 协议详解:逐字段读懂 gnmi.proto 中的 SubscribeRequest、SubscribeResponse 与 TypedValue
gNMI 协议详解:逐字段读懂 gnmi.proto 中的 SubscribeRequest、SubscribeResponse 与 TypedValue
gNMI(gRPC Network Management Interface)是网络设备遥测数据采集的核心协议。本文带你逐字段读懂 gnmi.proto 中最常用的三大消息:SubscribeRequest(订阅请求)、SubscribeResponse(订阅响应)与 TypedValue(类型化数值),帮你快速掌握 gNMI 订阅遥测数据的完整链路。
一、gNMI 是什么?先看四大 RPC
gNMI 用 gRPC + Protobuf 定义了网络管理系统(client)访问设备数据树(target)的标准接口。在 proto/gnmi/gnmi.proto 中,service gNMI 一共声明了 4 个 RPC:
| RPC | 作用 | 通信模式 |
|---|---|---|
Capabilities |
查询设备支持的能力与版本 | 单次请求/响应 |
Get |
获取数据快照 | 单次请求/响应 |
Set |
修改数据树(增删改) | 单次请求/响应 |
Subscribe |
订阅路径上的数据变化 | 双向流式 |
遥测场景的主角是 Subscribe:
rpc Subscribe(stream SubscribeRequest) returns (stream SubscribeResponse);
它是一条双向流:client 持续发送 SubscribeRequest,target 持续回传 SubscribeResponse。下面逐字段拆解。
二、SubscribeRequest 逐字段解析
SubscribeRequest 是 client 发起订阅时发送的消息(gnmi.proto#L220-L231)。
2.1 顶层结构:一个 oneof + 扩展
| 字段 | 类型 | 说明 |
|---|---|---|
subscribe |
SubscriptionList |
指定订阅哪些路径(必须且只能出现在第一条消息中) |
poll |
Poll(空消息) |
触发一次轮询更新,仅 POLL 模式有效 |
extension |
gnmi_ext.Extension |
可选扩展,如 History、Depth 等 |
oneof request 的含义:首条消息必须携带 subscribe 来建立订阅;后续消息可携带 poll 主动拉取一次数据。
2.2 SubscriptionList:订阅清单
SubscriptionList(gnmi.proto#L264-L293)是请求的核心:
| 字段 | 类型 | 说明 |
|---|---|---|
prefix |
Path |
所有路径的公共前缀,用于压缩路径长度 |
subscription |
Subscription[] |
具体的订阅项列表 |
qos |
QOSMarking |
传输遥测数据时使用的 DSCP 标记 |
mode |
Mode |
订阅模式:STREAM(持续推流)/ ONCE(只发一次)/ POLL(按需轮询) |
allow_aggregation |
bool |
是否允许聚合符合 schema 标记的叶节点 |
use_models |
ModelData[] |
限定只使用哪些 YANG 模型的数据 |
encoding |
Encoding |
回传数据的编码格式 |
updates_only |
bool |
只推送增量更新,跳过初始状态快照 |
💡
mode决定"流"的形态;而每个subscription内部还能再指定采样/变更模式,两者是"粗粒度 + 细粒度"的组合关系。
2.3 Subscription:单条订阅的规则
| 字段 | 类型 | 说明 |
|---|---|---|
path |
Path |
要订阅的数据树路径 |
mode |
SubscriptionMode |
TARGET_DEFINED(设备自决)/ ON_CHANGE(变化即推)/ SAMPLE(定时采样) |
sample_interval |
uint64 |
SAMPLE 模式下两次采样的间隔(纳秒) |
suppress_redundant |
bool |
SAMPLE 模式下,值没变就不发 |
heartbeat_interval |
uint64 |
心跳间隔(纳秒),保证通道活性、防止"静默" |
heartbeat_interval 支持两种用法:与 ON_CHANGE 搭配时,即使值没变也会按心跳周期重发;与 suppress_redundant 搭配时,强制每个心跳周期至少产生一次更新。
2.4 路径怎么编码:Path 与 PathElem
Path(gnmi.proto#L142-L158)由若干 PathElem 组成:
Path {
elem: [ { name: "interfaces", key: {} },
{ name: "interface", key: { name: "eth0" } },
{ name: "state", key: {} },
{ name: "oper-status", key: {} } ]
}
每个 PathElem 含 name(节点名)和 key(列表键值 map)。仓库中 path/path.go 提供了 Path 与索引字符串互转的工具函数,例如转成 <target>/<origin>/a/b/c/d 形式。
三、SubscribeResponse 逐字段解析
SubscribeResponse(gnmi.proto#L245-L257)是 target 回传的消息,同样是一个 oneof:
| 字段 | 类型 | 说明 |
|---|---|---|
update |
Notification |
路径的变更或采样值(核心数据载体) |
sync_response |
bool |
置 true 表示初始快照已全部发完,之后进入增量阶段 |
error |
Error |
已废弃,错误改用 gRPC status 返回 |
extension |
gnmi_ext.Extension |
可选扩展 |
3.1 Notification:一次数据更新
Notification(gnmi.proto#L84-L95)是可复用的数据消息:
| 字段 | 类型 | 说明 |
|---|---|---|
timestamp |
int64 |
时间戳,距 Epoch 的纳秒数 |
prefix |
Path |
本条通知内路径的前缀 |
update |
Update[] |
值发生变化的路径-值对 |
delete |
Path[] |
被删除的路径 |
atomic |
bool |
表示这些路径总是被一起更新(原子批) |
3.2 Update:路径 + 值
| 字段 | 类型 | 说明 |
|---|---|---|
path |
Path |
变更的路径(相对前缀) |
value |
Value |
已废弃,由 val 取代 |
val |
TypedValue |
带类型的更新值(重点,见下节) |
duplicates |
uint32 |
被合并(coalesce)掉的重复更新次数 |
📌 收到
sync_response = true是遥测客户端编程的关键信号:它之前的数据是"初始快照",之后的数据才是真正的"实时增量"。仓库中 client/notification.go 与 client/query.go 就在处理这类同步语义。
四、TypedValue 逐字段解析
TypedValue(gnmi.proto#L109-L136)解决"值到底是什么类型"的问题。它用一个 oneof value 在 14 个字段中择一存放:
| 字段 | 类型 | 说明 | 对应 Encoding |
|---|---|---|---|
string_val |
string | 字符串 | ASCII |
int_val |
int64 | 有符号整数 | PROTO |
uint_val |
uint64 | 无符号整数 | PROTO |
bool_val |
bool | 布尔 | PROTO |
bytes_val |
bytes | 任意字节序列 | BYTES |
float_val |
float | 已废弃,改用 double_val |
— |
double_val |
double | 浮点数 | PROTO |
decimal_val |
Decimal64 | 已废弃,改用 double_val |
— |
leaflist_val |
ScalarArray | 混合类型标量数组 | PROTO |
any_val |
google.protobuf.Any |
protobuf.Any 编码 | PROTO |
json_val |
bytes | JSON 编码文本 | JSON |
json_ietf_val |
bytes | 按 RFC 7951 的 IETF JSON 编码 | JSON_IETF |
ascii_val |
string | 带外约定的 ASCII 文本 | ASCII |
proto_bytes |
bytes | protobuf 二进制字节(实验性) | PROTO |
选型口诀很简单:
- 编码是
PROTO→ 值落在具体标量字段(int_val、bool_val、double_val……),解析成本最低、类型最精确; - 编码是
JSON/JSON_IETF→ 值落在json_val/json_ietf_val,一个字段装下整棵子树; - 编码枚举定义见 gnmi.proto#L175-L181:
JSON = 0、BYTES = 1、PROTO = 2、ASCII = 3、JSON_IETF = 4。
⚠️ 注意:
encoding是在SubscriptionList中声明的,target 必须按声明的编码回填对应字段——这是读SubscribeResponse时最容易踩的坑。
五、动手验证:用 gnmi_cli 观察真实报文
仓库自带 CLI 工具 gnmi_cli,可以指定原始 text proto 直接发送 gNMI 请求,非常适合观察协议细节:
# 发起一次 ONCE 模式的订阅(拉一次快照)
gnmi_cli --address=<ADDRESS> -q=/interfaces -qt=once
# 持续 STREAM 订阅(变化即推)
gnmi_cli --address=<ADDRESS> -q=/interfaces -qt=stream
也可以直接传入原始 proto 文本:
gnmi_cli --address=<ADDRESS> -proto="subscribe: { subscription: { mode: ONCE, encoding: JSON_IETF } }"
想自己搭一个可交互的 gNMI 目标设备做实验,仓库提供了 fake server:testing/fake/gnmi/cmd/fake_server/server.go,配置示例见 testing/fake/gnmi/cmd/fake_server/example-config.pb.txt。
六、字段速查:一次完整 Subscribe 会话
把三大消息串起来,一条 STREAM + ON_CHANGE 订阅的完整报文流是:
- client → target:
SubscribeRequest{ subscribe: SubscriptionList{ mode: STREAM, encoding: JSON_IETF, subscription: [ { path: /interfaces, mode: ON_CHANGE } ] } } - target → client:若干条
SubscribeResponse{ update: Notification{...} }(初始快照,值在val.json_ietf_val) - target → client:
SubscribeResponse{ sync_response: true }(快照结束标志) - target → client:此后每次值变化推送新的
Notification,直到 client 断开
七、源码索引
| 内容 | 路径 |
|---|---|
| 协议核心定义 | proto/gnmi/gnmi.proto |
| 扩展消息(History/Depth/Commit) | proto/gnmi_ext/gnmi_ext.proto |
| 生成的 Go 代码 | proto/gnmi/gnmi.pb.go |
| 生成的 Python 代码 | proto/gnmi/gnmi_pb2.py |
| Go 客户端库入口 | client/client.go |
| 查询与订阅封装 | client/query.go |
| 通知处理 | client/notification.go |
| CLI 实现 | cli/cli.go |
| Path 工具函数 | path/path.go |
八、总结
SubscribeRequest用oneof区分"建立订阅(SubscriptionList)"与"触发轮询(Poll)";SubscriptionList定"大模式"(STREAM/ONCE/POLL + 编码),Subscription定"细模式"(ON_CHANGE/SAMPLE + 心跳);SubscribeResponse用oneof区分数据(update)与同步标志(sync_response),sync_response = true是从快照进入增量的分水岭;TypedValue用 14 字段的oneof承载任意类型值,字段选择由encoding决定;- 配合
gnmi_cli的原始 proto 功能,你可以亲手验证每一条字段的真实行为。
读透这三个消息,gNMI 遥测订阅的协议层就基本吃透了 🎯