gNMI Service Definition
gNMI GetRequest
The gNMI GET RPC specifies how to retrieve one or more of the configuration attributes, state attributes, derived state attributes, or all attributes associated with a supported mode from a date tree. A GetRequest is sent from a client to the target to retrieve values from the data tree. A GetResponse is sent in response to a GetRequest.
The following example shows a Get Request on JSON structure:
XPath: /oc-if:interfaces/interface[name=Loopback111]
++++++++ Sending get request: ++++++++
path {
elem {
name: "oc-if:interfaces"
}
elem {
name: "interface"
key {
key: "name"
value: "Loopback111"
}
}
}
encoding: JSON_IETF
++++++++ Recevied get response: ++++++++
notification {
timestamp: 1521699434792345469
update {
path {
elem {
name: "oc-if:interfaces"
}
elem {
name: "interface"
key {
key: "name"
value: "\"Loopback111\""
}
}
}
val {
json_ietf_val: "{\n\t\"openconfig-interfaces:name\":\t\"Loopback111\",\n\t\
"openconfig-interfaces:config\":\t{\n\t\t\
"openconfig-interfaces:type\":\t\"ianaift:softwareLoopback\",\n\t\t\
"openconfig-interfaces:name\":\t\"Loopback111\",\n\t\t\
"openconfig-interfaces:enabled\":\t\"true\"\n\t},\n\t\
"openconfig-interfaces:state\":\t{\n\t\t\
"openconfig-interfaces:type\":\t\"ianaift:softwareLoopback\",\n\t\t\
"openconfig-interfaces:name\":\t\"Loopback111\",\n\t\t\
"openconfig-interfaces:enabled\":\t\"true\",\n\t\t\
"openconfig-interfaces:ifindex\":\t52,\n\t\t\
"openconfig-interfaces:admin-status\":\t\"UP\",\n\t\t\
"openconfig-interfaces:oper-status\":\t\"UP\",\n\t\t\
"openconfig-interfaces:last-change\":\t2018,\n\t\t\
"openconfig-interfaces:counters\":\t{\n\t\t\t\
"openconfig-interfaces:in-octets\":\t0,\n\t\t\t\
"openconfig-interfaces:in-unicast-pkts\":\t0,\n\t\t\t\
"openconfig-interfaces:in-broadcast-pkts\":\t0,\n\t\t\t\
"openconfig-interfaces:in-multicast-pkts\":\t0,\n\t\t\t\
"openconfig-interfaces:in-discards\":\t0,\n\t\t\t\
"openconfig-interfaces:in-errors\":\t0,\n\t\t\t\
"openconfig-interfaces:in-unknown-protos\":\t0,\n\t\t\t\
"openconfig-interfaces:out-octets\":\t0,\n\t\t\t\
"openconfig-interfaces:out-unicast-pkts\":\t0,\n\t\t\t\
"openconfig-interfaces:out-broadcast-pkts\":\t0,\n\t\t\t\
"openconfig-interfaces:out-multicast-pkts\":\t0,\n\t\t\t\
"openconfig-interfaces:out-discards\":\t0,\n\t\t\t\
"openconfig-interfaces:out-errors\":\t0,\n\t\t\t\
"openconfig-interfaces:last-clear\":\t2018\n\t\t},\n\t\t\
"openconfig-platform:hardware-port\":\t\"Loopback111\"\n\t},\n\t\
"openconfig-interfaces:subinterfaces\":\t{\n\t\t\
"openconfig-interfaces:index\":\t0,\n\t\t\
"openconfig-interfaces:config\":\t{\n\t\t\t\
"openconfig-interfaces:index\":\t0,\n\t\t\t\
"openconfig-interfaces:name\":\t\"Loopback111\",\n\t\t\t\
"openconfig-interfaces:enabled\":\t\"true\"\n\t\t},\n\t\t\
"openconfig-interfaces:state\":\t{\n\t\t\t\
"openconfig-interfaces:index\":\t0,\n\t\t\t\
"openconfig-interfaces:name\":\t\"Loopback111.0\",\n\t\t\t\
"openconfig-interfaces:enabled\":\t\"true\",\n\t\t\t\
"openconfig-interfaces:admin-status\":\t\"UP\",\n\t\t\t\
"openconfig-interfaces:oper-status\":\t\"UP\",\n\t\t\t\
"openconfig-interfaces:last-change\":\t2018,\n\t\t\t\
"openconfig-interfaces:counters\":\t{\n\t\t\t\t\
"openconfig-interfaces:in-octets\":\t0,\n\t\t\t\t\
"openconfig-interfaces:in-unicast-pkts\":\t0,\n\t\t\t\t\
"openconfig-interfaces:in-broadcast-pkts\":\t0,\n\t\t\t\t\
"openconfig-interfaces:in-multicast-pkts\":\t0,\n\t\t\t\t\
"openconfig-interfaces:in-discards\":\t0,\n\t\t\t\t\
"openconfig-interfaces:in-errors\":\t0,\n\t\t\t\t\
"openconfig-interfaces:out-octets\":\t0,\n\t\t\t\t\
"openconfig-interfaces:out-unicast-pkts\":\t0,\n\t\t\t\t\
"openconfig-interfaces:out-broadcast-pkts\":\t0,\n\t\t\t\t\
"openconfig-interfaces:out-multicast-pkts\":\t0,\n\t\t\t\t\
"openconfig-interfaces:out-discards\":\t0,\n\t\t\t\t\
"openconfig-interfaces:out-errors\":\t0,\n\t\t\t\t\
"openconfig-interfaces:last-clear\":\t2018\n\t\t\t}\n\t\t},\n\t\t\
"openconfig-if-ip:ipv6\":\t{\n\t\t\t\
"openconfig-if-ip:config\":\t\"false\",\n\t\t\t\
"openconfig-if-ip:state\":\t\"false\"\n\t\t}\n\t}\n}"
}
}
}
The following example shows a GetRequest on a leaf on JSON structure:
XPath: /oc-if:interfaces/interface[name=Loopback111]/state/oper-status
++++++++ Sending get request: ++++++++
path {
elem {
name: "oc-if:interfaces"
}
elem {
name: "interface"
key {
key: "name"
value: "Loopback111"
}
}
elem {
name: "state"
}
elem {
name: "oper-status"
}
}
encoding: JSON_IETF
++++++++ Recevied get response: ++++++++
notification {
timestamp: 1521699326012374332
update {
path {
elem {
name: "oc-if:interfaces"
}
elem {
name: "interface"
key {
key: "name"
value: "\"Loopback111\""
}
}
elem {
name: "state"
}
elem {
name: "oper-status"
}
}
val {
json_ietf_val: "\"UP\""
}
}
}
gNMI SetRequest
The Set RPC specifies how to set one or more configurable attributes associated with a supported model. A SetRequest is sent from a client to a target to update the values in the data tree.
Within an individual transaction (SetRequest) the order of operations is delete, replace, update.
In a SetRequest, only fully-specified (wildcards, and all keys-specified paths are not supported) paths, and only "json_ietf_val" or "json_val” TypedValue are supported. JSON keys must contain a YANG-prefix, in which the namespace of the following element differs from parent. The “routed-vlan” element derived from augmentation in openconfig-vlan.yang must be entered as “oc-vlan:routed-vlan”, because it is different from the namespace of the parent node (The parent node prefix is oc-if.).
The total set of deletes, replace, and updates contained in any one SetRequest is treated as a single transaction. If any subordinate element of the transaction fails; the entire transaction will be disallowed and rolled back. A SetResponse is sent back for a SetRequest.
In the case that any operation within the SetRequest message fails, then, the target MUST NOT apply any of the specified changes, and MUST consider the transaction as failed. The target SHOULD set the status code of the SetResponse message to Aborted (10), along with an appropriate error message, and MUST set the message field of the UpdateResult corresponding to the failed operation to an Error message indicating failure. In the case that the processed operation is not the only operation within the SetRequest the target MUST set the message field of the UpdateResult messages for all other operations, setting the code field to Aborted (10).
The following example shows a SetRequest on JSON structure:
Creating UPDATE update for /oc-if:interfaces/interface[name=Loopback111]/config/
XPath: /oc-if:interfaces/interface[name=Loopback111]/config/
++++++++ Sending set request: ++++++++
update {
path {
elem {
name: "oc-if:interfaces"
}
elem {
name: "interface"
key {
key: "name"
value: "Loopback111"
}
}
elem {
name: "config"
}
}
val {
json_ietf_val: "{\"config\":{\"openconfig-interfaces:enabled\":\"false\"}}"
}
}
++++++++ Recevied set response: ++++++++
response {
path {
elem {
name: "oc-if:interfaces"
}
elem {
name: "interface"
key {
key: "name"
value: "Loopback111"
}
}
elem {
name: "config"
}
}
op: UPDATE
}
timestamp: 1521699342123890045
The following example shows a SetRequest on leaf on JSON structure:
Creating UPDATE update for /oc-if:interfaces/interface[name=Loopback111]/config/
XPath: /oc-if:interfaces/interface[name=Loopback111]/config/
++++++++ Sending set request: ++++++++
update {
path {
elem {
name: "oc-if:interfaces"
}
elem {
name: "interface"
key {
key: "name"
value: "Loopback111"
}
}
elem {
name: "config"
}
}
val {
json_ietf_val: "{\"config\":{\"openconfig-interfaces:enabled\":\"false\"}}"
}
}
++++++++ Recevied set response: ++++++++
response {
path {
elem {
name: "oc-if:interfaces"
}
elem {
name: "interface"
key {
key: "name"
value: "Loopback111"
}
}
elem {
name: "config"
}
}
op: UPDATE
}
timestamp: 1521699342123890045
gNMI JSON_ietf_val
The JSON type indicates that the value is encoded as a JSON string as specified in RFC 7159. Additional types (such as, JSON_IETF) indicate specific additional characteristics of the encoding of the JSON data (particularly where they relate to serialization of YANG-modeled data).
The following is a sample JSON_ietf_val message:
val {
json_ietf_val:"{
"oc-if:config": {
"oc-if:description":
"UPDATE DESCRIPTION"
}
}"
}
gNMI Error Messages
When errors occur, gNMI server returns descriptive error messages. The following section displays some gNMI server error messages.
The following sample error message is displayed when the path is invalid:
gNMI Error Response:
== getRequest:
path: <
elem: <
name: "unknown-resource"
>
>
encoding: JSON_IETF
Get failed: rpc error: code = Code(385) desc = unknown resource