Cisco UCS Central XML API Methods
This chapter includes the following sections:
Authentication Methods
Authentication allows XML API interaction with . It provides a way to set permissions and control the operations that can be performed.
Note | Most code examples in this guide substitute the term <real_cookie> for an actual cookie (such as 1217377205/85f7ff49-e4ec-42fc-9437-da77a1a2c4bf). The Cisco UCS cookie is a 47-character string; it is not the type of cookie that web browsers store locally to maintain session information. |
Login
To log in, the XML API client establishes a TCP connection to the Cisco UCS Central HTTPS server and posts an XML document containing the aaaLogin method to the following URL: https://<UCSCENTRALIP>/xmlIM/
Next, the client specifies the aaaLogin method and provides a user name and password:
<aaaLogin inName="admin" inPassword="password" />
Note | Do not include XML version or DOCTYPE lines in the XML API document. The inName and inPassword attributes are parameters. |
Each XML API document represents an operation to be performed. When the request is received as an XML API document, Cisco UCS reads the request and performs the actions as provided in the method. Cisco UCS responds with a message in XML document format and indicates success or failure of the request.
The following is a typical successful response:
1 <aaaLogin 2 response="yes" 3 outCookie="<real_cookie>" 4 outRefreshPeriod="600" 5 outPriv="aaa,ext-lan-policy,ext-lan-qos,ext-san-policy,operations, pod-policy,pod-qos,read-only" 6 outDomains="mgmt02-dummy" 7 outChannel="noencssl" 8 outEvtChannel="noencssl"> 9 </aaaLogin>
Each line in the response should be interpreted as follows:
-
Specifies the method used to login.
-
Confirms that this is a response.
-
Provides the session cookie.
-
Specifies the recommended cookie refresh period. The default login session length is 600 seconds.
-
Specifies the privilege level assigned to the user account.
-
The outDomains value is mgmt02-dummy.
-
The outChannel value of noencssl declares that this session is not using encryption over SSL.
-
The outEvtChannel value of noencssl declares that any event subscriptions would not use encryption over SSL.
-
Closing tag.
Alternatively, you can use the cURL utility to log in to the XML API. You must use HTTPS in the cURL command, as shown in the following example:
curl -d "<aaaLogin inName='admin' inPassword='password'></aaaLogin>" https://192.0.20.72/xmlIM/
Refreshing the Session
Sessions are refreshed with the aaaRefresh method, using the 47-character cookie obtained either from the aaaLogin response or a previous refresh.
<aaaRefresh inName="admin" inPassword="mypasword" inCookie="real_cookie"/>
Logging Out of the Session
Use the following method to log out of a session:
<aaaLogout inCookie="<real_cookie>" />
Unsuccessful Responses
Failed login:
<aaaLogin response="yes" cookie="<real_cookie>" errorCode="551" invocationResult="unidentified-fail" errorDescr="Authentication failed"> </aaaLogin>
Nonexistent object (blank return indicates no object with the specified DN):
<configResolveDn dn="sys-machine/chassis-1/blade-4711“ cookie="<real_cookie>“ response="yes"> <outConfig> </outConfig> </configResolveDn>
Bad request:
<configConfMo dn="fabric/server“ cookie="<real_cookie>“ response="yes“ errorCode="103“ invocationResult="unidentified-fail“ errorDescr="can't create; object already exists."> </configConfMo>
Query Methods
Using configResolveChildren
When resolving children of objects in the MIT, note the following:
-
This method obtains all child objects of a named object that are instances of the named class. If a class name is omitted, all child objects of the named object are returned.
-
inDn attribute specifies the named object from which the child objects are retrieved (required).
-
classId attribute specifies the name of the child object class to return (optional).
-
Authentication cookie (from aaaLogin or aaaRefresh) is required.
-
inHierarchical attribute (default = false) if true, specifies that results are hierarchical.
-
Enumerated values, classIds, and bit masks are displayed as strings.
See the example request/response in configResolveChildren.
Using configResolveClass
When resolving a class, note the following:
-
All objects of the specified class type are retrieved.
-
classId specifies the object class name to return (required).
-
Authentication cookie (from aaaLogin or aaaRefresh) is required.
-
inHierarchical attribute (default = false) if true, specifies that results are hierarchical.
-
Enumerated values, classIds, and bit masks are displayed as strings.
Result sets can be large. Be precise when defining result sets. For example, to obtain only a list of servers, use computeItem as the attribute value for classId in the query. To get all instances of equipment, query the equipmentItem class. This example queries for all instances of the equipmentItem class:
<configResolveClass cookie="real_cookie" inHierarchical="false" classId="equipmentItem"/>
See the example request/response in configResolveClass.
Using configResolveClasses
When resolving multiple classes, note the following:
-
This method retrieves all the objects of the specified class types.
-
classId attribute specifies the name of the object class to return (required).
-
Authentication cookie (from aaaLogin or aaaRefresh) is required.
-
inHierarchical attribute (default = false) if true, specifies that results are hierarchical.
-
Enumerated values, classIds, and bit masks are displayed as strings.
If an invalid class name is specified in the inId attribute, an XML parsing error is generated and the query cannot execute.
See the example request/response in configResolveClasses.
Using configResolveDn
When resolving a DN, note the following:
-
The object specified by the DN is retrieved.
-
Specified DN identifies the object instance to be resolved (required).
-
Authentication cookie (from aaaLogin or aaaRefresh) is required.
-
inHierarchical attribute (default = false) if true, specifies that results are hierarchical.
-
Enumerated values, classIds, and bit masks are displayed as strings.
See the example request/response in configResolveDn.
Using configResolveDns
When resolving multiple DNs, note the following:
-
The objects specified by the DNs are retrieved.
-
Specified DN identifies the object instance to be resolved (required).
-
Authentication cookie (from aaaLogin or aaaRefresh) is required.
-
inHierarchical attribute (default = false) if true, specifies that results are hierarchical.
-
Enumerated values, classIds, and bit masks are displayed as strings.
-
Order of a request does not determine the order of the response.
-
Unknown DNs are returned as part of the outUnresolved element.
See the example request/response in configResolveDns.
Using configResolveParent
When resolving the parent object of an object, note the following:
-
This method retrieves the parent object of a specified DN.
-
dn attribute is the DN of the child object (required).
-
Authentication cookie (from aaaLogin or aaaRefresh) is required.
-
inHierarchical attribute (default = false) if true, specifies that results are hierarchical.
-
Enumerated values, classIds, and bit masks are displayed as strings.
See the example request/response in configResolveParent.
Using configScope
Limiting the scope of a query allows for a finer grained, less resource-intensive request. The query can be anchored at a point in the management information tree other than the root. When setting the query scope, note the following:
-
This method sets the root (scope) of the query to a specified DN and returns objects of the specified class type.
-
dn is the named object from which the query is scoped (required).
-
inClass attribute specifies the name of the object class to return (optional; when a class is not specified, the query acts the same as configResolveDn).
-
Authentication cookie (from aaaLogin or aaaRefresh) is required.
-
inHierarchical attribute (default = false) if true, specifies that results are hierarchical.
-
Enumerated values, classIds, and bit masks are displayed as strings.
The following example is a query for the Ethernet interfaces on the blades in chassis 1:
<configScope dn="sys/chassis-1" inClass="adaptorExtEthIf" cookie="<real_cookie>" inHierarchical="false"/>
Also see the example request/response in configScope.
Querying the Mac Pool
To obtain a list of all MAC addresses, query for macpoolAddr. These are children of the (system-created) macpoolUniverse. The request is as follows:
<configScope cookie="<real_cookie>" inHierarchical="false" dn="mac" inClass="macpoolAddr"/>
The response is as follows:
<?xml version="1.0" encoding="UTF-8"?> <configScope cookie="<real_cookie>" dn="mac" response="yes"> <outConfigs> <macpoolAddr assigned="no" assignedToDn="" dn="mac/00:00:00:00:FF:0F" id="00:00:00:00:FF:0F" owner="pool"> </macpoolAddr> <macpoolAddr assigned="no" assignedToDn="" dn="mac/00:00:00:00:FF:0E" id="00:00:00:00:FF:0E" owner="pool"> </macpoolAddr> . . . <\outconfig <\configScope
Because the objects of the macpoolAddr class can exist only as children of the MAC pool universe, a simpler query follows:
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="macpoolAddr"/>
To determine which computeItem (blade or rack mount server) is assigned a particular MAC address, specify the MAC address in the query and look at the assignedToDn field in the response. For example, a request with a specified MAC address follows:
<configResolveDn cookie="<real_cookie>" inHierarchical="false" dn="mac/10:00:00:00:00:03"/>
The response is as follows:
<configResolveDn dn="mac/10:00:00:00:00:03" cookie="real_cookie" response="yes"> <outConfig> <macpoolAddr assigned="yes" assignedToDn="org-root/ls-BOB/ether-eth1" dn="mac/10:00:00:00:00:03" id="10:00:00:00:00:03" owner="pool" /> </outConfig> </configResolveDn>
Querying Faults
The following example obtains a list of major faults:
<configResolveClass cookie="real_cookie" inHierarchical="false" classId="faultInst"/>
The following example (which contains the filter <inFilter>eq class= “faultInst”) obtains a list of all major or critical faults:
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="faultInst"> <inFilter> <eq class="faultInst" property="highestSeverity" value="major" /> </inFilter> </configResolveClass>
Using Filters
Simple Filters
Simple filters use true and false conditions of properties to select results.
False example:
<configResolveClass cookie="<real_cookie>" classId="topSystem" inHierarchical="false"> <inFilter> </inFilter> </configResolveClass>
True example:
<configResolveClass cookie="<real_cookie>" classId="topSystem" inHierarchical="true"> <inFilter> </inFilter> </configResolveClass>
Property Filters
Equality Filter
The example shows a query for all associated servers. The filter is framed as follows:
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="lsServer"> <inFilter> <eq class="lsServer" property="assocState" value="associated" /> </inFilter> </configResolveClass>
Not Equal Filter
The example finds all unassigned servers (assignment state property is not equal to assigned). The filter is framed as follows:
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="lsServer"> <inFilter> <ne class="lsServer" property="assignState" value="assigned" /> </inFilter> </configResolveClass>
Greater Than Filter
The example finds the memory arrays with more than 1024 MB capacity. The filter is framed as follows:
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="memoryArray"> <inFilter> <gt class="memoryArray" property="currCapacity" value="1024" /> </inFilter> </configResolveClass>
Greater Than or Equal to Filter
The example finds the memory arrays with 2048 MB capacity or more. The filter is framed as follows:
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="memoryArray"> <inFilter> <ge class="memoryArray" property="currCapacity" value="2048" /> </inFilter> </configResolveClass>
Less Than Filter
The example finds memory arrays with less than 1024 MB capacity. The filter is framed as follows:
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="memoryArray"> <inFilter> <lt class="memoryArray" property="currCapacity" value="1024" /> </inFilter> </configResolveClass>
Less Than or Equal to Filter
The example finds memory arrays with 2048 MB capacity or less. The filter is framed as follows:
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="memoryArray"> <inFilter> <le class="memoryArray" property="currCapacity" value="2048" /> </inFilter> </configResolveClass>
Wildcard Filter
The wildcard filter uses standard regular expression syntax. The example finds any adapter unit whose serial number begins with the prefix QCI1:
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="adaptorUnit"> <inFilter> <wcard class="adaptorUnit" property="serial" value="QCI1.*" /> </inFilter> </configResolveClass>
Any Bits Filter
This example finds all servers that have a connStatus of either A or B (the property connStatus is a bit mask). The filter is framed as follows:
<configResolveClass cookie="null" inHierarchical="false" classId="computeItem"> <inFilter> <anybit class="computeItem" property="connStatus" value="A,B" /> </inFilter> </configResolveClass>
All Bits Filter
The example finds all service profiles with the configQualifier bit mask set to both vnic-capacity and vhba-capacity. The filter is framed as follows:
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="lsServer"> <inFilter> <allbits class="lsServer" property="configQualifier" value="vnic-capacity,vhba-capacity" /> </inFilter> </configResolveClass>
Composite Filters
AND Filter
To determine all UUIDs assigned and owned by pools, run the following query. The filter is framed as follows:
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="uuidpoolAddr"> <inFilter> <and> <eq class="uuidpoolAddr" property="owner" value="pool" /> <eq class="uuidpoolAddr" property="assigned" value="yes" /> </and> </inFilter> </configResolveClass>
The response is as follows:
<configResolveClass classId="uuidpoolAddr" cookie="<real_cookie>" response="yes"> <outConfigs> <uuidpoolAddr assigned="yes" assignedToDn="org-root/ls-foo" dn="uuid/F000-00000000000F" id="F000-00000000000F" owner="pool"> </uuidpoolAddr> </outConfigs> </configResolveClass>
In the example, the AND filter finds the chassis with vendor Cisco Systems Inc and serial number CHS A04:
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="equipmentChassis"> <inFilter> <and> <eq property="vendor" value="Cisco Systems Inc" class="equipmentChassis"/> <eq class="equipmentChassis" property="serial" value="CHS A04"/> </and> </inFilter> </configResolveClass>
OR Filter
The example returns all objects of type computeItem that are located in slot one or slot eight from all chassis.
<configResolveClass inHierarchical="false" cookie="<real_cookie>" classId="compute"> <inFilter> <or> <eq class="computeItem" property="slotId" value="1"/> <eq class="computeItem" property="slotId" value="8"/> </or> </inFilter> </configResolveClass>
Between Filter
The example finds the memory arrays with slots 1, 2, 3, 4, or 5 populated (note that the between range is inclusive). The filter is framed as follows:
<configResolveClass cookie="<real_cookie>" inHierarchical="false" classId="memoryarray"> <inFilter> <bw class="memoryArray" property="populated" firstValue="1" secondValue="5"/> </inFilter> </configResolveClass>
AND, OR, NOT Composite Filter
The example is an AND, OR, NOT combination. It returns all objects of the computeItem type that are located in slot one or slot eight from all chassis, except chassis five.
<configResolveClass inHierarchical="false" cookie="<real_cookie>" classId="computeItem"> <inFilter> <and> <or> <eq class="computeItem" property="slotId" value="1"/> <eq class="computeItem" property="slotId" value="8"/> </or> <not> <eq class="computeItem" property="chassisId" value="5"/> </not> </and> </inFilter> </configResolveClass>
NOT Modifier Filter
The NOT filter can negate a contained filter. The filter is framed as follows. The example queries for servers that do not have a connStatus of unknown (the property connStatus is a bit mask).
<configResolveClass cookie="null" inHierarchical="false" classId="computeItem"> <inFilter> <not> <anybit class="computeItem" property="connStatus" value="unknown" /> </not> </inFilter> </configResolveClass>