Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
 

Define Junos PyEZ Operational Tables for Parsing Structured Output

Junos PyEZ operational (op) Tables for structured output extract data from the XML output of an RPC executed on a Junos device. This enables you to quickly retrieve and review the relevant operational state information for the device.

Junos PyEZ Tables are formatted using YAML. Op Table definitions can include a number of required and optional parameters, which are summarized in Table 1.

Table 1: Parameters in Junos PyEZ Op Tables for Structured Output

Table Parameter Name

Table Parameter

Description

Table name

User-defined identifier for the Table.

RPC command

rpc

Request tag name of the RPC to execute.

RPC default arguments

args

(Optional) Default command options and arguments for the RPC.

RPC optional argument key

args_key

(Optional) Reference to a command’s optional first argument when that argument does not require a specific keyword.

If you do not include this property, you must specify the keyword, or option name, for optional arguments that are included in the get() method argument list when you retrieve the operational data.

Table item

item

XPath expression relative to the top-level element within the <rpc-reply> element that selects the items to extract from the data.

These items become the reference for the associated View.

Table item key

key

(Optional) XPath expression or a list of XPath expressions that selects the tag or tags whose values uniquely identify the Table item for items that do not use the <name> element as an identifier or for cases where composite keys are required.

If the item uses the <name> element for the identifier, you can omit this property.

Table View

view

View that is used to extract field data from the Table items.

Consider the following Junos PyEZ op Table, EthPortTable, which is included with the Junos PyEZ distribution. The Table extracts operational state information for Ethernet interfaces on the target device:

The following sections discuss the different components of the Table.

Table Name

The Table name is a user-defined identifier for the Table. The YAML file or string can contain one or more Tables. The start of the YAML document must be left justified. For example:

RPC Command (rpc)

Junos PyEZ op Tables for structured output extract specific information from the XML output of an RPC. You must include the rpc property in the op Table definition to specify the RPC to execute on a device.

The rpc value is the Junos XML request tag for a command. For example, the request tag name for the show interfaces command is get-interface-information.

The request tag can be found by using one the following methods:

  • Appending the | display xml rpc option after the command in the Junos OS CLI

  • Executing the Junos PyEZ Device instance display_xml_rpc('command', format='text') method

  • Finding the command and corresponding tag in the Junos XML API Explorer

  • Finding the command and corresponding tag in the Junos XML API Operational Developer Reference

RPC Default Arguments (args)

The optional args property defines the default command options and arguments for the RPC. These are listed as key-value pairs that are indented under args. A default argument is used when you call the get() method in your script and do not provide an argument that overrides that default.

If an option is just a flag that does not require a specific value, you can include it in the argument list by setting the option value to True in the Table definition. For example, the show interfaces media command maps to the get-interface-information request tag with the argument media: True. If an option requires a value, set the argument value to the value you want to use as the default.

Note:

If the option name in the Junos OS command-line interface (CLI) is hyphenated, you must change any dashes in the name to underscores.

By default, Junos PyEZ normalizes all Table keys and values, which strips out all leading and trailing whitespace and replaces sequences of internal whitespace characters with a single space. To disable normalization for a Table, include normalize: False in the argument list.

RPC Optional Argument Key (args_key)

You use the optional args_key property in cases where a CLI command takes an optional first argument that does not require you to explicitly specify an option name or keyword. In the following example, the show interfaces command takes an interface name as an optional argument:

The args_key property enables you to use this optional argument when retrieving operational data without having to explicitly specify the keyword or option name.

If you include the args_key property in your Table definition, you can specify the argument value but omit the option name when you retrieve the data.

If you omit the args_key property in your Table definition, you must explicitly specify the option name if you want to include this parameter when you retrieve the data.

Table Item (item)

The Table item property, which is required in all op Table definitions, identifies the data to extract from the RPC output. The item value is an XPath expression relative to the top-level element within the <rpc-reply> tag that selects the desired elements. These items become the reference for the associated View.

The following example shows sample, truncated CLI command output:

To select the <physical-interface> elements from this output, include the item property and specify the XPath that selects the element. In this case, the <physical-interface> element is a direct child of the top-level <interface-information> element, and the XPath expression for the item value is just the element name.

These items become the reference for the associated View.

Different devices can emit different output elements for the same RPC. As a result, the item’s XPath could vary depending on the system. The item property supports using the pipe ( | ) operator to specify an implicit "or" to select from multiple possible nodes. When the item property includes this operator, the key property must use a list. For example:

Table Item Key (key)

The optional key property is an XPath expression or a list of XPath expressions that selects which tag or tags are used to uniquely identify a Table item for those items that do not use the <name> element as an identifier or for cases where you want to use composite keys.

In the following command output, each <physical-interface> element is uniquely identified by its <name> child element:

If the Table item property selects the <physical-interface> elements, you can omit the key property from the Table definition if you want to use the <name> element as the key by default.

In contrast, consider the following show route brief command output:

When selecting the route-table/rt elements, there is no corresponding <name> element to uniquely identify each route entry. When the <name> identifier is absent, the key property can specify which tag or tags uniquely identify each item. In this case, you can uniquely identify each route-table/rt item by using <rt-destination> as the key.

In addition, starting in Junos PyEZ Release 2.3.0, a Table can define key: Null to indicate that a key is not required. In this case, the Table and View return the data as a simple dictionary rather than a nested one with keys.

Table items can be defined by a key consisting of a single element or multiple elements. Single-element keys use a simple XPath expression for the value of the key property. Composite keys are defined by a list of XPath expressions. Consider the following Table definition:

The composite key for this Table definition might be similar to the following:

If a composite key references a missing element, Junos PyEZ replaces the value in the key with None.

Note:

The key property must use a list when the item property includes the pipe ( | ) operator.

The key property also supports the pipe ( | ) operator, which enables the Table to select from multiple possible nodes. The operator enables you to use the same Table even in cases where different systems emit different output elements for the same RPC. For example, the LLDPNeighborTable, which is shown here for reference, can select the lldp-local-interface or lldp-local-port-id element as its key:

When the key property uses the | operator, each key present in the RPC reply is added to the list of keys. The operator can be used to specify an implicit "or" and is useful in situations where different tag names are present for different types of configurations or releases. For example, if the RPC returns lldp-local-interface as the identifier for one device, and the same RPC returns lldp-local-port-id as the identifier for another device, the Table automatically selects the appropriate key.

Table View (view)

The view property associates the Table definition with a particular View. A View maps your user-defined field names to elements in the selected Table items using XPath expressions. You can customize the View to only select the necessary elements from the Table items.