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)
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
Table 2 searchDevices Parameters
|
|
|
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
searchDevices Results lists device details returned by this call.
Table 3 searchDevices Results
|
|
|
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/">
<query>deviceType:cgr1000</query>
<!--Zero or more repetitions:-->
<fieldNames></fieldNames>
</sear:searchDevices> </soapenv:Body>
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
Table 4 getGroups Parameters
|
|
|
groupType |
string |
Group type strings from the above list. |
Results
getGroups Results lists groups returned by this call.
Table 5 getGroups Results
|
|
|
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/">
<groupType>devicetype</groupType>
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:
nextHopAddress : fe80:0:0:0:207:8108:3c:270b
destAddress:0:0:0:0:0:0:0:0
Prototype
DeviceDetailQueryResult getDeviceDetails(string query, list<string> deviceIds, string queryId,
Parameters
Table 6 getDeviceDetails Parameters
|
|
|
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 getDeviceDetails Results.
Table 7 getDeviceDetails Results
Parameter |
Type |
Description |
addresses |
list<address> |
A list of addresses known to the device. See Address Attributes. |
assets |
list<asset> |
A list of assets installed on the device. See Asset Attributes. |
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 Interface Attributes. |
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 Route Attributes. |
subnetGroup |
string |
The name of the subnet group assigned to the device. |
Address Attributes describes the Address attributes.
Table 8 Address Attributes
|
|
|
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. |
Interface Attributes describes the Interface attributes.
Table 9 Interface Attributes
|
|
|
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 Address Attributes) associated with the interface. |
properties |
map<string, string> |
Properties of the interface in name-value pairs. |
metrics |
map<string, double> |
Metrics of the interface. |
Route Attributes describes the Route attributes.
Table 10 Route Attributes
|
|
|
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. |
Asset Attributes describes the Asset attribute parameters.
Table 11 Asset Attributes
|
|
|
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/">
<!--Zero or more repetitions:-->
<deviceIds>+JSJ1522003G</deviceIds>
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/">
<query>deviceType:cgmesh status:up</query>
<!--Zero or more repetitions:-->
Response
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<seam:conversationId xmlns:seam="http://www.jboss.org/seam/webservice">1125</seam:conversationId>
<ns2:getDeviceDetailsResponse xmlns:ns2="http://search.nbapi.cgms.cisco.com/">
<deviceDetailQueryResult>
<queryId>E6FDA0F0D3E0ADFFF69E334462D1EF6A</queryId>
<queryStatus>SUCCEEDED</queryStatus>
</deviceDetailQueryResult>
</ns2:getDeviceDetailsResponse>
getDeletedDevices
This call retrieves information of devices deleted within a time period.
Prototype
DeletedDeviceQueryResult getDeletedDevices(string deviceType, date startTime, date endTime)
Parameters
Table 12 getDeletedDevices Parameters
|
|
|
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
searchDevices Results lists device details returned by this call.
Table 13 getDeletedDevices Results
|
|
|
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"}
SOAP XML Request Format
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sear="http://search.nbapi.cgms.cisco.com/">
<deviceType>cgr1000</deviceType>
<startTime>2015-03-25T00:00:00</startTime>
<endTime>2015-03-26T00:00:00</endTime>
</sear:getDeletedDevices>
Response
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<ns2:getDeletedDevicesResponse xmlns:ns2="http://search.nbapi.cgms.cisco.com/">
<deletedDeviceQueryResult>
<queryStatus>SUCCEEDED</queryStatus>
<deleteDate>2015-03-25T23:00:44Z</deleteDate>
<deviceType>cgr1000</deviceType>
<eid>CGR1240/K9+JSJ200201</eid>
<deleteDate>2015-03-25T23:00:44Z</deleteDate>
<deviceType>cgr1000</deviceType>
<eid>CGR1240/K9+JSJ200202</eid>
</deletedDeviceQueryResult>
</ns2:getDeletedDevicesResponse>
Example Python Request
from suds.transport.https import HttpAuthenticated
from suds.client import Client
from datetime import timedelta,date,datetime,tzinfo
from requests.auth import HTTPBasicAuth
#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)
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")
searchthis = client.service.getDeletedDevices(deviceType,startTime,endTime)
Results
Suds ( https://fedorahosted.org/suds/) version: 0.6
Service ( SearchWebService) tns="http://search.nbapi.cgms.cisco.com/"
ns0 = "http://search.nbapi.cgms.cisco.com/"
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)
findEidsForIpAddressesByDeviceType
findEidsForIpAddressesByDeviceTypeResponse
findEidsForIpAddressesResponse
getDeletedDevicesResponse
getUpdatedDeviceDetailsResponse
updatedDeviceDetailQueryResult
(200, (deletedDeviceQueryResult){
queryStatus = "SUCCEEDED"
deleteDate = 2015-03-25 23:00:44+00:00
eid = "CGR1240/K9+JSJ200201"
deleteDate = 2015-03-25 23:00:44+00:00
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
Table 14 getUpdatedDeviceDetails Parameters
|
|
|
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
getUpdatedDeviceDetails Results lists the device details returned by this call. The return message, UpdatedDeviceDetailQueryResult, is a list of UpdatedDeviceDetail records.
Table 15 getUpdatedDeviceDetails Results
|
|
|
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 Address Attributes, Interface Attributes, and Route Attributes 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/">
<sear:getUpdatedDeviceDetails>
<query>deviceCategory=router</query>
<startTime>2015-03-25T23:00:00</startTime>
<endTime>2015-03-26T00:00:00</endTime>
</sear:getUpdatedDeviceDetails>
Response
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/>
<ns2:getUpdatedDeviceDetailsResponse xmlns:ns2="http://search.nbapi.cgms.cisco.com/">
<updatedDeviceDetailQueryResult>
<queryId>E1EA07CE9BE5536A883469707FCA602E</queryId>
<queryStatus>SUCCEEDED</queryStatus>
<configGroup>default-c800</configGroup>
<eid>C819HGW-S-A-K9+FTX174685VB</eid>
<firmwareGroup>default-c800</firmwareGroup>
<value>3790.8790113658024</value>
<value>8.40631367E8</value>
<value>7.97480016E8</value>
<value>210.51087003645023</value>
<value>4.3151351E7</value>
<name>GigabitEthernet0</name>
<value>c025.5c08.e3f5</value>
<key>cellularBandwidth</key>
<key>cellularTxSpeed</key>
<key>ethernetTxSpeed</key>
<value>516.6779073252414</value>
<key>cellularBwPerCycle</key>
<key>ethernetTxDrops</key>
<key>cellularRxSpeed</key>
<key>ethernetRxSpeed</key>
<value>3790.8790113658024</value>
<key>cellConnectTime</key>
<key>runningFirmwareImageId</key>
<value>2015-03-25 23:29:19.0</value>
<key>reloadFirmwareVersion</key>
<key>backupFirmwareVersion</key>
<key>slot4FirmwareImageId</key>
<value>C819HGW-S-A-K9+FTX174685VB</value>
<key>runningFirmwareVersion</key>
<value>15.5(0.23)T</value>
<key>slot5FirmwareImageId</key>
<value>FTX174685VB</value>
<key>backupFirmwareImageId</key>
<value>C819HGW-S-A-K9</value>
<value>2015-03-25 23:34:18.0</value>
<value>172.27.161.82</value>
<key>downloadFirmwareVersion</key>
<key>slot6FirmwareImageId</key>
<value>eksu5bex8r8hrfk9942g4</value>
<key>downloadFirmwareImageId</key>
</updatedDeviceDetailQueryResult>
</ns2:getUpdatedDeviceDetailsResponse>
Example SOAP Request using event
Example SOAP Request using issues
<query>deviceType:cgr1000 issueStatus:open</query>
Example SOAP Request using meshDeviceOps
<mes:getFirmwareImageInfoList>
<firmwareGroup>?</firmwareGroup>
</mes:getFirmwareImageInfoList>
<mes:getFirmwareUploadStatus>
<firmwareGroup>?</firmwareGroup>
</mes:getFirmwareUploadStatus>
<firmwareGroup>?</firmwareGroup>
<firmwareImageName>?</firmwareImageName>
<reloadGmtTime>?</reloadGmtTime>
<mes:setBackupFirmwareImage>
<firmwareGroup>?</firmwareGroup>
<firmwareImageName>?</firmwareImageName>
</mes:setBackupFirmwareImage>
<firmwareGroup>?</firmwareGroup>
<firmwareImageName>?</firmwareImageName>
<firmwareGroup>?</firmwareGroup>
Example SOAP Request using queryId
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sear="http://search.nbapi.cgms.cisco.com/">
<sear:getUpdatedDeviceDetails>
<queryId>E1EA07CE9BE5536A883469707FCA602E</queryId>
</sear:getUpdatedDeviceDetails>
Example SOAP Request using workorder
<wor:RequestSignedAuthorization>
<technicianUserName>?</technicianUserName>
<workOrderNumber>?</workOrderNumber>
<appVersion>?</appVersion>
</wor:RequestSignedAuthorization>
<wor:RequestSignedAuthorizationWithClientKey>
<technicianUserName>?</technicianUserName>
<workOrderNumber>?</workOrderNumber>
<appVersion>?</appVersion>
</wor:RequestSignedAuthorizationWithClientKey>
<wor:RequestUserAuthentication>
<appVersion>?</appVersion>
<scriptVersion>?</scriptVersion>
</wor:RequestUserAuthentication>
<!--Zero or more repetitions:-->
<serviceStatusReport>
<!--Optional:-->
<orderNumber>?</orderNumber>
<technicianUserName>?</technicianUserName>
</wor:UploadServiceReport>
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/
from suds.transport.https import HttpAuthenticated
from suds.client import Client
from datetime import timedelta,date,datetime,tzinfo
from requests.auth import HTTPBasicAuth
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)
#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"]
searchthis = client.service.getUpdatedDeviceDetails(query,startTime,endTime, "",count, offset)
Results
Suds ( https://fedorahosted.org/suds/) version: 0.6
Service ( SearchWebService) tns="http://search.nbapi.cgms.cisco.com/"
ns0 = "http://search.nbapi.cgms.cisco.com/"
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)
findEidsForIpAddressesByDeviceType
findEidsForIpAddressesByDeviceTypeResponse
findEidsForIpAddressesResponse
getDeletedDevicesResponse
getUpdatedDeviceDetailsResponse
updatedDeviceDetailQueryResult
(200, (updatedDeviceDetailQueryResult){
queryId = "60EF7F6ACFD8EE823AC2B8F83E545BC9"
queryStatus = "SUCCEEDED"
configGroup = "default-cgmesh"
firmwareGroup = "default-cgmesh"
key = "runningFirmwareImageId"
value = "2015-03-12 21:28:48.0"
key = "reloadFirmwareVersion"
key = "backupFirmwareVersion"
key = "slot4FirmwareImageId"
key = "runningFirmwareVersion"
key = "slot5FirmwareImageId"
key = "backupFirmwareImageId"
key = "downloadFirmwareVersion"
key = "slot6FirmwareImageId"
key = "downloadFirmwareImageId"
configGroup = "default-cgmesh"
firmwareGroup = "default-cgmesh"
key = "runningFirmwareImageId"
value = "2015-03-12 21:28:48.0"
key = "reloadFirmwareVersion"
key = "backupFirmwareVersion"
key = "slot4FirmwareImageId"
key = "runningFirmwareVersion"
key = "slot5FirmwareImageId"
key = "backupFirmwareImageId"
key = "downloadFirmwareVersion"
key = "slot6FirmwareImageId"
key = "downloadFirmwareImageId"
configGroup = "default-cgmesh"
firmwareGroup = "default-cgmesh"
address = "fe80:0:0:0:0:0:0:1"
address = "2010:dead:beef:cafe:0:8108:a8:bfe"
address = "fe80:0:0:0:207:8108:a8:bfe"
address = "0:0:0:0:0:0:0:1"
address = "0:0:0:0:0:0:0:1"
address = "2010:dead:beef:cafe:0:8108:a8:bfe"
address = "fe80:0:0:0:207:8108:a8:bfe"
value = "0007810800a80bfe"
address = "fe80:0:0:0:0:0:0:1"
value = "0007810800a80bfe"
key = "runningFirmwareImageId"
value = "2015-03-12 21:28:48.0"
key = "reloadFirmwareVersion"
value = "1970-01-01 00:00:00.0"
key = "backupFirmwareVersion"
key = "slot4FirmwareImageId"
value = "0007810800a80bfe"
key = "runningFirmwareVersion"
key = "slot5FirmwareImageId"
value = "0007810800A80BFE"
key = "backupFirmwareImageId"
value = "2015-02-24 18:59:52.0"
value = "2010:dead:beef:cafe:0:8108:a8:bfe"
key = "downloadFirmwareVersion"
key = "slot6FirmwareImageId"
value = "dp8zy77zbk7u02v6jxzgn"
key = "downloadFirmwareImageId"
key = "previousMeshPanid"
key = "nextHopAddressType"
value = "fe80:0:0:0:207:8108:bf:a053"
value = "0:0:0:0:0:0:0:0"
configGroup = "default-cgmesh"
firmwareGroup = "default-cgmesh"
address = "2010:dead:beef:cafe:0:8108:a8:d40"
address = "fe80:0:0:0:0:0:0:1"
address = "0:0:0:0:0:0:0:1"
address = "fe80:0:0:0:207:8108:a8:d40"
address = "0:0:0:0:0:0:0:1"
address = "2010:dead:beef:cafe:0:8108:a8:d40"
address = "fe80:0:0:0:207:8108:a8:d40"
value = "0007810800a80d40"
address = "fe80:0:0:0:0:0:0:1"
value = "0007810800a80d40"
key = "runningFirmwareImageId"
value = "2015-03-12 21:28:48.0"
key = "reloadFirmwareVersion"
value = "1970-01-01 00:00:00.0"
key = "backupFirmwareVersion"
key = "slot4FirmwareImageId"
value = "0007810800a80d40"
key = "runningFirmwareVersion"
key = "slot5FirmwareImageId"
value = "0007810800A80D40"
key = "backupFirmwareImageId"
value = "2015-02-23 23:27:00.0"
value = "2010:dead:beef:cafe:0:8108:a8:d40"
key = "downloadFirmwareVersion"
key = "slot6FirmwareImageId"
value = "dp8xr9333g58c96cp1ptr"
key = "downloadFirmwareImageId"
key = "previousMeshPanid"
key = "nextHopAddressType"
value = "fe80:0:0:0:207:8108:cc:e50b"
value = "0:0:0:0:0:0:0:0"
configGroup = "default-cgmesh"
firmwareGroup = "default-cgmesh"
address = "fe80:0:0:0:207:8108:bf:38e7"
address = "fe80:0:0:0:0:0:0:1"
address = "2011:dead:beef:cafe:0:8108:bf:38e7"
address = "0:0:0:0:0:0:0:1"
address = "0:0:0:0:0:0:0:1"
address = "fe80:0:0:0:207:8108:bf:38e7"
address = "2011:dead:beef:cafe:0:8108:bf:38e7"
value = "0007810800bf38e7"
address = "fe80:0:0:0:0:0:0:1"
value = "0007810800bf38e7"
key = "runningFirmwareImageId"
value = "2015-03-23 12:27:24.0"
key = "reloadFirmwareVersion"
key = "backupFirmwareVersion"
key = "slot4FirmwareImageId"
value = "0007810800bf38e7"
key = "runningFirmwareVersion"
key = "slot5FirmwareImageId"
value = "0007810800BF38E7"
key = "backupFirmwareImageId"
value = "2015-03-23 12:26:00.0"
value = "2011:dead:beef:cafe:0:8108:bf:38e7"
key = "downloadFirmwareVersion"
value = "sjklin-internal"
key = "slot6FirmwareImageId"
value = "host/smartmeter"
value = "dp3xguxs2fpne6gfgtjyw"
key = "downloadFirmwareImageId"
key = "previousMeshPanid"
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,
Parameters
Table 16 getMetricHistory Parameters
|
|
|
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 getMetricHistory Results.
Table 17 getMetricHistory Results
|
|
|
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/">
<query>deviceType:cgr1000</query>
<!--Zero or more repetitions:-->
<deviceIds>far_test3</deviceIds>
<startTime>null</startTime>
<!--Zero or more repetitions:-->
<rollupInterval>none</rollupInterval>
<rollupFunction>min</rollupFunction>
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
Table 18 findEidsForIpAddresses Parameters
|
|
|
ipAddresses |
list<string> |
The list of IP addresses with EIDs corresponding to devices to search for. Note: The list is limited to a maximum of 1000 IP addresses. An error returns if more than 1000 are specified. 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.
findEidsForIpAddresses Results describes the parameters in the response.
Table 19 findEidsForIpAddresses Results
|
|
|
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
Table 20 findEidsForIpAddressesByDeviceType Parameters
|
|
|
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. Note: The list is limited to a maximum of 1000 IP addresses. An error returns if more than 1000 are specified. 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.
findEidsForIpAddressesByDeviceType Results describes the parameters in the response.
Table 21 findEidsForIpAddressesByDeviceType Results
|
|
|
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. |