gNMI 协议详解:逐字段读懂 gnmi.proto 中的 SubscribeRequest、SubscribeResponse 与 TypedValue

原创2026-11-15 09:33:031,420 阅读

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 订阅的完整报文流是:

  1. client → target:SubscribeRequest{ subscribe: SubscriptionList{ mode: STREAM, encoding: JSON_IETF, subscription: [ { path: /interfaces, mode: ON_CHANGE } ] } }
  2. target → client:若干条 SubscribeResponse{ update: Notification{...} }(初始快照,值在 val.json_ietf_val)
  3. target → client:SubscribeResponse{ sync_response: true }(快照结束标志)
  4. 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 遥测订阅的协议层就基本吃透了 🎯

登录后查看全文
gnmi