Defining Junos PyEZ Operational Tables

 

You define Junos PyEZ operational (op) Tables to extract specific data from the RPC reply of an operational command executed on a device running Junos OS. 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: Junos PyEZ Op Table Parameters

Table Parameter Name

Table Parameter

Description

Table name

User-defined Table identifier.

RPC command

rpc

Request tag name of the RPC for which to return operational data.

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) One or more XPath expressions selecting 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, which 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)

A Junos PyEZ op Table is used to extract specific information from operational command output. You must include the rpc property in the op Table definition to specify the operational command for which to retrieve data.

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 in the Junos XML API Operational Developer Reference, displayed in the CLI by including the | display xml rpc option after the command, or displayed using the Junos PyEZ Device instance display_xml_rpc() method.

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 CLI commands take 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:

user@router> show interfaces media "[afgx]e*" | display xml

To select the <physical-interface> elements from this output, you include the item property with the XPath expression to 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.

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:

user@router> show interfaces media "[afgx]e*" | display xml

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 must 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.

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.

The key property also supports the XPath union ( | ) operator. For example, the LLDPNeighborTable, which is shown here for reference, can select the lldp-local-interface and lldp-local-port-id elements as keys:

When the key property uses the union operator, each key present in the RPC reply is added to the list of keys. The union 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.