Search API
This chapter describes the Search API.
Overview
All search interfaces return a queryStatus, in addition to the actual search results. Search interfaces with count and offset arguments also return a queryId. The queryId is useful for retrieving more results from the same search. The queryStatus contains an integer status code and a string message about the code.
The search API provides the following interfaces:
-
DeviceDetailQueryResult getDeviceDetails(string query, list<string> deviceIds, string queryId, long count, long offset)
-
DeletedDeviceQueryResult getDeletedDevices(string deviceType, date startTime, date endTime)
-
DeviceQueryResult searchDevices(string query, list<string> fieldNames, string queryId, long count, long offset)
-
EidsForIpAddressesResult findEidsForIpAddressesByDeviceType(string deviceType, list<string> ipAddresses)
-
EidsForIpAddressesResult findEidsForIpAddresses(list<string> ipAddresses)
-
GroupQueryResult getGroups(string groupType)
-
MetricHistoryQueryResult getMetricHistory(string query, list<string> deviceIds, date startTime, date endTime, List<string> metricIds, string rollupInterval, string rollupFunction, string queryId, long count, long offset)
-
UpdatedDeviceDetailQueryResult getUpdatedDeviceDetails(string query, date startTime, date endTime, string queryId, long count, long offset)
Using the Search API
Use this IoT FND server URL to access the Search API WSDL:
http://<server_address> /nbapi/search?wsdl
Provided are these examples of client applications using the Search API.
Example 1 (Python-SUDS Client)
from suds.client import Client
import logging
logging.basicConfig(level=logging.INFO)
logging.getLogger('suds.client').setLevel(logging.INFO)
url = "http://localhost/nbapi/search?wsdl"
cl = Client(url, username='root', password='Tree123!')
globalMetrics = ['uptime']
cgmeshMetrics = ['meshHops','meshLinkCost','meshPathCost','meshRssi','meshReverseRssi','meshRxSpeed','meshTxSpeed']
cgr1kStatus = ['doorStatus','numBBU','battery0Level','battery0Runtime','battery1Level','battery1Runtime','battery2Level','battery2Runtime']
cgr1kMetrics = ['chassisTemp','ethernetTxDrops','ethernetRxSpeed','ethernetTxSpeed']
cgr1kCellIfMetrics = ['cellularRSSI','cellularRxSpeed','cellularTxSpeed']
cgr1kWiMAXIfMetrics = ['wimaxRSSI','wimaxRxSpeed','wimaxTxSpeed']
cgr1kMeshIfMetrics = ['meshEndpointCount','meshRxSpeed','meshTxSpeed']
# search FAN router devices
devices = []
result = cl.service.searchDevices('deviceType:cgr1000 status:down',['lng','lat','ip'],'',1000,0)
#print result
if result.queryStatus == "SUCCEEDED":
print "eid,lng,lat,ip,"
for d in result.devices:
devices.append(d.eid)
print str(d.eid)+",",
for f in d.fields.entry:
print str(f.value)+",",
print ""
Example 2 (Python-SUDS Client)
from suds.client import Client
import logging
logging.basicConfig(level=logging.INFO)
logging.getLogger('suds.client').setLevel(logging.INFO)
url = "http://localhost/nbapi/search?wsdl"
cl = Client(url, username='root', password='Tree123!')
#print cl
# search mesh end devices
devices = []
result = cl.service.searchDevices('deviceType:cgmesh',['lng','lat','ip'],'',10,0)
#print result
if result.queryStatus == "SUCCEEDED":
print "eid,lng,lat,ip,"
for d in result.devices:
devices.append(d.eid)
print str(d.eid)+",",
for f in d.fields.entry:
print str(f.value)+",",
print ""
globalMetrics = ['uptime']
cgmeshMetrics = ['meshHops','meshLinkCost','meshPathCost','meshRssi','meshReverseRssi','meshRxSpeed','meshTxSpeed']
cgr1kStatus = ['doorStatus','numBBU','battery0Level','battery0Runtime','battery1Level','battery1Runtime','battery2Level','battery2Runtime']
cgr1kMetrics = ['chassisTemp','ethernetTxDrops','ethernetRxSpeed','ethernetTxSpeed']
cgr1kCellIfMetrics = ['cellularRSSI','cellularRxSpeed','cellularTxSpeed']
cgr1kWiMAXIfMetrics = ['wimaxRSSI','wimaxRxSpeed','wimaxTxSpeed']
cgr1kMeshIfMetrics = ['meshEndpointCount','meshRxSpeed','meshTxSpeed']
# get device metric history
result = cl.service.getMetricHistory('status:up',[str(devices[0]),str(devices[1]),str(devices[2])],'2012-04-01 00:00:00','2012-04-01 23:59:59',cgmeshMetrics,'day','avg','',2,0)
#print result
if (result.queryStatus == "SUCCEEDED"):
try:
result.metricValues
except:
print "no metrics returned"
else:
print "eid,metric,value,timestamp,"
for m in result.metricValues:
print str(m.eid), ",", str(m.metricId),",", str(m.value),",", str(m.timestamp)
# search FAN router devices
devices = []
result = cl.service.searchDevices('deviceType:cgr1000',['lng','lat','ip'],'',10,0)
#print result
if result.queryStatus == "SUCCEEDED":
print "eid,lng,lat,ip,"
for d in result.devices:
devices.append(d.eid)
print str(d.eid)+",",
for f in d.fields.entry:
print str(f.value)+",",
print ""
# get device metric history
for f in devices:
result = cl.service.getMetricHistory('status:up',f,'2012-04-01 00:00:00','2012-04-01 23:59:59',cgr1kMetrics+cgr1kCellIfMetrics+cgr1kWiMAXIfMetrics+cgr1kMeshIfMetrics,'day','avg','',0,0)
#print result
if (result.queryStatus == "SUCCEEDED"):
try:
result.metricValues
except:
print "no metrics returned"
else:
print "eid,metric,value,timestamp,"
for m in result.metricValues:
print str(m.eid), ",", str(m.metricId),",", str(m.value),",", str(m.timestamp)
Example 3 (Python-SUDS Client)
import sys
from suds.client import Client
import logging
logging.basicConfig(level=logging.INFO)
logging.getLogger('suds.client').setLevel(logging.DEBUG)
url = "http://localhost/nbapi/search?wsdl"
cl = Client(url, username='root', password='Tree123!')
# get config groups
groups = ['DeviceType','Status','ConfigGroup','FirmwareGroup','TunnelProvisioningGroup','Label']
for g in groups:
result = cl.service.getGroups(g)
#print result
if result.queryStatus == "SUCCEEDED":
print g
for r in result.groups:
print r.name,
if (r.properties != None and r.properties != ""):
for p in r.properties.entry:
if (p.key == "description" or p.key == "deviceType"):
print p.value,
if r.memberCount != None:
print "x " + str(r.memberCount) + ",",
print ""
print ""
# search devices
devices = []
result = cl.service.searchDevices('status:up',['lng','lat','ip'],'',10,0)
#print result
if result.queryStatus == "SUCCEEDED":
print "eid,lng,lat,ip,"
for d in result.devices:
devices.append(d.eid)
print str(d.eid)+",",
for f in d.fields.entry:
print str(f.value)+",",
print ""
# fetch mesh endpoint node device details
metrics = ("uptime","nodeLocalTime","meshHops","meshRssi","meshReverseRssi","meshLinkCost","meshPathCost","meshRxSpeed","meshTxSpeed","meshTxDrops")
properties = ("sn","deviceType","pid","lng","lat","alt","geoHash","mapLevel","lastHeard","status","configInSync","runningFirmwareVersion","hardwareId","vid","certSN","certL","certO","certCN","certST","certOU","certC")
devices = []
result = cl.service.searchDevices('deviceType:cgmesh','','',10,0)
if result.queryStatus == "SUCCEEDED":
for d in result.devices:
devices.append(d.eid)
print devices
if len(devices) != 0:
fn = "./cgmeshDevDetails.csv"
f = open(fn, 'w')
#fetch device details
print >>f, "eid,configGroup,firmwareGroup,",
for p in properties:
print >>f, p+",",
for m in metrics:
print >>f, m+",",
print >>f, "interfaces"
for d in devices:
result = cl.service.getDeviceDetails('',d,'',0,0)
#print result
if result.queryStatus == "SUCCEEDED":
print >>f, d+","+result.deviceDetails[0].configGroup+","+result.deviceDetails[0].firmwareGroup+",",
for p in properties:
for j in result.deviceDetails[0].properties.entry:
if j.key == p:
try:
j.value
except:
pass
else:
if j.value != "null":
print >>f, j.value,
print >>f, ",",
for m in metrics:
for j in result.deviceDetails[0].metrics.entry:
if j.key == m:
print >>f, j.value,
print >>f, ",",
for i in result.deviceDetails[0].interfaces:
print >>f, i.name,
print >>f, ""
# fetch FAN router details
metrics = ["uptime","chassisTemp","ethernetTxSpeed","ethernetRxSpeed","ethernetTxDrops","meshEndpointCount","meshRxSpeed","meshTxSpeed"]
properties = ["sn","deviceType","pid","lng","lat","alt","geoHash","mapLevel","lastHeard","status","doorStatus","bbuPresent","numBBU","configInSync","runningFirmwareVersion","hardwareId","vid","certSN","certL","certO","certCN","certST","certOU","certC","meshPanidConfig","meshLinkKeyRefresh","meshLinkKeyExpiration","meshPrefixConfig","powerSource","ip","hostname","domainName","meshPrefixLengthConfig","meshPrefix","meshPrefixLength","meshAddressConfig","meshAddress"]
devices = []
result = cl.service.searchDevices('deviceType:cgr1000','','',10,0)
#print result
if result.queryStatus == "SUCCEEDED":
for d in result.devices:
devices.append(d.eid)
print devices
if len(devices) != 0:
fn = "./cgr1kDevDetails.csv"
f = open(fn, 'w')
#fetch device details
print >>f, "eid,configGroup,firmwareGroup,",
for p in properties:
print >>f, p+",",
for m in metrics:
print >>f, m+",",
print >>f, "interfaces"
for d in devices:
result = cl.service.getDeviceDetails('',d,'',0,0)
#print result
if result.queryStatus == "SUCCEEDED":
print >>f, d+","+result.deviceDetails[0].configGroup+","+result.deviceDetails[0].firmwareGroup+",",
for p in properties:
for j in result.deviceDetails[0].properties.entry:
if j.key == p:
try:
j.value
except:
pass
else:
if j.value != "null":
print >>f, j.value,
print >>f, ",",
for m in metrics:
for j in result.deviceDetails[0].metrics.entry:
if j.key == m:
print >>f, j.value,
print >>f, ",",
for i in result.deviceDetails[0].interfaces:
print >>f, i.name,
print >>f, ""
Using the search-client Script
The IoT FND distribution provides a Search API client (search-client script) in the cgms-tools-version .x86_64.rpm package. The client is wrapped by a shell script (/opt/cgms-tools/bin/search-client) for communicating with the IoT FND API.
[root@localhost bin]# ./search-client
usage:
./search-client device <endpoint URL> <query> <field names> <count> <offset>
./search-client device <endpoint URL> <query Id> <field names>
./search-client deviceDetail <endpoint URL> <query> <count> <offset>
./search-client deviceDetail <endpoint URL> <query Id>
./search-client deviceDetail <endpoint URL> <device eid list>
./search-client updatedDeviceDetail <endpoint URL> <query> <startTime> <endTime> <count> <offset>
./search-client updatedDeviceDetail <endpoint URL> <queryId>
./search-client deletedDevice <endpoint URL> <deviceType> <startTime> <endTime>
./search-client group <endpoint URL> <group type>
<group type> can be deviceType, label, status, configGroup, firmwareGroup, tunnelGroup or
subnetGroup
./search-client metricHistory <endpoint URL> <query> <startTime> <endTime> <field names>
<rollupInterval> <rollupFunction> <count> <offset>
./search-client metricHistory <endpoint URL> <queryId>
./search-client metricHistory <endpoint URL> <device eid list> <startTime> <endTime> <field names>
<rollupInterval> <rollupFunction>
./search-client eidByAddresses <endPoint URL> <deviceIps>
./search-client ReprovisionByEids <endPoint URL> <groupName> <deviceEids> <interfaceName>
<interfaceType>
The following table lists search-client script commands.
|
Command |
Description |
|---|---|
|
device |
Calls the searchDevices API. |
|
deviceDetail |
Calls the getDeviceDetails API. |
|
deletedDevice |
Calls the getDeletedDevices API. |
|
eidByAddresses |
Calls the findEidsForIpAddresses API. |
|
event |
Calls the getUpdatedDeviceDetails API. |
|
group |
Calls the getGroups API. |
|
issues |
Calls the getUpdatedDeviceDetails API. |
|
meshFirmwareUpgrade |
Calls the getUpdatedDeviceDetails API. |
|
metricHistory |
Calls the getMetricHistory API. |
|
updatedDeviceDetail |
Calls the getUpdatedDeviceDetails API. |
|
work order |
Calls the getUpdatedDeviceDetails API. |
Search API Method Calls
- searchDevices
- getGroups
- getDeviceDetails
- getDeletedDevices
- getUpdatedDeviceDetails
- getMetricHistory
- findEidsForIpAddresses
- findEidsForIpAddressesByDeviceType
searchDevices
This call lets the client provide a search query string (using the query language) and returns a list of device details (properties or metrics).
Prototype
DeviceQueryResult searchDevices (string query, list<string> fieldNames, string queryId, long count, long offset)
Parameters
|
Parameter |
Type |
Description |
|---|---|---|
|
query |
string |
Search query string. |
|
fieldNames |
string |
List of property or metric names to retrieve for each device. For information about properties and metrics, see Property Field Names for All Devices and Metrics Field Names. |
|
queryId |
string |
Query ID returned by the call. If available results for the query is more than count, the caller can use the returned queryId to call the same API repeatedly. When queryId is provided, all other parameters are ignored. |
|
count |
long |
Number of results to retrieve. Valid range is 1–40000. |
|
offset |
long |
Position of the first result. Valid values are >= 0. |
Results
The following table lists device details returned by this call.
|
Name |
Type |
Description |
|---|---|---|
|
eid |
string |
Device ID. |
|
fields |
map<string.string> |
A list of fieldname-value pairs. |
|
key |
long |
A long value associated with the device. |
searchDevices SOAP XML Request Format
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sear="http://search.nbapi.cgms.cisco.com/">
<soapenv:Header/>
<soapenv:Body>
<sear:searchDevices>
<!--Optional:-->
<query>deviceType:cgr1000</query>
<!--Zero or more repetitions:-->
<fieldNames></fieldNames>
<!--Optional:-->
<queryId></queryId>
<!--Optional:-->
<count>10</count>
<!--Optional:-->
<offset>0</offset>
</sear:searchDevices> </soapenv:Body>
</soapenv:Envelope>
getGroups
This call lets the client retrieve the following:
-
List of groups for a specific group type within the system
-
Current number of members in each group
-
Properties assigned to the group
Group types are any one of the following strings:
-
deviceType
-
status
-
label
-
configGroup
-
firmwareGroup
-
subnetGroup
-
tunnelProvisioningGroup
Prototype
GroupQueryResult getGroups (string groupType)
Parameters
|
Parameter |
Type |
Description |
|---|---|---|
|
groupType |
string |
Group type strings from the above list. |
Results
The following table lists groups returned by this call.
|
Name |
Type |
Description |
|---|---|---|
|
name |
string |
Name of the group. |
|
memberCount |
long |
Number of devices in the group. |
|
properties |
map<string, string> |
Property name-value pairs. |
getGroups SOAP XML Request Format
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sear="http://search.nbapi.cgms.cisco.com/">
<soapenv:Header/>
<soapenv:Body>
<sear:getGroups>
<!--Optional:-->
<groupType>devicetype</groupType>
</sear:getGroups>
</soapenv:Body>
</soapenv:Envelope>
getDeviceDetails
This call lets the client retrieve the following information:
-
Address list information:
-
Address
-
addressType
-
Key
-
prefixLength
-
-
Assets list information:
-
Key
-
Name
-
Asset metrics
-
Asset properties
-
-
ConfigGroup as a string
-
EID as a string
-
FirmwareGroup as a string
-
Interface list information:
-
Interface key
-
Interface name
-
Interface index
-
Interface addresses list
-
Interface metrics
-
Interface properties
-
-
Key as a long integer
-
Labels list
-
Metrics list
-
Properties list
-
SubnetGroup as a string
-
Route list information:
-
Index
-
Key
-
Route metrics
-
Route properties
-
Devices are retrieved by specifying a query or a list. For example, the Route properties key-value pair information retrieved is:
destAddressType:2 nextHopAddressType:4 nextHopAddress : fe80:0:0:0:207:8108:3c:270b destAddress:0:0:0:0:0:0:0:0 prefixLength:0
Prototype
DeviceDetailQueryResult getDeviceDetails (string query, list<string> deviceIds, string queryId,long count, long offset)
Parameters
|
Parameter |
Type |
Description |
|---|---|---|
|
query |
string |
Search query. |
|
deviceIds |
list<string> |
List of device EIDs to retrieve. When deviceIds is provided, the query parameter is ignored. |
|
queryId |
string |
Query ID returned by the call. If available results for the query is more than count, the caller can use the returned queryId to call the same API repeatedly. When queryId is provided, all other parameters are ignored. |
|
count |
long |
Number of results to retrieve. Valid range is 1–40000 |
|
offset |
long |
Position of the first result. Valid values are >= 0. |
Results
Parameters returned by this call are listed in the following table.
|
Parameter |
Type |
Description |
|---|---|---|
|
addresses |
list<address> |
A list of addresses known to the device. See Table 3. |
|
assets |
list<asset> |
A list of assets installed on the device. See Table 6. |
|
configGroup |
string |
The name of the configuration group assigned to the device. |
|
eid |
string |
The string ID of the device. |
|
firmwareGroup |
string |
The name of the firmware group assigned to the device. |
|
interfaces |
list<interface> |
A list of interfaces of the device. See Table 4. |
|
labels |
list<string> |
The list of labels assigned to the device. |
|
key |
long |
A long value associated with the device. |
|
metrics |
map<string, double> |
Metric type-value pairs. See Metrics Field Names . |
|
properties |
map<string, string> |
Property name-value pairs. See Property Field Names for All Devices . |
|
routes |
list<route> |
A list of routes known to the device. See Table 5. |
|
subnetGroup |
string |
The name of the subnet group assigned to the device. |
The following table describes the Address attributes.
|
Attribute |
Type |
Description |
|---|---|---|
|
key |
long |
A long value associated with the address. |
|
addressType |
string |
Value is one of these address types: IPV4, IPV6, IPV4Z, IPV6Z or UNKNOWN. |
|
address |
string |
The IP address. |
|
prefixLength |
integer |
Subnet prefix length of the address. |
The following table describes the Interface attributes.
|
Attribute |
Type |
Description |
|---|---|---|
|
key |
long |
A long value associated with the interface. |
|
index |
integer |
Index value of the interface. |
|
name |
string |
The name of the interface. |
|
addresses |
list<address> |
List of Address (see Table 3) associated with the interface. |
|
properties |
map<string, string> |
Properties of the interface in name-value pairs. |
|
metrics |
map<string, double> |
Metrics of the interface. |
The following table describes the Route attributes.
|
Attribute |
Type |
Description |
|---|---|---|
|
key |
long |
A long value associated with the route. |
|
index |
integer |
Index value of the route. |
|
properties |
map<string, string> |
Properties of the route in name-value pairs. |
|
metrics |
map<string, double> |
Metrics of the route. |
The following table describes the Asset attribute parameters.
|
Attribute |
Type |
Description |
|---|---|---|
|
key |
long |
A long value associated with the asset. |
|
name |
string |
The name of the asset. |
|
properties |
map<string, string> |
Properties of the asset in name-value pairs. |
|
metrics |
map<string, double> |
Metrics of the asset. |
getDeviceDetails SOAP XML Request Format for a FAR
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sear="http://search.nbapi.cgms.cisco.com/">
<soapenv:Header/>
<soapenv:Body>
<sear:getDeviceDetails>
<!--Optional:-->
<query>far_test2</query>
<!--Zero or more repetitions:-->
<deviceIds>+JSJ1522003G</deviceIds>
<!--Optional:-->
<queryId></queryId>
<!--Optional:-->
<count>5</count>
<!--Optional:-->
<offset>0</offset>
</sear:getDeviceDetails>
</soapenv:Body>
</soapenv:Envelope>
getDeviceDetails SOAP XML Request Format for a Mesh Device
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sear="http://search.nbapi.cgms.cisco.com/">
<soapenv:Header/>
<soapenv:Body>
<sear:getDeviceDetails>
<!--Optional:-->
<query>deviceType:cgmesh status:up</query>
<!--Zero or more repetitions:-->
<deviceIds></deviceIds>
<!--Optional:-->
<queryId></queryId>
<!--Optional:-->
<count>10</count>
<!--Optional:-->
<offset>0</offset>
</sear:getDeviceDetails>
</soapenv:Body>
</soapenv:Envelope>
Response
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header>
<seam:conversationId xmlns:seam="http://www.jboss.org/seam/webservice">1125</seam:conversationId>
</env:Header>
<env:Body>
<ns2:getDeviceDetailsResponse xmlns:ns2="http://search.nbapi.cgms.cisco.com/">
<deviceDetailQueryResult>
<queryId>E6FDA0F0D3E0ADFFF69E334462D1EF6A</queryId>
<queryStatus>SUCCEEDED</queryStatus>
</deviceDetailQueryResult>
</ns2:getDeviceDetailsResponse>
</env:Body>
</env:Envelope>
getDeletedDevices
This call retrieves information of devices deleted within a time period.
Prototype
DeletedDeviceQueryResult getDeletedDevices (string deviceType, date startTime, date endTime)
Parameters
|
Parameter |
Type |
Description |
|---|---|---|
|
deviceType |
string |
The name of the device type to filter the results by. For example, cgr1000 only matches deleted devices against CGR devices. |
|
startTime |
date |
Starting UTC date and time for the deletion interval. This is a mandatory parameter. It cannot be null. Format is YYYY-MM-DDThh:mm:ss (for example, 2015-03-25T00:00:00). |
|
endTime |
date |
Ending UTC date and time for the deletion interval. This is a mandatory parameter. It cannot be null. Use it as the startTime for the next call without retrieving repeated records. Format is YYYY-MM-DDThh:mm:ss. |
Results
The following table lists device details returned by this call.
|
Name |
Type |
Description |
|---|---|---|
|
deleteDate |
date |
The date and time of device deletion. |
|
deviceType |
string |
The device type of the deleted device. |
|
eid |
string |
Device ID. |
search-client Script Example
search-client deletedDevice https://kml-lnx2/nbapi/search?wsdl "cgr1000" "2015-03-25 12:00:00" "2015-03-26 12:00:00"
search-client Script Results
URL: https://kml-lnx2/nbapi/search?wsdl
Mar 25, 2015 5:16:43 PM org.apache.cxf.service.factory.ReflectionServiceFactoryBean buildServiceFromWSDL
INFO: Creating Service {http://search.nbapi.cgms.cisco.com/}SearchWebService from WSDL: https://kml-lnx2/nbapi/search?wsdl
Mar 25, 2015 5:16:44 PM org.apache.cxf.service.factory.ReflectionServiceFactoryBean buildServiceFromWSDL
INFO: Creating Service {http://search.nbapi.cgms.cisco.com/}SearchWebService from WSDL: https://kml-lnx2/nbapi/search?wsdl
{"deleteDate":"Wed Mar 25 16:00:44 PDT 2015","deviceType":"cgr1000","eid":"CGR1240/K9+JSJ200201"}
{"deleteDate":"Wed Mar 25 16:00:44 PDT 2015","deviceType":"cgr1000","eid":"CGR1240/K9+JSJ200202"}
Elapsed Time: [169] ms
Status: Query succeeded
Rows: 2
SOAP XML Request Format
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sear="http://search.nbapi.cgms.cisco.com/">
<soapenv:Header/>
<soapenv:Body>
<sear:getDeletedDevices>
<deviceType>cgr1000</deviceType>
<startTime>2015-03-25T00:00:00</startTime>
<endTime>2015-03-26T00:00:00</endTime>
</sear:getDeletedDevices>
</soapenv:Body>
</soapenv:Envelope>
Response
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<ns2:getDeletedDevicesResponse xmlns:ns2="http://search.nbapi.cgms.cisco.com/">
<deletedDeviceQueryResult>
<queryStatus>SUCCEEDED</queryStatus>
<deletedDevices>
<deleteDate>2015-03-25T23:00:44Z</deleteDate>
<deviceType>cgr1000</deviceType>
<eid>CGR1240/K9+JSJ200201</eid>
</deletedDevices>
<deletedDevices>
<deleteDate>2015-03-25T23:00:44Z</deleteDate>
<deviceType>cgr1000</deviceType>
<eid>CGR1240/K9+JSJ200202</eid>
</deletedDevices>
</deletedDeviceQueryResult>
</ns2:getDeletedDevicesResponse>
</soap:Body>
</soap:Envelope>
Example Python Request
#!/usr/local/bin/python
from suds.transport.https import HttpAuthenticated
from suds.client import Client
import logging
from datetime import timedelta,date,datetime,tzinfo
import requests
from requests.auth import HTTPBasicAuth
import datetime
#transport = HttpAuthenticated(username='root',password='PeterChen123!')
transport = HttpAuthenticated(username='root',password='Private123!')
#WSDL_URL= "https://172.27.126.110/nbapi/search/?wsdl"
WSDL_URL= "https://kml-lnx2/nbapi/search/?wsdl"
client = Client(WSDL_URL, faults=False,cachingpolicy=1,location=WSDL_URL,transport=transport)
print(client)
deviceType="cgr1000"
string_start_date = "2015-03-25 12:00:00.78200"
string_end_date = "2016-03-26 12:00:00.78200"
startTime = datetime.datetime.strptime(string_start_date, "%Y-%m-%d %H:%M:%S.%f")
endTime= datetime.datetime.strptime(string_end_date, "%Y-%m-%d %H:%M:%S.%f")
count=5
offset =0
searchthis = client.service.getDeletedDevices(deviceType,startTime,endTime)
print(searchthis)
Results
Suds ( https://fedorahosted.org/suds/ ) version: 0.6
Service ( SearchWebService ) tns="http://search.nbapi.cgms.cisco.com/"
Prefixes (1)
ns0 = "http://search.nbapi.cgms.cisco.com/"
Ports (1):
(SearchWebServicePort)
Methods (8):
findEidsForIpAddresses(xs:string[] ipAddresses)
findEidsForIpAddressesByDeviceType(xs:string deviceType, xs:string[] ipAddresses)
getDeletedDevices(xs:string deviceType, xs:dateTime startTime, xs:dateTime endTime)
getDeviceDetails(xs:string query, xs:string[] deviceIds, xs:string queryId, xs:long count, xs:long offset)
getGroups(xs:string groupType)
getMetricHistory(xs:string query, xs:string[] deviceIds, xs:dateTime startTime, xs:dateTime endTime, xs:string[] metricIds, xs:string rollupInterval, xs:string rollupFunction, xs:string queryId, xs:long count, xs:long offset)
getUpdatedDeviceDetails(xs:string query, xs:dateTime startTime, xs:dateTime endTime, xs:string queryId, xs:long count, xs:long offset)
searchDevices(xs:string query, xs:string[] fieldNames, xs:string queryId, xs:long count, xs:long offset)
Types (36):
Exception
address
asset
deletedDevice
deletedDeviceQueryResult
device
deviceDetail
deviceDetailQueryResult
deviceQueryResult
eidsForIpAddressesResult
findEidsForIpAddresses
findEidsForIpAddressesByDeviceType
findEidsForIpAddressesByDeviceTypeResponse
findEidsForIpAddressesResponse
getDeletedDevices
getDeletedDevicesResponse
getDeviceDetails
getDeviceDetailsResponse
getGroups
getGroupsResponse
getMetricHistory
getMetricHistoryResponse
getUpdatedDeviceDetails
getUpdatedDeviceDetailsResponse
group
groupQueryResult
interface
metricHistoryQueryResult
metricValue
queryResult
queryStatus
route
searchDevices
searchDevicesResponse
updatedDeviceDetail
updatedDeviceDetailQueryResult
(200, (deletedDeviceQueryResult){
queryStatus = "SUCCEEDED"
deletedDevices[] =
(deletedDevice){
deleteDate = 2015-03-25 23:00:44+00:00
deviceType = "cgr1000"
eid = "CGR1240/K9+JSJ200201"
},
(deletedDevice){
deleteDate = 2015-03-25 23:00:44+00:00
deviceType = "cgr1000"
eid = "CGR1240/K9+JSJ200202"
},
})
getUpdatedDeviceDetails
This call lets the client retrieve the following information of devices updated within a specified time period:
-
key
-
eid
-
configGroup
-
event
-
firmwareGroup
-
issues
-
Labels list
-
meshDeviceOps
-
workorder
-
Updated Properties list
-
Updated Metrics list
-
Updated Interfaces list
-
Updated Routes list
-
Updated Addresses list
-
Deleted Interfaces list
-
Deleted Routes list
-
Deleted Addresses list
Prototype
UpdatedDeviceDetailQueryResult getUpdatedDeviceDetails (string query, date startTime, date endTime, string queryId, long count, long offset)
Parameters
|
Parameter |
Type |
Description |
|---|---|---|
|
query |
string |
Search query. |
|
startTime |
date |
Starting UTC date and time for the updated interval. This is a mandatory parameter. It cannot be null. Format is YYYY-MM-DDThh:mm:ss (for example, 2015-03-25T00:00:00). |
|
endTime |
date |
Ending UTC date and time for the updated interval. This is a mandatory parameter. It cannot be null. Format is YYYY-MM-DDThh:mm:ss. endTime is exclusive. It can be used as the startTime for the next call without retrieving repeated records. |
|
queryId |
string |
The ID of the initial query used in subsequent calls to retrieve remaining records. |
|
count |
long |
Number of results to retrieve. Valid range is 1–40000. |
|
offset |
long |
Position of the first result. Valid values are >= 0. |
This call returns the records of devices that match the specified deviceType and have delete time >= startTime and < endTime.
Results
The following table lists the device details returned by this call. The return message, UpdatedDeviceDetailQueryResult, is a list of UpdatedDeviceDetail records.
|
Parameter |
Type |
Description |
|---|---|---|
|
configGroup |
string |
The name of the configuration group assigned to the device. |
|
deletedAddresses |
list<string> |
Deleted IP addresses. |
|
deletedInterfaces |
list<string> |
Deleted interface names. |
|
deletedRoutes |
list<string> |
Deleted route names. |
|
eid |
string |
Device string ID. |
|
event |
string |
Search for events based on device type, event name, event time, and event severity. |
|
firmwareGroup |
string |
The name of the firmware group assigned to the device. |
|
issues |
string |
Call searches for issues in the IoT FND database based on the provided criteria that return a list of those issues. |
|
key |
long |
A long value associated with the device. |
|
meshDeviceOps |
string |
Allows client applications to start and stop firmware uploads to a group of mesh devices, check their firmware upload status, obtain firmware information by firmware group, set up a backup firmware image, and schedule a firmware reload. |
|
workorder |
string |
Provides seven primary action calls to cloud-based management services. |
|
updatedAddresses |
list<address> |
The list of addresses of the device updated during the specified time interval. |
|
updatedInterfaces |
list<interface> |
The interface of the device updated during the specified time interval. |
|
updatedMetrics |
map<string, double> |
The metrics of the device updated during the specified time interval. |
|
updatedProperties |
map<string, string> |
The properties of the device updated during the specified time interval. |
|
updatedRoutes |
list<route> |
The routes of the device updated during the specified time interval. |
See Table 3, Table 4, and Table 5 for information on the Address, Interface, and Route attributes.
Example
search-client updatedDeviceDetails https://kml-lnx2/nbapi/search?wsdl "deviceCategory=router" "2015-03-25 12:00:00" "2015-03-26 12:00:00" 5 0 search-client updatedDeviceDetails https://kml-lnx2/nbapi/search?wsdl "deviceCategory=router" "2015-03-26 00:00:00" "2015-03-26 00:20:00" 2 0
Example SOAP Request
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sear="http://search.nbapi.cgms.cisco.com/">
<soapenv:Header/>
<soapenv:Body>
<sear:getUpdatedDeviceDetails>
<query>deviceCategory=router</query>
<startTime>2015-03-25T23:00:00</startTime>
<endTime>2015-03-26T00:00:00</endTime>
<count>1</count>
<offset>0</offset>
</sear:getUpdatedDeviceDetails>
</soapenv:Body>
</soapenv:Envelope>
Response
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<soap:Body>
<ns2:getUpdatedDeviceDetailsResponse xmlns:ns2="http://search.nbapi.cgms.cisco.com/">
<updatedDeviceDetailQueryResult>
<queryId>E1EA07CE9BE5536A883469707FCA602E</queryId>
<queryStatus>SUCCEEDED</queryStatus>
<updatedDeviceDetails>
<configGroup>default-c800</configGroup>
<eid>C819HGW-S-A-K9+FTX174685VB</eid>
<firmwareGroup>default-c800</firmwareGroup>
<key>270000</key>
<updatedInterfaces>
<index>1</index>
<key>290009</key>
<metrics>
<entry>
<key>rxSpeed</key>
<value>3790.8790113658024</value>
</entry>
<entry>
<key>utilBytes</key>
<value>8.40631367E8</value>
</entry>
<entry>
<key>inBytes</key>
<value>7.97480016E8</value>
</entry>
<entry>
<key>txSpeed</key>
<value>210.51087003645023</value>
</entry>
<entry>
<key>outBytes</key>
<value>4.3151351E7</value>
</entry>
<entry>
<key>txDrops</key>
<value>0.0</value>
</entry>
</metrics>
<name>GigabitEthernet0</name>
<properties>
<entry>
<key>physAddress</key>
<value>c025.5c08.e3f5</value>
</entry>
</properties>
</updatedInterfaces>
.
.
.
<updatedMetrics>
<entry>
<key>cellularBandwidth</key>
<value>0.0</value>
</entry>
<entry>
<key>cellularTxSpeed</key>
<value>0.0</value>
</entry>
<entry>
<key>ethernetTxSpeed</key>
<value>516.6779073252414</value>
</entry>
<entry>
<key>cellularBwPerCycle</key>
<value>0.0</value>
</entry>
<entry>
<key>ethernetTxDrops</key>
<value>0.0</value>
</entry>
<entry>
<key>uptime</key>
<value>1650960.0</value>
</entry>
<entry>
<key>cellularRxSpeed</key>
<value>0.0</value>
</entry>
<entry>
<key>cellularEcio</key>
<value>-11.0</value>
</entry>
<entry>
<key>ethernetRxSpeed</key>
<value>3790.8790113658024</value>
</entry>
<entry>
<key>cellConnectTime</key>
<value>93.0</value>
</entry>
<entry>
<key>cellularRssi</key>
<value>-117.0</value>
</entry>
</updatedMetrics>
<updatedProperties>
<entry>
<key>runningFirmwareImageId</key>
<value>null</value>
</entry>
<entry>
<key>lastUpdate</key>
<value>2015-03-25 23:29:19.0</value>
</entry>
<entry>
<key>lng</key>
<value>-26.9007</value>
</entry>
<entry>
<key>reloadFirmwareVersion</key>
<value>null</value>
</entry>
<entry>
<key>reloadDate</key>
<value>null</value>
</entry>
<entry>
<key>backupFirmwareVersion</key>
<value>null</value>
</entry>
<entry>
<key>slot4FirmwareImageId</key>
<value>null</value>
</entry>
<entry>
<key>deviceType</key>
<value>c800</value>
</entry>
<entry>
<key>alt</key>
<value>21</value>
</entry>
<entry>
<key>name</key>
<value>C819HGW-S-A-K9+FTX174685VB</value>
</entry>
<entry>
<key>configInSync</key>
<value>false</value>
</entry>
<entry>
<key>runningFirmwareVersion</key>
<value>15.5(0.23)T</value>
</entry>
<entry>
<key>hardwareId</key>
<value>null</value>
</entry>
<entry>
<key>vid</key>
<value>null</value>
</entry>
<entry>
<key>lat</key>
<value>26.0197</value>
</entry>
<entry>
<key>slot5FirmwareImageId</key>
<value>null</value>
</entry>
<entry>
<key>sn</key>
<value>FTX174685VB</value>
</entry>
<entry>
<key>backupFirmwareImageId</key>
<value>null</value>
</entry>
<entry>
<key>status</key>
<value>up</value>
</entry>
<entry>
<key>hostname</key>
<value>kit-819</value>
</entry>
<entry>
<key>pid</key>
<value>C819HGW-S-A-K9</value>
</entry>
<entry>
<key>lastHeard</key>
<value>2015-03-25 23:34:18.0</value>
</entry>
<entry>
<key>mapLevel</key>
<value>1</value>
</entry>
<entry>
<key>ip</key>
<value>172.27.161.82</value>
</entry>
<entry>
<key>downloadFirmwareVersion</key>
<value>null</value>
</entry>
<entry>
<key>slot6FirmwareImageId</key>
<value>null</value>
</entry>
<entry>
<key>geoHash</key>
<value>eksu5bex8r8hrfk9942g4</value>
</entry>
<entry>
<key>downloadFirmwareImageId</key>
<value>null</value>
</entry>
</updatedProperties>
</updatedDeviceDetails>
</updatedDeviceDetailQueryResult>
</ns2:getUpdatedDeviceDetailsResponse>
</soap:Body>
</soap:Envelope>
Example SOAP Request using event
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:even="http://event.nbapi.cgms.cisco.com/"> <soapenv:Header/> <soapenv:Body> <even:searchEvents> <!--Optional:--> <query>?</query> <!--Optional:--> <count>?</count> <!--Optional:--> <offset>?</offset> </even:searchEvents> </soapenv:Body> </soapenv:Envelope>
Example SOAP Request using issues
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:iss="http://issues.nbapi.cgms.cisco.com/"> <soapenv:Header/> <soapenv:Body> <iss:searchIssues> <!--Optional:--> <query>deviceType:cgr1000 issueStatus:open</query> <!--Optional:--> <count>2</count> <!--Optional:--> <offset>0</offset> </iss:searchIssues> </soapenv:Body> </soapenv:Envelope>
Example SOAP Request using meshDeviceOps
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mes="http://meshDeviceOps.nbapi.cgms.cisco.com/"> <soapenv:Header/> <soapenv:Body> <mes:getFirmwareImageInfoList> <!--Optional:--> <firmwareGroup>?</firmwareGroup> </mes:getFirmwareImageInfoList> </soapenv:Body> </soapenv:Envelope> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mes="http://meshDeviceOps.nbapi.cgms.cisco.com/"> <soapenv:Header/> <soapenv:Body> <mes:getFirmwareUploadStatus> <!--Optional:--> <firmwareGroup>?</firmwareGroup> </mes:getFirmwareUploadStatus> </soapenv:Body> </soapenv:Envelope> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mes="http://meshDeviceOps.nbapi.cgms.cisco.com/"> <soapenv:Header/> <soapenv:Body> <mes:scheduleReload> <!--Optional:--> <firmwareGroup>?</firmwareGroup> <!--Optional:--> <firmwareImageName>?</firmwareImageName> <!--Optional:--> <reloadGmtTime>?</reloadGmtTime> </mes:scheduleReload> </soapenv:Body> </soapenv:Envelope> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mes="http://meshDeviceOps.nbapi.cgms.cisco.com/"> <soapenv:Header/> <soapenv:Body> <mes:setBackupFirmwareImage> <!--Optional:--> <firmwareGroup>?</firmwareGroup> <!--Optional:--> <firmwareImageName>?</firmwareImageName> </mes:setBackupFirmwareImage> </soapenv:Body> </soapenv:Envelope> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mes="http://meshDeviceOps.nbapi.cgms.cisco.com/"> <soapenv:Header/> <soapenv:Body> <mes:startUpload> <!--Optional:--> <firmwareGroup>?</firmwareGroup> <!--Optional:--> <firmwareImageName>?</firmwareImageName> </mes:startUpload> </soapenv:Body> </soapenv:Envelope> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:mes="http://meshDeviceOps.nbapi.cgms.cisco.com/"> <soapenv:Header/> <soapenv:Body> <mes:stopUpload> <!--Optional:--> <firmwareGroup>?</firmwareGroup> </mes:stopUpload> </soapenv:Body> </soapenv:Envelope>
Example SOAP Request using queryId
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sear="http://search.nbapi.cgms.cisco.com/">
<soapenv:Header/>
<soapenv:Body>
<sear:getUpdatedDeviceDetails>
<queryId>E1EA07CE9BE5536A883469707FCA602E</queryId>
</sear:getUpdatedDeviceDetails>
</soapenv:Body>
</soapenv:Envelope>
Example SOAP Request using workorder
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wor="http://workorder.nbapi.cgms.cisco.com/"> <soapenv:Header/> <soapenv:Body> <wor:RequestSignedAuthorization> <!--Optional:--> <technicianUserName>?</technicianUserName> <!--Optional:--> <workOrderNumber>?</workOrderNumber> <!--Optional:--> <appVersion>?</appVersion> </wor:RequestSignedAuthorization> </soapenv:Body> </soapenv:Envelope> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wor="http://workorder.nbapi.cgms.cisco.com/"> <soapenv:Header/> <soapenv:Body> <wor:RequestSignedAuthorizationWithClientKey> <!--Optional:--> <technicianUserName>?</technicianUserName> <!--Optional:--> <workOrderNumber>?</workOrderNumber> <!--Optional:--> <appVersion>?</appVersion> <!--Optional:--> <appKey>?</appKey> </wor:RequestSignedAuthorizationWithClientKey> </soapenv:Body> </soapenv:Envelope> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wor="http://workorder.nbapi.cgms.cisco.com/"> <soapenv:Header/> <soapenv:Body> <wor:RequestUserAuthentication> <!--Optional:--> <userAuthInfo> <!--Optional:--> <appVersion>?</appVersion> <!--Optional:--> <scriptVersion>?</scriptVersion> </userAuthInfo> </wor:RequestUserAuthentication> </soapenv:Body> </soapenv:Envelope> <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wor="http://workorder.nbapi.cgms.cisco.com/"> <soapenv:Header/> <soapenv:Body> <wor:UploadServiceReport> <!--Zero or more repetitions:--> <serviceStatusReport> <!--Optional:--> <orderNumber>?</orderNumber> <!--Optional:--> <deviceId>?</deviceId> <!--Optional:--> <technicianUserName>?</technicianUserName> <!--Optional:--> <status>?</status> </serviceStatusReport> </wor:UploadServiceReport> </soapenv:Body> </soapenv:Envelope>
Example Python Request
IoT FND 3.0 and NB API 3.0 work with both TLS1.0 and TLS1.2.
 Note | If you use TLS1.2 with SUDS package, you must use the ActivePython package available at: |
http://www.activestate.com/blog/2015/11/activepython-vs-open-source-python-whats-difference
Note | If you use TLS1.0 with SUDS package, you must use the regular Python package available at: |
https://www.python.org/downloads/
#!/usr/local/bin/python
from suds.transport.https import HttpAuthenticated
from suds.client import Client
import logging
from datetime import timedelta,date,datetime,tzinfo
import requests
from requests.auth import HTTPBasicAuth
import datetime
transport = HttpAuthenticated(username='root',password='PeterChen123!')
WSDL_URL= "https://172.27.126.110/nbapi/search/?wsdl"
client = Client(WSDL_URL, faults=False,cachingpolicy=1,location=WSDL_URL,transport=transport)
print(client)
#query="deviceType:cgr1000"
query="deviceType:cgmesh"
#fieldNames = ["uptime","uplinkTxSpeed","uplinkTxDrops"]
string_start_date = "2014-09-28 20:30:55.78200"
string_end_date = "2015-03-25 20:30:55.78200"
startTime = datetime.datetime.strptime(string_start_date, "%Y-%m-%d %H:%M:%S.%f")
endTime= datetime.datetime.strptime(string_end_date, "%Y-%m-%d %H:%M:%S.%f")
#deviceId=["00173bab003c3500", "00173bab003c3501"]
count=5
offset =0
searchthis = client.service.getUpdatedDeviceDetails(query,startTime,endTime, "",count, offset)
print(searchthis)
Results
Suds ( https://fedorahosted.org/suds/ ) version: 0.6
Service ( SearchWebService ) tns="http://search.nbapi.cgms.cisco.com/"
Prefixes (1)
ns0 = "http://search.nbapi.cgms.cisco.com/"
Ports (1):
(SearchWebServicePort)
Methods (8):
findEidsForIpAddresses(xs:string[] ipAddresses)
findEidsForIpAddressesByDeviceType(xs:string deviceType, xs:string[] ipAddresses)
getDeletedDevices(xs:string deviceType, xs:dateTime startTime, xs:dateTime endTime)
getDeviceDetails(xs:string query, xs:string[] deviceIds, xs:string queryId, xs:long count, xs:long offset)
getGroups(xs:string groupType)
getMetricHistory(xs:string query, xs:string[] deviceIds, xs:dateTime startTime, xs:dateTime endTime, xs:string[] metricIds, xs:string rollupInterval, xs:string rollupFunction, xs:string queryId, xs:long count, xs:long offset)
getUpdatedDeviceDetails(xs:string query, xs:dateTime startTime, xs:dateTime endTime, xs:string queryId, xs:long count, xs:long offset)
searchDevices(xs:string query, xs:string[] fieldNames, xs:string queryId, xs:long count, xs:long offset)
Types (36):
Exception
address
asset
deletedDevice
deletedDeviceQueryResult
device
deviceDetail
deviceDetailQueryResult
deviceQueryResult
eidsForIpAddressesResult
findEidsForIpAddresses
findEidsForIpAddressesByDeviceType
findEidsForIpAddressesByDeviceTypeResponse
findEidsForIpAddressesResponse
getDeletedDevices
getDeletedDevicesResponse
getDeviceDetails
getDeviceDetailsResponse
getGroups
getGroupsResponse
getMetricHistory
getMetricHistoryResponse
getUpdatedDeviceDetails
getUpdatedDeviceDetailsResponse
group
groupQueryResult
interface
metricHistoryQueryResult
metricValue
queryResult
queryStatus
route
searchDevices
searchDevicesResponse
updatedDeviceDetail
updatedDeviceDetailQueryResult
(200, (updatedDeviceDetailQueryResult){
queryId = "60EF7F6ACFD8EE823AC2B8F83E545BC9"
queryStatus = "SUCCEEDED"
updatedDeviceDetails[] =
(updatedDeviceDetail){
configGroup = "default-cgmesh"
eid = "00000000001"
firmwareGroup = "default-cgmesh"
key = 261628
updatedMetrics = ""
updatedProperties =
(updatedProperties){
entry[] =
(entry){
key = "runningFirmwareImageId"
value = "null"
},
(entry){
key = "lastUpdate"
value = "2015-03-12 21:28:48.0"
},
(entry){
key = "lng"
value = "1000.0"
},
(entry){
key = "reloadFirmwareVersion"
value = "null"
},
(entry){
key = "reloadDate"
value = "null"
},
(entry){
key = "function"
value = "meter"
},
(entry){
key = "backupFirmwareVersion"
value = "null"
},
(entry){
key = "slot4FirmwareImageId"
value = "null"
},
(entry){
key = "deviceType"
value = "cgmesh"
},
(entry){
key = "alt"
value = "null"
},
(entry){
key = "name"
value = "00000000001"
},
(entry){
key = "configInSync"
value = "false"
},
(entry){
key = "runningFirmwareVersion"
value = "null"
},
(entry){
key = "hardwareId"
value = "null"
},
(entry){
key = "vid"
value = "null"
},
(entry){
key = "lat"
value = "1000.0"
},
(entry){
key = "slot5FirmwareImageId"
value = "null"
},
(entry){
key = "sn"
value = "null"
},
(entry){
key = "backupFirmwareImageId"
value = "null"
},
(entry){
key = "status"
value = "unheard"
},
(entry){
key = "hostname"
value = "null"
},
(entry){
key = "pid"
value = "null"
},
(entry){
key = "lastHeard"
value = "null"
},
(entry){
key = "mapLevel"
value = "16"
},
(entry){
key = "ip"
value = "2.2.2.11"
},
(entry){
key = "downloadFirmwareVersion"
value = "null"
},
(entry){
key = "slot6FirmwareImageId"
value = "null"
},
(entry){
key = "geoHash"
value = "null"
},
(entry){
key = "downloadFirmwareImageId"
value = "null"
},
}
},
(updatedDeviceDetail){
configGroup = "default-cgmesh"
eid = "00000000002"
firmwareGroup = "default-cgmesh"
key = 261627
updatedMetrics = ""
updatedProperties =
(updatedProperties){
entry[] =
(entry){
key = "runningFirmwareImageId"
value = "null"
},
(entry){
key = "lastUpdate"
value = "2015-03-12 21:28:48.0"
},
(entry){
key = "lng"
value = "1000.0"
},
(entry){
key = "reloadFirmwareVersion"
value = "null"
},
(entry){
key = "reloadDate"
value = "null"
},
(entry){
key = "function"
value = "meter"
},
(entry){
key = "backupFirmwareVersion"
value = "null"
},
(entry){
key = "slot4FirmwareImageId"
value = "null"
},
(entry){
key = "deviceType"
value = "cgmesh"
},
(entry){
key = "alt"
value = "null"
},
(entry){
key = "name"
value = "00000000002"
},
(entry){
key = "configInSync"
value = "false"
},
(entry){
key = "runningFirmwareVersion"
value = "null"
},
(entry){
key = "hardwareId"
value = "null"
},
(entry){
key = "vid"
value = "null"
},
(entry){
key = "lat"
value = "1000.0"
},
(entry){
key = "slot5FirmwareImageId"
value = "null"
},
(entry){
key = "sn"
value = "null"
},
(entry){
key = "backupFirmwareImageId"
value = "null"
},
(entry){
key = "status"
value = "unheard"
},
(entry){
key = "hostname"
value = "null"
},
(entry){
key = "pid"
value = "null"
},
(entry){
key = "lastHeard"
value = "null"
},
(entry){
key = "mapLevel"
value = "16"
},
(entry){
key = "ip"
value = "2.2.2.12"
},
(entry){
key = "downloadFirmwareVersion"
value = "null"
},
(entry){
key = "slot6FirmwareImageId"
value = "null"
},
(entry){
key = "geoHash"
value = "null"
},
(entry){
key = "downloadFirmwareImageId"
value = "null"
},
}
},
(updatedDeviceDetail){
configGroup = "default-cgmesh"
eid = "0007810800a80bfe"
firmwareGroup = "default-cgmesh"
key = 20127
updatedAddresses[] =
(address){
address = "fe80:0:0:0:0:0:0:1"
addressType = "IPV6"
key = 20001004
prefixLength = 64
},
(address){
address = "2010:dead:beef:cafe:0:8108:a8:bfe"
addressType = "IPV6"
key = 20001005
prefixLength = 64
},
(address){
address = "fe80:0:0:0:207:8108:a8:bfe"
addressType = "IPV6"
key = 20001006
prefixLength = 64
},
(address){
address = "0:0:0:0:0:0:0:1"
addressType = "IPV6"
key = 20001007
prefixLength = 128
},
updatedInterfaces[] =
(interface){
addresses[] =
(address){
address = "0:0:0:0:0:0:0:1"
addressType = "IPV6"
key = 20001007
prefixLength = 128
},
index = 1
key = 50004
metrics = ""
name = "lo"
properties = ""
},
(interface){
addresses[] =
(address){
address = "2010:dead:beef:cafe:0:8108:a8:bfe"
addressType = "IPV6"
key = 20001005
prefixLength = 64
},
(address){
address = "fe80:0:0:0:207:8108:a8:bfe"
addressType = "IPV6"
key = 20001006
prefixLength = 64
},
index = 2
key = 50005
metrics = ""
name = "lowpan"
properties =
(properties){
entry[] =
(entry){
key = "physAddress"
value = "0007810800a80bfe"
},
}
},
(interface){
addresses[] =
(address){
address = "fe80:0:0:0:0:0:0:1"
addressType = "IPV6"
key = 20001004
prefixLength = 64
},
index = 3
key = 50006
metrics = ""
name = "ppp"
properties =
(properties){
entry[] =
(entry){
key = "physAddress"
value = "0007810800a80bfe"
},
}
},
updatedMetrics = ""
updatedProperties =
(updatedProperties){
entry[] =
(entry){
key = "runningFirmwareImageId"
value = "null"
},
(entry){
key = "lastUpdate"
value = "2015-03-12 21:28:48.0"
},
(entry){
key = "meshPanid"
value = "26930"
},
(entry){
key = "lng"
value = "-88.66548868"
},
(entry){
key = "reloadFirmwareVersion"
value = "null"
},
(entry){
key = "activeLinkType"
value = "RF"
},
(entry){
key = "reloadDate"
value = "1970-01-01 00:00:00.0"
},
(entry){
key = "backupFirmwareVersion"
value = "null"
},
(entry){
key = "slot4FirmwareImageId"
value = "null"
},
(entry){
key = "deviceType"
value = "cgmesh"
},
(entry){
key = "alt"
value = "null"
},
(entry){
key = "name"
value = "0007810800a80bfe"
},
(entry){
key = "configInSync"
value = "true"
},
(entry){
key = "runningFirmwareVersion"
value = "5.5.62"
},
(entry){
key = "hardwareId"
value = "null"
},
(entry){
key = "vid"
value = "3.1"
},
(entry){
key = "lat"
value = "43.56901132"
},
(entry){
key = "slot5FirmwareImageId"
value = "null"
},
(entry){
key = "sn"
value = "0007810800A80BFE"
},
(entry){
key = "backupFirmwareImageId"
value = "null"
},
(entry){
key = "status"
value = "outage"
},
(entry){
key = "hostname"
value = "null"
},
(entry){
key = "pid"
value = "OWCM"
},
(entry){
key = "lastHeard"
value = "2015-02-24 18:59:52.0"
},
(entry){
key = "mapLevel"
value = "16"
},
(entry){
key = "ip"
value = "2010:dead:beef:cafe:0:8108:a8:bfe"
},
(entry){
key = "downloadFirmwareVersion"
value = "null"
},
(entry){
key = "slot6FirmwareImageId"
value = "null"
},
(entry){
key = "geoHash"
value = "dp8zy77zbk7u02v6jxzgn"
},
(entry){
key = "downloadFirmwareImageId"
value = "null"
},
(entry){
key = "previousMeshPanid"
value = "2015"
},
}
updatedRoutes[] =
(route){
index = 1
key = 100005
metrics = ""
properties =
(properties){
entry[] =
(entry){
key = "destAddressType"
value = "2"
},
(entry){
key = "nextHopAddressType"
value = "4"
},
(entry){
key = "nextHopAddress"
value = "fe80:0:0:0:207:8108:bf:a053"
},
(entry){
key = "destAddress"
value = "0:0:0:0:0:0:0:0"
},
(entry){
key = "prefixLength"
value = "0"
},
}
},
},
(updatedDeviceDetail){
configGroup = "default-cgmesh"
eid = "0007810800a80d40"
firmwareGroup = "default-cgmesh"
key = 20126
updatedAddresses[] =
(address){
address = "2010:dead:beef:cafe:0:8108:a8:d40"
addressType = "IPV6"
key = 20001009
prefixLength = 64
},
(address){
address = "fe80:0:0:0:0:0:0:1"
addressType = "IPV6"
key = 20001010
prefixLength = 64
},
(address){
address = "0:0:0:0:0:0:0:1"
addressType = "IPV6"
key = 20001011
prefixLength = 128
},
(address){
address = "fe80:0:0:0:207:8108:a8:d40"
addressType = "IPV6"
key = 20001008
prefixLength = 64
},
updatedInterfaces[] =
(interface){
addresses[] =
(address){
address = "0:0:0:0:0:0:0:1"
addressType = "IPV6"
key = 20001011
prefixLength = 128
},
index = 1
key = 50007
metrics = ""
name = "lo"
properties = ""
},
(interface){
addresses[] =
(address){
address = "2010:dead:beef:cafe:0:8108:a8:d40"
addressType = "IPV6"
key = 20001009
prefixLength = 64
},
(address){
address = "fe80:0:0:0:207:8108:a8:d40"
addressType = "IPV6"
key = 20001008
prefixLength = 64
},
index = 2
key = 50008
metrics = ""
name = "lowpan"
properties =
(properties){
entry[] =
(entry){
key = "physAddress"
value = "0007810800a80d40"
},
}
},
(interface){
addresses[] =
(address){
address = "fe80:0:0:0:0:0:0:1"
addressType = "IPV6"
key = 20001010
prefixLength = 64
},
index = 3
key = 50009
metrics = ""
name = "ppp"
properties =
(properties){
entry[] =
(entry){
key = "physAddress"
value = "0007810800a80d40"
},
}
},
updatedMetrics = ""
updatedProperties =
(updatedProperties){
entry[] =
(entry){
key = "runningFirmwareImageId"
value = "null"
},
(entry){
key = "lastUpdate"
value = "2015-03-12 21:28:48.0"
},
(entry){
key = "meshPanid"
value = "26930"
},
(entry){
key = "lng"
value = "-88.96548868"
},
(entry){
key = "reloadFirmwareVersion"
value = "null"
},
(entry){
key = "activeLinkType"
value = "RF"
},
(entry){
key = "reloadDate"
value = "1970-01-01 00:00:00.0"
},
(entry){
key = "backupFirmwareVersion"
value = "null"
},
(entry){
key = "slot4FirmwareImageId"
value = "null"
},
(entry){
key = "deviceType"
value = "cgmesh"
},
(entry){
key = "alt"
value = "null"
},
(entry){
key = "name"
value = "0007810800a80d40"
},
(entry){
key = "configInSync"
value = "true"
},
(entry){
key = "runningFirmwareVersion"
value = "5.5.42"
},
(entry){
key = "hardwareId"
value = "null"
},
(entry){
key = "vid"
value = "3.1"
},
(entry){
key = "lat"
value = "43.46901132"
},
(entry){
key = "slot5FirmwareImageId"
value = "null"
},
(entry){
key = "sn"
value = "0007810800A80D40"
},
(entry){
key = "backupFirmwareImageId"
value = "null"
},
(entry){
key = "status"
value = "outage"
},
(entry){
key = "hostname"
value = "null"
},
(entry){
key = "pid"
value = "OWCM"
},
(entry){
key = "lastHeard"
value = "2015-02-23 23:27:00.0"
},
(entry){
key = "mapLevel"
value = "16"
},
(entry){
key = "ip"
value = "2010:dead:beef:cafe:0:8108:a8:d40"
},
(entry){
key = "downloadFirmwareVersion"
value = "5.5.59"
},
(entry){
key = "slot6FirmwareImageId"
value = "null"
},
(entry){
key = "geoHash"
value = "dp8xr9333g58c96cp1ptr"
},
(entry){
key = "downloadFirmwareImageId"
value = "null"
},
(entry){
key = "previousMeshPanid"
value = "2015"
},
}
updatedRoutes[] =
(route){
index = 1
key = 100006
metrics = ""
properties =
(properties){
entry[] =
(entry){
key = "destAddressType"
value = "2"
},
(entry){
key = "nextHopAddressType"
value = "4"
},
(entry){
key = "nextHopAddress"
value = "fe80:0:0:0:207:8108:cc:e50b"
},
(entry){
key = "destAddress"
value = "0:0:0:0:0:0:0:0"
},
(entry){
key = "prefixLength"
value = "0"
},
}
},
},
(updatedDeviceDetail){
configGroup = "default-cgmesh"
eid = "0007810800bf38e7"
firmwareGroup = "default-cgmesh"
key = 20130
updatedAddresses[] =
(address){
address = "fe80:0:0:0:207:8108:bf:38e7"
addressType = "IPV6"
key = 104001023
prefixLength = 64
},
(address){
address = "fe80:0:0:0:0:0:0:1"
addressType = "IPV6"
key = 104001024
prefixLength = 64
},
(address){
address = "2011:dead:beef:cafe:0:8108:bf:38e7"
addressType = "IPV6"
key = 104001025
prefixLength = 64
},
(address){
address = "0:0:0:0:0:0:0:1"
addressType = "IPV6"
key = 104001026
prefixLength = 128
},
updatedInterfaces[] =
(interface){
addresses[] =
(address){
address = "0:0:0:0:0:0:0:1"
addressType = "IPV6"
key = 104001026
prefixLength = 128
},
index = 1
key = 250016
metrics = ""
name = "lo"
properties = ""
},
(interface){
addresses[] =
(address){
address = "fe80:0:0:0:207:8108:bf:38e7"
addressType = "IPV6"
key = 104001023
prefixLength = 64
},
(address){
address = "2011:dead:beef:cafe:0:8108:bf:38e7"
addressType = "IPV6"
key = 104001025
prefixLength = 64
},
index = 2
key = 250017
metrics = ""
name = "lowpan"
properties =
(properties){
entry[] =
(entry){
key = "physAddress"
value = "0007810800bf38e7"
},
}
},
(interface){
addresses[] =
(address){
address = "fe80:0:0:0:0:0:0:1"
addressType = "IPV6"
key = 104001024
prefixLength = 64
},
index = 3
key = 250018
metrics = ""
name = "ppp"
properties =
(properties){
entry[] =
(entry){
key = "physAddress"
value = "0007810800bf38e7"
},
}
},
updatedMetrics =
(updatedMetrics){
entry[] =
(entry){
key = "nodeLocalTime"
value = 1427113644.0
},
}
updatedProperties =
(updatedProperties){
entry[] =
(entry){
key = "runningFirmwareImageId"
value = "null"
},
(entry){
key = "lastUpdate"
value = "2015-03-23 12:27:24.0"
},
(entry){
key = "meshPanid"
value = "118"
},
(entry){
key = "lng"
value = "-87.71548868"
},
(entry){
key = "reloadFirmwareVersion"
value = "null"
},
(entry){
key = "reloadDate"
value = "null"
},
(entry){
key = "backupFirmwareVersion"
value = "null"
},
(entry){
key = "slot4FirmwareImageId"
value = "null"
},
(entry){
key = "deviceType"
value = "cgmesh"
},
(entry){
key = "alt"
value = "null"
},
(entry){
key = "name"
value = "0007810800bf38e7"
},
(entry){
key = "configInSync"
value = "false"
},
(entry){
key = "runningFirmwareVersion"
value = "5.5.42"
},
(entry){
key = "hardwareId"
value = "null"
},
(entry){
key = "vid"
value = "3.1"
},
(entry){
key = "lat"
value = "42.16901532"
},
(entry){
key = "slot5FirmwareImageId"
value = "null"
},
(entry){
key = "sn"
value = "0007810800BF38E7"
},
(entry){
key = "backupFirmwareImageId"
value = "null"
},
(entry){
key = "status"
value = "down"
},
(entry){
key = "hostname"
value = "null"
},
(entry){
key = "pid"
value = "OWCM"
},
(entry){
key = "lastHeard"
value = "2015-03-23 12:26:00.0"
},
(entry){
key = "mapLevel"
value = "16"
},
(entry){
key = "ip"
value = "2011:dead:beef:cafe:0:8108:bf:38e7"
},
(entry){
key = "downloadFirmwareVersion"
value = "null"
},
(entry){
key = "meshSsid"
value = "sjklin-internal"
},
(entry){
key = "slot6FirmwareImageId"
value = "null"
},
(entry){
key = "meterCert"
value = "host/smartmeter"
},
(entry){
key = "geoHash"
value = "dp3xguxs2fpne6gfgtjyw"
},
(entry){
key = "downloadFirmwareImageId"
value = "null"
},
(entry){
key = "meshTxPower"
value = "-34"
},
(entry){
key = "previousMeshPanid"
value = "null"
},
(entry){
key = "meshSecMode"
value = "1"
},
}
},
})
getMetricHistory
This call lets the client retrieve the historical metric values saved in the IoT FND database by specifying the following:
-
Single device
-
List of devices
-
Query that returns devices
You can also specify a rollup interval from the following:
-
none
-
hour
-
day
And a rollup function from the following:
-
avg
-
max
-
min
Prototype
MetricHistoryQueryResult getMetricHistory (string query, list<string> deviceIds, date startTime, date endTime, list<string> metricIds, string rollupInterval, string rollupFunction, string queryId, long count, long offset)
Parameters
|
Parameter |
Type |
Description |
|---|---|---|
|
query |
string |
Search query string |
|
deviceIds |
list<string> |
List of device EIDs to retrieve. |
|
startTime |
date |
Starting UTC date and time for the metric history interval; use null if not defined. |
|
endTime |
date |
Ending UTC date and time for the metric history interval; use null if not defined. |
|
metricIds |
list<string> |
List of metric type names to retrieve for each device. |
|
rollupInterval |
string |
Valid values are none, hour, or day. |
|
rollupFunction |
string |
Valid values are avg, max, or min. |
|
queryId |
string |
If available results for the query is more than count , the caller can use the returned queryId to call the same API repeatedly. When queryId is provided, all other parameters are ignored. |
|
count |
long |
Number of results to retrieve. Valid range is 1–40000 |
|
offset |
long |
Position of the first result. Valid values are >= 0. |
Results
This interface returns a list of metric values, as defined in Table 2.
|
Parameter |
Type |
Description |
|---|---|---|
|
eid |
string |
String ID of the device. |
|
metricId |
string |
Metric type name. |
|
timestamp |
date |
UTC timestamp of the metric value. |
|
value |
double |
Value of the metric. |
getMetricHistory SOAP XML Request Format
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sear="http://search.nbapi.cgms.cisco.com/">
<soapenv:Header/>
<soapenv:Body>
<sear:getMetricHistory>
<!--Optional:-->
<query>deviceType:cgr1000</query>
<!--Zero or more repetitions:-->
<deviceIds>far_test3</deviceIds>
<!--Optional:-->
<startTime>null</startTime>
<!--Optional:-->
<endTime>null</endTime>
<!--Zero or more repetitions:-->
<metricIds>1</metricIds>
<!--Optional:-->
<rollupInterval>none</rollupInterval>
<!--Optional:-->
<rollupFunction>min</rollupFunction>
<!--Optional:-->
<queryId></queryId>
<!--Optional:-->
<count>5</count>
<!--Optional:-->
<offset>1</offset>
</sear:getMetricHistory>
</soapenv:Body>
</soapenv:Envelope>
findEidsForIpAddresses
This call retrieves the EID of devices based on the IP address, and allows the Collection Engine to communicate to IoT FND which devices to migrate.
Prototype
EidsForIpAddressesResult findEidsForIpAddresses (list<string> ipAddresses)
Parameters
|
Parameter |
Type |
Description |
||
|---|---|---|---|---|
|
ipAddresses |
list<string> |
The list of IP addresses with EIDs corresponding to devices to search for.
IoT FND does not support inputs as GRE Tunnel IPv6 addresses. |
Results
This call always returns a response of type EidsForIpAddressesResult. The queryStatus value defines any errors.
On success, the eidMap contains correlations between the IP address and the EID of the device with that IP address. If an IP address is not mapped to a device, those IP addresses are included in the invalidMappings value.
The following table describes the parameters in the response.
|
Parameter |
Type |
Description |
|---|---|---|
|
eidMap |
map<string,string> |
Map of IP addresses-to-EIDs, where the address maps to a single CGR. |
|
invalidMappings |
list<string> |
List of IP addresses that did not correspond to any CGR. |
findEidsForIpAddressesByDeviceType
This call retrieves the EID of devices based on the device type, and allows the Collection Engine to communicate to IoT FND which devices to migrate.
Prototype
EidsForIpAddressesResult findEidsForIpAddressesByDeviceType (string deviceType, list<string> ipAddresses)
Parameters
|
Parameter |
Type |
Description |
||
|---|---|---|---|---|
|
deviceType |
string |
The name of the device type with EIDs corresponding to devices to search for. For example, cgr1000 only matches IP addresses against CGR devices. |
||
|
ipAddresses |
list<string> |
Returns a list of uplink IP addresses the collection engine uses to track CGR devices. WAN or IPSEC Tunnel.
IoT FND does not support inputs as GRE Tunnel IPv6 addresses. |
Results
This call always returns a response of type EidsForIpAddressesResult. The queryStatus value defines any errors.
On success, the eidMap contains correlations between the IP address and the EID of the device with that IP address. If an IP address is not mapped to a device of the specified deviceType, those IP addresses are included in the invalidMappings value.
The following table describes the parameters in the response.
|
Parameter |
Type |
Description |
|---|---|---|
|
eidMap |
map<string,string> |
Map of IP addresses-to-EIDs, where the address maps to a single CGR. |
|
invalidMappings |
list<string> |
List of IP addresses that did not correspond to any CGR. |
Feedback