10.1.15.12-06212024

Create an API Parser

This section introduces API parser, which is for retrieving and parsing data from a third-party system via API.

The following example shows how to create an API Parser to extract key metrics from a Cisco ACI network. And the functions and logics used will be explained as you walk through this example.

Go to Parser Library, then click New Advanced Parser from the drop-down menu of a folder. The parser editor will open.
Keep the default Traditional Devices option from the Qualified Device list, select Cisco ACI APIC from the second list.
(Optional): Click Advanced to configure the settings for filtering applicable devices as qualified device. For more information, see Qualified Device Filter in Advanced Parser.
Select a specific data type. In the Data Type field, select API from the first pull-down list and Cisco ACI from the second pull-down list.

Define the retrieve script which is for obtaining parser sample. the retrieve script consists of three major parts:
- Retrieve parameters: Manually input parameters required for data retrieval. The parameter values will be converted to parameters for the Build Parameters Function.
- Build Parameters function: Build the parameter objects used by the Retrieve Function. The values of the Build Parameters Function are device objects.
- Retrieve function: This function primarily serves for defining the scripts for retrieving sample data. The scripts will be submitted to the API server to be run.

No.

Function Name

Explanation

Declare Parameters

This function is to declare the parameters from user inputs at runtime.
Graphical user interface, application

Description automatically generated

This function is in the JSON format, and a sample code is as follows:

'''
Begin Declare Parameters
[
{"name": "$intf_name"} # specify the parameter name
]
End Declare
'''

The item name defined in this function refers to the name of the parameters (variables) that receives values from user input.

def BuildParameters (context, device_name, params)

This function declares the parameters from GDR, DeviceSetting, and SDN. It contains three fixed parameters:

Context — context objects called by python. It contains tenant, domain or user information.
Device_name — the names of target devices.
Params — the parameters from user inputs (defined in the Declare Parameters function. It is used to pass the parameters from user input to the current function.

This function also supports calling built-in APIs to get device or interface parameters:

GetDeviceProperties(context, dev_name, params) — the params is the parameter and its type to be retrieved. For example, {'techName': 'Cisco ACI', 'paramType': 'SDN', 'params' : ['dn', 'model'] }.
GetInterfaceProperties(context, dev_name, intf_name, params) — refer to the GetDeviceProperties API.

The type of returned values by this function is tuple (bool, list).

Copy Code

JSON

def BuildParameters(context, device_name, params):
    intf_name = params['intf_name']
    get_dn = GetInterfaceProperties(context, device_name,intf_name, {'techName': 'Cisco ACI', 'paramType': 'SDN', 'params' : ['dn'] })
    dn = get_dn['params']['dn']
    rtn_params = [{ 'devName' : device_name, 'dn' : dn, 'intfName': intf_name }]
    return rtn_params

def RetrieveData(devices)

This function is used to retrieve the data of devices based on the parameters declared in the Declare Parameters and BuildParameters functions. This function contains one parameter.

The following is a sample code of this function:

Copy Code

JSON

def RetrieveData(rtn_params):
    dn = rtn_params['dn']
    node_dn = dn.rpartition('/sys')[0]
    url = '/api/mo/' + node_dn + '/sys.json'
    rtn_params['dn'] = node_dn
    rtn_params['url'] = url
    node_data = getData(rtn_params)
    node_data = json.loads(node_data)
    uptime = node_data[0]['topSystem']['attributes']['systemUpTime']
    #333:03:58:38.000
    uptimes = uptime.replace('.000', '').split(':')
    day = 0
    hour = 0
    min = 0
    sec = 0
    padding = 4 - len(uptimes)
    if padding > 0:
        for i in range(padding):
            uptimes = ['0'] + uptimes
    if len(uptimes) == 4:
        day = int(uptimes[0])
        hour = int(uptimes[1])
        min = int(uptimes[2])
        sec = int(uptimes[3])
    uptime = 100 * (day * 86400 + hour * 3600 + min * 60 + sec)
    
    intf_name = rtn_params['intfName']
    url = '/api/mo/' + dn + '.json'
    rtn_params['url'] = url
    rtn_params['dn'] = dn
    data = getData(rtn_params)
    bandwidth = 0
    intf_status = 'Down'
    data = json.loads(data)
    intf_data = {}
    use64 = False
    traffic_in_byte = 0
    traffic_out_byte = 0
    link_error_in = 0
    link_error_out = 0
    if 'cnwPhysIf' in data[0]:
        intf_data = data[0]['cnwPhysIf']['attributes']
        bandwidth = int(intf_data['bw'])
        if bandwidth >= 4294967295:
            use64 = True
        intf_status = intf_data['operSt'].capitalize()
    elif 'cnwAggrIf' in data[0]:
        intf_data = data[0]['cnwAggrIf']['attributes']
        bandwidth = int(intf_data['bw'])
        if bandwidth >= 4294967295:
            use64 = True
        intf_status = intf_data['operSt'].capitalize()
    rtn = {'intf': [intf_name], 'intf_status': [intf_status], 'bandwidth': [bandwidth], 'traffic_in_byte': [traffic_in_byte], 'traffic_out_byte': [traffic_out_byte], 'used64couter': [use64], 'link_error_in': [link_error_in], 'link_error_out': [link_error_out], 'sys_uptime': [uptime]}
    return json.dumps(rtn)

Click Retrieve and select a device to retrieve data on this device. The system will firstly retrieve parameters, and a window will pop up for selecting devices. In the retrieving process, the system will verify the following:
- The retrieved text is in complete and standard format (for example, standard Json format).
- The "name" parameter exists.
- Each parameter has its unique name. There is no parameter name duplication.

	Note: After selecting device, a window for defining parameter will display for selecting/inputting parameter value. For $intf_name, you can select the parameter value.

Define the parser scripts to parse key metrics from the retrieved data. The parser scripts contain two parts: variable tree and parser function. Define these functions step by step:

No.

Function Name

Explanation

Declare variable tree

This function declares the metrics (variables) and the types you want to parse from the retrieved device data and generates a variable tree. The following parameters of a variable are defined:

Name — the name of the variable.
Type — the value type of a variable. The type includes string, int, bool, double and table.
Column Key — column key is only for defining table column for table type variable.

This function is in the JSON format, and a sample code is as follows:

'''
Begin Declare Variable
[
  {"name": "Intf_Info", "type": "table","columns": [
      {"name": "Interface_Name", "type": "string"},
      {"name": "adminSt", "type": "string"},
      {"name": "dn", "type": "string"}
  ]}
]
End Declare

'''

def ParseText (original_result)

This function returns the specific metric values and assigns the values to corresponding variables in the variable tree.

The following is a sample code of this function:

Copy Code

JSON

'''
Begin Declare Variable
[
]
End Declare

For sample
[
    {"name": "var1", "type": "string"},
    {"name": "table1", "type": "table", "columns": [
        {"name": "column1", "type": "int"},
        {"name": "column2", "type": "double"},
        {"name": "column3", "type": "string"},
        {"name": "column4", "type": "bool"}
    ]}
]
'''
 
def ParseText(_original_result):
    return {}

Click Parse Results, then the parsed results will be added to the pane below:

	Note: In the parsing process, the variable tree will be verified in the following aspects:1) The variable tree is in complete and standard Json format. 2) The variable tree contains name, type parameter. When it is table type, it contains column parameter. 3) Each of the variables at the same level have unique name. There is no variable name duplication for variables at the same level. 4) The variables are in the range of values for its type.

Click at the upper right corner of the page. The Parser will be saved in the Parser Library.