cancel
Showing results for 
Search instead for 
Did you mean: 
cancel

UCS XML API Query Methods

1964
Views
0
Helpful
1
Comments
Advisor
This blog was generated from CDN blog

Created by: John McDonough on 14-07-2010 06:35:45 PM
When you first open the UCS Manager GUI application, you'll see a on the lower right in the Status Bar a progress indicator showing that data is being retrieved.  If you were to capture this traffic in WireShark or some other traffic sniffing applicaiton you would see multiple query requests being made from the UCS Manager back to the UCS itself. These queries are responsible for populating the information displayed in the manager interface.

Queries are also the heart of the Visore application that ships with UCS Manager.  For those unfamiliar with Visore it is a browser based UCS Object browser. To access Visore point you browser (works best in Firefox, and Chrome) to http://<ucs-ip-address>/visore.html, enter login information and authenticate.  If the provided credentials are valid the browser will be populated with the top-level UCS Objects.

Utilizing Visore is not the subject of this post, however I did want to point out a link on the Visore interface.  The link near the top of the page "Display XML of last query", when clicked will show the query that was used to populate the page.  This can be invaluable information when developing queries for use in you application.

On to the Queries, there are eight essential queries

- configFindDnsByClassId - Retrieve a list of distinguished names of a particular class type
- configResolveChildren - Query UCS object Children
- configResolveClass - Query UCS Oject by Class
- configResolveClasses - Query UCS Oject by Classes
- configResolveDn - Query UCS Object by distinguised name
- configResolveDns - Query UCS Objects by distinguised names
- configResolveParent - Query UCS Object Parent
- configScope - Achor the Object Query to a specific point in the object tree

Queries are useful in so many ways, monitoring, managemnt, inventory reporting, statistics gathering, gathering input for configuartion calls, etc...

Let's start with the basic queries configResolveClass and configResolveDn.

Objects in UCS have a dn or Distinguoshed name, this name is an unambiguous reference to the object.  Objects are also of a specific class type. Objects can have only one dn that refencees them and can only have one class type.

When you query with the confgResolveDn method only a single object is returned and perhaps it's children objects if the attribute inHierarchical for the query is set to "true".  When you query with the configResolveClass method multiple objects can be returned based on the class and the UCS configuration, chidlren objects of those objects could also be returned based inHierarchical attribute.

configResolveDn query to get information about Chassis-1
<configResolveDn cookie="1276271945/81b81df3-e2d9-42ea-80ac-6a2e535f232e" inHierarchical="false" dn="sys/chassis-1"/>

The response
<configResolveDn dn="sys/chassis-1" cookie="1276271945/81b81df3-e2d9-42ea-80ac-6a2e535f232e" response="yes">
<outConfig>
<equipmentChassis adminState="acknowledged" configState="ok" connPath="A,B" connStatus="A,B" dn="sys/chassis-1"   fabricEpDn="fabric/server/chassis-1" fltAggr="1" fsmDescr="" fsmPrev="nop" fsmProgr="100" fsmRmtInvErrCode="none"   fsmRmtInvErrDescr="" fsmRmtInvRslt="" fsmStageDescr="" fsmStamp="never" fsmStatus="nop" fsmTry="0" id="1" lcTs="1970-01-01T00:00:00.000" licState="license-ok" managingInst="B" model="N20-C6508" operQualifier="psu-power"   operState="power-problem" operability="operable" power="ok" presence="unknown" revision="0" serial="FOX1327G4VY"   thermal="ok" vendor="Cisco Systems Inc" versionHolder="yes"/>
</outConfig>
</configResolveDn>

The response has one object of equipmentChassis class

configResolveClass query to get information about the class equipmentChassis, this is the class that Chassis belong to
<configResolveClass cookie="1276271945/81b81df3-e2d9-42ea-80ac-6a2e535f232e" inHierarchical="false" classId="equipmentChassis"/>

<configResolveClass cookie="1276271945/81b81df3-e2d9-42ea-80ac-6a2e535f232e" response="yes" classId="equipmentChassis">
<outConfigs>
<equipmentChassis adminState="acknowledged" configState="ok" connPath="A,B" connStatus="A,B" dn="sys/chassis-1"   fabricEpDn="fabric/server/chassis-1" fltAggr="1" fsmDescr="" fsmPrev="nop" fsmProgr="100" fsmRmtInvErrCode="none"   fsmRmtInvErrDescr="" fsmRmtInvRslt="" fsmStageDescr="" fsmStamp="never" fsmStatus="nop" fsmTry="0" id="1" lcTs="1970-01-01T00:00:00.000" licState="license-ok" managingInst="B" model="N20-C6508" operQualifier="psu-power"  operState="power-problem" operability="operable" power="ok" presence="unknown" revision="0" serial="FOX1327G4VY"   thermal="ok" vendor="Cisco Systems Inc"
versionHolder="yes"/>
<equipmentChassis adminState="acknowledged" configState="ok" connPath="A,B" connStatus="A,B" dn="sys/chassis-2"   fabricEpDn="fabric/server/chassis-2" fltAggr="562997198061569" fsmDescr="" fsmPrev="nop" fsmProgr="100"   fsmRmtInvErrCode="none" fsmRmtInvErrDescr="" fsmRmtInvRslt="" fsmStageDescr="" fsmStamp="never" fsmStatus="nop"   fsmTry="0" id="2" lcTs="1970-01-01T00:00:00.000" licState="license-ok" managingInst="B" model="N20-C6508"  operQualifier="fan-thermal" operState="thermal-problem" operability="operable" power="ok" presence="unknown"   revision="0" serial="FOX1325G5FE" thermal="ok" vendor="Cisco Systems Inc" versionHolder="yes"/>
<equipmentChassis adminState="acknowledged" configState="ok" connPath="A,B" connStatus="A,B" dn="sys/chassis-3"   fabricEpDn="fabric/server/chassis-3" fltAggr="21474836482" fsmDescr="" fsmPrev="nop" fsmProgr="100"   fsmRmtInvErrCode="none" fsmRmtInvErrDescr="" fsmRmtInvRslt="" fsmStageDescr="" fsmStamp="never" fsmStatus="nop"   fsmTry="0" id="3" lcTs="1970-01-01T00:00:00.000" licState="license-ok" managingInst="B" model="N20-C6508"  operQualifier="chassis-power" operState="power-problem" operability="operable" power="redundancy-failed"   presence="unknown" revision="0" serial="FOX1326GC3F" thermal="ok" vendor="Cisco Systems Inc" versionHolder="yes"/>
</outConfigs>
</configResolveClass>

The response for this UCS has multiple objects of class equipmentChassis because there are multiple chassis.

Let's look at a single Service Profile with inHierarchical set to true, the dn is org-root/org-jomcdono/ls-esx4-01-node-01
<configResolveDn cookie="1276271945/81b81df3-e2d9-42ea-80ac-6a2e535f232e" inHierarchical="true" dn="org-root/org-jomcdono/ls-esx4-01-node-01"/>

The response shows an lsServer object for the queried dn, the lsServer object has multiple chidlren objects, which themseleves have children objects, For example the vnicEther object which define one of the enthernet interfaces has vnicEtherIf children which define the VLANs that are associated with the interface.
<configResolveDn dn="org-root/org-jomcdono/ls-esx4-01-node-01" cookie="1276271945/81b81df3-e2d9-42ea-80ac-6a2e535f232e" response="yes">
<outConfig>
<lsServer agentPolicyName="" assignState="assigned" assocState="associated" biosProfileName="" bootPolicyName="esx4-01" childAction="deleteNonPresent" configQualifier="" configState="applied" descr="" dn="org-root/org-jomcdono/ls-esx4-01-node-01" dynamicConPolicyName="" fltAggr="0" hostFwPolicyName="" identPoolName="" intId="749493" localDiskPolicyName="default" mgmtAccessPolicyName="" mgmtFwPolicyName="" name="esx4-01-node-01" operState="ok" owner="management" pnDn="sys/chassis-3/blade-5" scrubPolicyName="" solPolicyName="default" srcTemplName="esx4-01-node" statsPolicyName="default" type="instance" uuid="derived" uuidSuffix="0000-000000000000" vconProfileName="">
<vnicEther adaptorProfileName="" addr="derived" adminVcon="any" bootDev="disabled" hildAction="deleteNonPresent" configState="applied" equipmentDn="sys/chassis-3/blade-5/adaptor-1/host-eth-2" fltAggr="0" identPoolName="" instType="manual" mtu="1500" name="vnicB" nwCtrlPolicyName="" nwTemplName="" operOrder="2" operSpeed="line-rate" operVcon="1" order="2" owner="logical" pinToGroupName="" qosPolicyName="" rn="ether-vnicB" statsPolicyName="default" switchId="B" type="ether">
<vnicEtherIf addr="derived" childAction="deleteNonPresent" defaultNet="no" name="jomcdono-n1kv-ctrl" operState="indeterminate" owner="logical" rn="if-jomcdono-n1kv-ctrl" switchId="B" type="ether" vnet="14"/>
<vnicEtherIf addr="derived" childAction="deleteNonPresent" defaultNet="no" name="jomcdono-n1kv-pkt" operState="indeterminate" owner="logical" rn="if-jomcdono-n1kv-pkt" switchId="B" type="ether" vnet="15"/>
<vnicEtherIf addr="derived" childAction="deleteNonPresent" defaultNet="no" name="jomcdono-vmotion" operState="indeterminate" owner="logical" rn="if-jomcdono-vmotion" switchId="B" type="ether" vnet="16"/>
<vnicEtherIf addr="derived" childAction="deleteNonPresent" defaultNet="yes" name="default" operState="indeterminate" owner="logical" rn="if-default" switchId="B" type="ether" vnet="1"/>
<vnicEtherIf addr="derived" childAction="deleteNonPresent" defaultNet="no" name="vlan3" operState="indeterminate" owner="logical" rn="if-vlan3" switchId="B" type="ether" vnet="3"/>
</vnicEther>
<vnicEther adaptorProfileName="" addr="derived" adminVcon="any" bootDev="disabled" childAction="deleteNonPresent" configState="applied" equipmentDn="sys/chassis-3/blade-5/adaptor-1/host-eth-1" fltAggr="0" identPoolName="" instType="manual" mtu="1500" name="vnicA" nwCtrlPolicyName="" nwTemplName="" operOrder="1" operSpeed="line-rate" operVcon="1" order="1" owner="logical" pinToGroupName="" qosPolicyName="" rn="ether-vnicA" statsPolicyName="default" switchId="A" type="ether">
<vnicEtherIf addr="derived" childAction="deleteNonPresent" defaultNet="no" name="jomcdono-n1kv-ctrl" operState="indeterminate" owner="logical" rn="if-jomcdono-n1kv-ctrl" switchId="A" type="ether" vnet="14"/>
<vnicEtherIf addr="derived" childAction="deleteNonPresent" defaultNet="no" name="jomcdono-n1kv-pkt" operState="indeterminate" owner="logical" rn="if-jomcdono-n1kv-pkt" switchId="A" type="ether" vnet="15"/>
<vnicEtherIf addr="derived" childAction="deleteNonPresent" defaultNet="no" name="jomcdono-vmotion" operState="indeterminate" owner="logical" rn="if-jomcdono-vmotion" switchId="A" type="ether" vnet="16"/>
<vnicEtherIf addr="derived" childAction="deleteNonPresent" defaultNet="yes" name="default" operState="indeterminate" owner="logical" rn="if-default" switchId="A" type="ether" vnet="1"/>
<vnicEtherIf addr="derived" childAction="deleteNonPresent" defaultNet="no" name="vlan3" operState="indeterminate" owner="logical" rn="if-vlan3" switchId="A" type="ether" vnet="3"/>
</vnicEther>
<vnicFc adaptorProfileName="" addr="derived" adminVcon="any" bootDev="disabled" childAction="deleteNonPresent" configState="applied" equipmentDn="sys/chassis-3/blade-5/adaptor-1/host-fc-2" fltAggr="0" identPoolName="" instType="manual" maxDataFieldSize="2048" name="vhbaB" nodeAddr="00:00:00:00:00:00:00:00" nwTemplName="esx4-01-vhba-b" operOrder="4" operSpeed="line-rate" operVcon="1" order="4" owner="logical" persBind="disabled" persBindClear="no" pinToGroupName="" qosPolicyName="" rn="fc-vhbaB" statsPolicyName="default" switchId="B" type="fc">
<vnicFcIf childAction="deleteNonPresent" initiator="00:00:00:00:00:00:00:00" name="vsan200" operState="indeterminate" owner="logical" rn="if-default" switchId="B" type="fc" vnet="200"/>
</vnicFc>
<vnicFc adaptorProfileName="" addr="derived" adminVcon="any" bootDev="disabled" childAction="deleteNonPresent" configState="applied" equipmentDn="sys/chassis-3/blade-5/adaptor-1/host-fc-1" fltAggr="0" identPoolName="" instType="manual" maxDataFieldSize="2048" name="vhbaA" nodeAddr="00:00:00:00:00:00:00:00" nwTemplName="esx4-01-vhba-a" operOrder="3" operSpeed="line-rate" operVcon="1" order="3" owner="logical"
persBind="disabled" persBindClear="no" pinToGroupName="" qosPolicyName="" rn="fc-vhbaA" statsPolicyName="default" switchId="A" type="fc">
<vnicFcIf childAction="deleteNonPresent" initiator="00:00:00:00:00:00:00:00" name="vsan100" operState="indeterminate" owner="logical" rn="if-default" switchId="A" type="fc" vnet="100"/>
</vnicFc>
<vnicFcNode addr="pool-derived" childAction="deleteNonPresent" fltAggr="0" identPoolName="node-default" rn="fc-node"/>
<lsRequirement childAction="deleteNonPresent" computeEpDn="" name="jomcdono" pnPoolDn="org-root/org-jomcdono/compute-pool-jomcdono" qualifier="" rn="pn-req"/>
<lsPower childAction="deleteNonPresent" rn="power" state="up"/>
</lsServer>
</outConfig>
</configResolveDn>

Had I queried for the Class lsServer I would have gotten all the Service Profiles on the system, associated with blades or not and service profile templates. Had I only wanted associated blades that are actual Service Profiles not templates then I would have used a filter in my query. Query filters will be the subject of a later post.

What is I want multiple classes or more than one dn, there are queries for that as well...
configResolveClasses and configResolveDns

In these queries a list of dns or classes is passed as part of the query
configResolveDns
<configResolveDns cookie="1276279335/68222b90-d124-4e61-987d-21d2faccb43c" inHierarchical="false">
<inDns>
<dn value="org-root/org-jomcdono/ls-esx4-01-node-01"/>
<dn value="org-root/org-jomcdono/ls-esx4-01-node-02"/>
<dn value="sys/Chassis-1"/>
</inDns>
</configResolveDns>

configResolveClasses
<configResolveClasses cookie="1276279335/68222b90-d124-4e61-987d-21d2faccb43c" inHierarchical="false">
<inIds>
<id value="equipmentChassis"/>
<id value="lsServer"/>
</inIds>
</configResolveClasses>

The output from these queries would be similar in that they would both contain lsServer and equipmentchassis objects.  The classes query would most likely contain more objects unless the UCS being queried only had one chassis and two service profiles defined.

configResolveParent and configResolveChildren are pretty straight forward and act much as you would expect them to, although there is an option that can be employeed with configResolveChildren that allows for the retrieval of all the children objects or just the children objects of a specific class.

configResolveParent, allows for the retrieval of the parent of an object based on the provided dn.
<configResolveParent cookie="1278509820/594928ca-9672-40a3-a9e7-ddd14b77bc89" inHierarchical="false" dn="sys/switch-B/psu-2/fault-F0378"/>

Ouput from the configResolveParent query
<configResolveParent dn="sys/switch-B/psu-2/fault-F0378" cookie="1278509820/594928ca-9672-40a3-a9e7-ddd14b77bc89" response="yes">
<outConfig>
<equipmentPsu dn="sys/switch-B/psu-2" fltAggr="1" id="2" model="" operState="removed" operability="inoperable" perf="unknown" power="offduty" presence="missing" revision="0" serial="" thermal="unknown" vendor="" voltage="unknown"/>
</outConfig>
</configResolveParent>

configResolveParent could be replaced with configResloveDn since we know the dn of the child object the application issuing the query could easily remove

the last object from the dn that we have and issue a configResolveDn.

configResolveChildren allows for the retrieval of all the children objects of a dn or all the children objects of a dn of a specific class.  For example if we only wnated to find the external Ethernet interface (adaptorExtEthIf) child objects of a blade adaptor (adaptorUnit) the following query could be used
<configResolveChildren cookie="1279126960/fe35a472-618c-491b-b0c4-44efce2b8607" inHierarchical="false" inDn="sys/chassis-1/blade-1/adaptor-1" classId="adaptorExtEthIf" />

Output from the configResolveChildren query
<configResolveChildren cookie="1279126960/fe35a472-618c-491b-b0c4-44efce2b8607" response="yes" classId="adaptorExtEthIf">
<outConfigs>
  <adaptorExtEthIf adapterId="1" adminState="enabled" chassisId="N/A"  dn="sys/chassis-1/blade-1/adaptor-1/ext-eth-2" epDn="" fsmDescr="" fsmPrev="nop" fsmProgr="100" fsmRmtInvErrCode="none" fsmRmtInvErrDescr="" fsmRmtInvRslt="" fsmStageDescr="" fsmStamp="never" fsmStatus="nop" fsmTry="0" id="2" ifRole="unknown" ifType="physical" linkState="up" locale="" mac="00:26:51:0B:70:F9" name="" operState="admin-down" operStateDesc="" peerDn="sys/chassis-1/slot-2/host/port-1" peerPortId="1" peerSlotId="2" physEpDn="" portId="2" purpose="general"  side="right" slotId="1"  switchId="B" transport="" type=""/>
   <adaptorExtEthIf adapterId="1" adminState="enabled" chassisId="N/A"  dn="sys/chassis-1/blade-1/adaptor-1/ext-eth-1" epDn="" fsmDescr="" fsmPrev="nop" fsmProgr="100" fsmRmtInvErrCode="none" fsmRmtInvErrDescr="" fsmRmtInvRslt="" fsmStageDescr="" fsmStamp="never" fsmStatus="nop" fsmTry="0" id="1" ifRole="unknown" ifType="physical" linkState="up" locale="" mac="00:26:51:0B:70:F8" name="" operState="admin-down" operStateDesc="" peerDn="sys/chassis-1/slot-1/host/port-1" peerPortId="1" peerSlotId="1" physEpDn="" portId="1" purpose="general"  side="left" slotId="1"  switchId="A" transport="" type=""/> 
</outConfigs>
</configResolveChildren>

The query that gets all the children objects of adaptorUnit is very similar to the one above except that it does not have the classId attribute specified in the query as shown below.
<configResolveChildren cookie="1279126960/fe35a472-618c-491b-b0c4-44efce2b8607" inHierarchical="false" inDn="sys/chassis-1/blade-1/adaptor-1" />

The query would return all the children objects of the specified dn.

configFindDnsByClassId returns a list of dns of a specified class type, some uses would be to get all the dns of the chassis (equipmentChassis) or blades (computeBlades) or service profiles (lsServer) or perhaps all the dns for objects that represent fan speed statistics (equipmentFanStats)Chassis (running against a single chassis UCS)

<configFindDnsByClassId cookie="1279126960/fe35a472-618c-491b-b0c4-44efce2b8607" classId="equipmentChassis" />

Response
<configFindDnsByClassId cookie="1279126960/fe35a472-618c-491b-b0c4-44efce2b8607" response="yes" classId="equipmentChassis">
<outDns>
  <dn value="sys/chassis-1"/>
</outDns>
</configFindDnsByClassId>

Blades
<configFindDnsByClassId cookie="1279126960/fe35a472-618c-491b-b0c4-44efce2b8607" classId="computeBlade" />

Response
<configFindDnsByClassId cookie="1279126960/fe35a472-618c-491b-b0c4-44efce2b8607" response="yes" classId="computeBlade">
<outDns>
  <dn value="sys/chassis-1/blade-7"/>
  <dn value="sys/chassis-1/blade-6"/>
  <dn value="sys/chassis-1/blade-5"/>
  <dn value="sys/chassis-1/blade-4"/>
  <dn value="sys/chassis-1/blade-3"/>
  <dn value="sys/chassis-1/blade-2"/>
  <dn value="sys/chassis-1/blade-1"/>
  </outDns>
</configFindDnsByClassId>

Fan Speed Statistics
<configFindDnsByClassId cookie="1279126960/fe35a472-618c-491b-b0c4-44efce2b8607" classId="equipmentFanStats" />

Response
<configFindDnsByClassId cookie="1279126960/fe35a472-618c-491b-b0c4-44efce2b8607" response="yes" classId="equipmentFanStats">
<outDns>
  <dn value="sys/chassis-1/fan-module-1-5/fan-2/stats"/>
  <dn value="sys/chassis-1/fan-module-1-6/fan-1/stats"/>
  <dn value="sys/chassis-1/fan-module-1-4/fan-2/stats"/>
  <dn value="sys/chassis-1/fan-module-1-7/fan-1/stats"/>
  <dn value="sys/chassis-1/fan-module-1-7/fan-2/stats"/>
  <dn value="sys/chassis-1/fan-module-1-4/fan-1/stats"/>
  <dn value="sys/chassis-1/fan-module-1-6/fan-2/stats"/>
  <dn value="sys/chassis-1/fan-module-1-5/fan-1/stats"/>
  <dn value="sys/chassis-1/fan-module-1-1/fan-2/stats"/>
  <dn value="sys/chassis-1/fan-module-1-2/fan-1/stats"/>
  <dn value="sys/chassis-1/fan-module-1-3/fan-1/stats"/>
  <dn value="sys/chassis-1/fan-module-1-3/fan-2/stats"/>
  <dn value="sys/chassis-1/fan-module-1-2/fan-2/stats"/>
  <dn value="sys/chassis-1/fan-module-1-1/fan-1/stats"/>
  <dn value="sys/chassis-1/fan-module-1-8/fan-2/stats"/>
  <dn value="sys/chassis-1/fan-module-1-8/fan-1/stats"/>
</outDns>
</configFindDnsByClassId>

Notice two things about the query, in the query the inHierarchical attribute is not used and in the response there is no specific order in which the dns are returned.

configScope allows for the rooting of a query at a specific point in the tree, the root is specified by a dn and a class is specified as the object type  to return.  For example suppose you only wanted to retrieve the fan speed statistics for fan module 8 in chassis 1, sys/chassis-1/fan-module-1-8 the configScope query would look like this
<configScope cookie="1279126960/fe35a472-618c-491b-b0c4-44efce2b8607" dn="sys/chassis-1/fan-module-1-8" inClass="equipmentFanStats" />

Response
<configScope dn="sys/chassis-1/fan-module-1-8" cookie="1279126960/fe35a472-618c-491b-b0c4-44efce2b8607" response="yes">
<outConfigs>
  <equipmentFanStats  dn="sys/chassis-1/fan-module-1-8/fan-2/stats" intervals="58982460"  speed="3760" speedAvg="3760" speedMax="3760" speedMin="3760"  suspect="no" thresholded="" timeCollected="2010-07-14T10:54:41.705" update="131074"/>
  <equipmentFanStats  dn="sys/chassis-1/fan-module-1-8/fan-1/stats" intervals="58982460"  speed="3560" speedAvg="3560" speedMax="3560" speedMin="3560"  suspect="no" thresholded="" timeCollected="2010-07-14T10:54:41.705" update="131074"/>
</outConfigs>
</configScope>

How is configScope different from configResolveChildren? Notice that the configScope query specifies the root dn as sys/chassis-1/fan-module-1-8 for a configResolveChildren the stats object is a child of the fan-1 or fan-2 object under the fan-module object.  In order to get both stats objects for the fan-module two configResolveChildren queries would need to be run to get the fan speed stats objects. One query for sys/cahssis-1/fan-module-1-8/fan-1 and one for sys/cahssis-1/fan-module-1-8/fan-2

Next time I'll discuss filters and regular expressions.

John McDonough
Cisco Advanced Services
UCS Compute and Virtualization Practice
1 Comment
Beginner

Hi,

Is there any way to find out or see what XML data was sent across when an operation was performed.

Ex: Say when a "Service Profile" was dissociated from its current association.

The reason for asking this is I want to write my own code to do this, instead on doing it through UCS Manager. I don't seem to find a way to generate correct XML (What all MO properties should be modified etc...) to do this operation or many other such operations that I want to perform.

And since I am using UCSPE (2.1) I can't do a data capture. I have used the UCS Visore, but it is not of much help.

Could you please suggest an easy way to do it using the Simulator or any other way.

Rgds,

Kshitij

CreatePlease to create content
Content for Community-Ad
FusionCharts will render here