Cisco DCNM Web Services API Guide, Release 4.0
Overview
Downloads: This chapterpdf (PDF - 123.0KB) The complete bookPDF (PDF - 6.48MB) | Feedback

Overview

Table Of Contents

Overview

Information About Web Services

SOAP Messages

SOAP Message to Get Session ID

SOAP Message to Make API Call

Error Handling

Licensing Requirements for Web Services

Additional References

Related Documents

Standards


Overview


This chapter describes the Data Center Network Management (DCNM) web services application program interface (API).

This chapter includes the following sections:

Information About Web Services

Licensing Requirements for Web Services

Additional References

Information About Web Services

You can configure NX-OS devices by using the Cisco DCNM web services API on the DCNM server. You create XML-based API requests by using the SOAP protocol. The DCNM server configures devices using the XML management interface. For more information about the XML management interface, see the Cisco Nexus 7000 Series NX-OS XML Management Interface User Guide, Release 4.0.

The web services API provides a subset of the features available in the DCNM client. For information about DCNM, see the Cisco DCNM Fundamentals Configuration Guide, Release 4.0.

This section includes the following topics:

SOAP Messages

Error Handling

SOAP Messages

The SOAP messages that you exchange with the DCNM server contain a session ID in the header and an API call in the body. You make an initial SOAP request to obtain the session ID.

You can obtain the XSD and WSDL files that describe the DCNM web services on the DCNM server in the ws-client folder of the DCNM installation directory. By default, the DCNM server is installed at C:\Program Files\Cisco Systems\DCNM.

For more information about SOAP, see http://www.w3.org/TR/soap.

This section includes the following topics:

SOAP Message to Get Session ID

SOAP Message to Make API Call

SOAP Message to Get Session ID

Example 1-1 shows the initial SOAP message that you send to obtain a session ID with the getSessionId method in the SecurityApp service. All subsequent SOAP messages use the returned session ID. You use the getSessionId method in the Security AppService and specify the user ID and password of the DCNM server.

Example 1-1 SOAP Message to Obtain Session ID

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
 <env:Header>
 <util:credentialHeader xmlns:util="http://util.common.dcm.dcbu.cisco.com"
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
           xsi:schemaLocation="http://util.common.dcm.dcbu.cisco.com util.xsd">
  <userId>administration</userId>
  <password>administration</password>
 </util:credentialHeader>
 </env:Header>
 <env:Body>
 <m:getSessionId xmlns:m="http://security.app.ws.dcm.dcbu.cisco.com/SecurityAppService">
  <opContext_0/>
 </m:getSessionId>
 </env:Body>
</env:Envelope>

Example 1-2 shows the returned session ID "FFEE034DDFAFASEREW8383FDSFSD" that you use in subsequent API calls.

Example 1-2 Response to SOAP Message to Obtain Session ID

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
 <env:Header/>
 <env:Body>
 <m:getSessionIdResponse 
xmlns:m="http://security.app.ws.dcm.dcbu.cisco.com/SecurityAppService">
  <return xmlns:basictypes="http://basictypes.dcm.dcbu.cisco.com" 
xmlns:common="http://common.dcm.dcbu.cisco.com" 
xmlns:datatype="http://datatype.model.dcm.dcbu.cisco.com" 
xmlns:enumkind="http://enumkind.model.dcm.dcbu.cisco.com" 
xmlns:util="http://util.common.dcm.dcbu.cisco.com" 
xmlns:xs="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://www.w3.org/2001/XMLSchema xml.xsd" 
xsi:type="xs:string">FFEE034DDFAFASEREW8383FDSFSD</return>
 </m:getSessionIdResponse>
 </env:Body>
</env:Envelope>

SOAP Message to Make API Call

Example 1-3 shows the SOAP message that you send to request the chassis inventory with method getAllChassisInNetwork in the InventoryApp service. You use the session ID from Example 1-2.

Example 1-3 SOAP Message to Request Chassis Inventory

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
 <env:Header>
 <util:credentialHeader xmlns:util="http://util.common.dcm.dcbu.cisco.com"
        xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
           xsi:schemaLocation="http://util.common.dcm.dcbu.cisco.com util.xsd">
  <sessionId>FFEE034DDFAFASEREW8383FDSFSD</sessionId>
 </util:credentialHeader>
 </env:Header>
 <env:Body>
 <m:getAllChassisInNetwork 
xmlns:m="http://inventory.app.ws.dcm.dcbu.cisco.com/InventoryAppService">
  <opContext_0/>
 </m:getAllChassisInNetwork>
 </env:Body>
</env:Envelope>

Example 1-4 shows the response to the request for chassis inventory.

Example 1-4 Response to SOAP Message to Request Chassis Inventory

<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
 <env:Header/>
 <env:Body>
 <m:getAllChassisInNetworkResponse 
xmlns:m="http://inventory.app.ws.dcm.dcbu.cisco.com/InventoryAppService">
  <return collectionType="List" xmlns:basictypes="http://basictypes.dcm.dcbu.cisco.com" 
xmlns:common="http://common.dcm.dcbu.cisco.com" 
xmlns:datatype="http://datatype.model.dcm.dcbu.cisco.com" 
xmlns:enumkind="http://enumkind.model.dcm.dcbu.cisco.com" 
xmlns:physical="http://physical.model.dcm.dcbu.cisco.com" 
xmlns:tns="http://physical.model.dcm.dcbu.cisco.com" 
xmlns:util="http://util.common.dcm.dcbu.cisco.com" 
xmlns:vdc="http://vdc.model.dcm.dcbu.cisco.com" 
xmlns:xs="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://physical.model.dcm.dcbu.cisco.com physical.xsd" 
xsi:type="physical:Chassis_ListType">
  <itemList xsi:type="physical:Chassis">
   <instClassName>com.cisco.dcbu.dcm.model.physical.Chassis</instClassName>
   <instanceClassId>6143</instanceClassId>
   
<instanceName>com.cisco.dcbu.dcm.model.physical.Chassis:neId=2,chassisId=TBM11256510</inst
anceName>
   <instanceState>Unmodified</instanceState>
   <version>3</version>
   <description>Nexus7000 C7010 (10 Slot) Chassis</description>
   <name>Chassis</name>
   <productId>N7K-C7010</productId>
   <serialNumber>TBM11256510</serialNumber>
   <chassisPowerSupplyRef xsi:type="physical:ChassisPowerSupplySetting">
   
<instClassName>com.cisco.dcbu.dcm.model.physical.ChassisPowerSupplySetting</instClassName>
   <powerSupplyRedundancyMode>Redundant</powerSupplyRedundancyMode>
   </chassisPowerSupplyRef>
   <chassisPowerSupplyStatusRef xsi:type="physical:ChassisPowerSupplyStatus">
   
<instClassName>com.cisco.dcbu.dcm.model.physical.ChassisPowerSupplyStatus</instClassName>
   <instanceClassId>6252</instanceClassId>
   
<instanceName>com.cisco.dcbu.dcm.model.physical.ChassisPowerSupplyStatus:neId=2,chassisId=
TBM11256510</instanceName>
   <instanceState>Unmodified</instanceState>
   <version>0</version>
   <availablePowerSupply>2329.00</availablePowerSupply>
   <operationalRedundancyStatus>Redundant</operationalRedundancyStatus>
   <totalPowerSupply>5480.00</totalPowerSupply>
   <usedPowerSupply>3151.0</usedPowerSupply>
   </chassisPowerSupplyStatusRef>
   <networkElementRef xsi:type="vdc:NetworkElement">
   <instClassName>com.cisco.dcbu.dcm.model.vdc.NetworkElement</instClassName>
   <instanceClassId>2</instanceClassId>
   <instanceName>com.cisco.dcbu.dcm.model.vdc.NetworkElement:neId=2</instanceName>
   <instanceState>Unmodified</instanceState>
   <version>6</version>
   <abstractNetworkElementStatusRef xsi:type="vdc:AbstractNetworkElementStatus">
    
<instClassName>com.cisco.dcbu.dcm.model.vdc.AbstractNetworkElementStatus</instClassName>
    <instanceClassId>6146</instanceClassId>
    
<instanceName>com.cisco.dcbu.dcm.model.vdc.AbstractNetworkElementStatus:neId=2</instanceNa
me>
    <instanceState>Unmodified</instanceState>
    <version>1</version>
    <mgmtState>Managed</mgmtState>
    <userId>administration</userId>
   </abstractNetworkElementStatusRef>
   <hostName>DCNM-9</hostName>
   <mgmtIpAddress>172.27.139.76</mgmtIpAddress>
   <platformName>Nexus7000</platformName>
   <platformType>Cisco Nexus7000 Series</platformType>
   <platformVersion>4.0(1)</platformVersion>
   <chassisRef xsi:type="physical:Chassis">
    
<instanceName>com.cisco.dcbu.dcm.model.physical.Chassis:neId=2,chassisId=TBM11256510</inst
anceName>
   </chassisRef>
   </networkElementRef>
   <redundancySettingsRef xsi:type="physical:RedundancySetting">
   <instClassName>com.cisco.dcbu.dcm.model.physical.RedundancySetting</instClassName>
   <redundancyMode>HA</redundancyMode>
   </redundancySettingsRef>
   <redundancyStatusRef xsi:type="physical:RedundancyStatus">
   <instClassName>com.cisco.dcbu.dcm.model.physical.RedundancyStatus</instClassName>
   <instanceClassId>6250</instanceClassId>
   
<instanceName>com.cisco.dcbu.dcm.model.physical.RedundancyStatus:neId=2,chassisId=TBM11256
510</instanceName>
   <instanceState>Unmodified</instanceState>
   <version>0</version>
   <operationalRedundancyMode>None</operationalRedundancyMode>
   </redundancyStatusRef>
   <slotCol collectionType="Set" xsi:type="physical:Slot_SetType">
   <itemSet xsi:type="physical:Slot">
    <instClassName>com.cisco.dcbu.dcm.model.physical.Slot</instClassName>
    <instanceClassId>6150</instanceClassId>
    
<instanceName>com.cisco.dcbu.dcm.model.physical.Slot:neId=2,chassisId=TBM11256510,slotNumb
er=3</instanceName>
    <instanceState>Unmodified</instanceState>
    <version>1</version>
    <chassisRef xsi:type="physical:Chassis">
    
<instanceName>com.cisco.dcbu.dcm.model.physical.Chassis:neId=2,chassisId=TBM11256510</inst
anceName>
    </chassisRef>
    <slotNumber>3</slotNumber>
   </itemSet>
   <itemSet xsi:type="physical:Slot">
    <instClassName>com.cisco.dcbu.dcm.model.physical.Slot</instClassName>
    <instanceClassId>6148</instanceClassId>
    
<instanceName>com.cisco.dcbu.dcm.model.physical.Slot:neId=2,chassisId=TBM11256510,slotNumb
er=1</instanceName>
    <instanceState>Unmodified</instanceState>
    <version>1</version>
    <chassisRef xsi:type="physical:Chassis">
    
<instanceName>com.cisco.dcbu.dcm.model.physical.Chassis:neId=2,chassisId=TBM11256510</inst
anceName>
    </chassisRef>
    <slotNumber>1</slotNumber>
   </itemSet>
   <itemSet xsi:type="physical:Slot">
    <instClassName>com.cisco.dcbu.dcm.model.physical.Slot</instClassName>
    <instanceClassId>6152</instanceClassId>
    
<instanceName>com.cisco.dcbu.dcm.model.physical.Slot:neId=2,chassisId=TBM11256510,slotNumb
er=5</instanceName>
    <instanceState>Unmodified</instanceState>
    <version>1</version>
    <chassisRef xsi:type="physical:Chassis">
    
<instanceName>com.cisco.dcbu.dcm.model.physical.Chassis:neId=2,chassisId=TBM11256510</inst
anceName>
    </chassisRef>
    <slotNumber>5</slotNumber>
   </itemSet>
   <itemSet xsi:type="physical:Slot">
    <instClassName>com.cisco.dcbu.dcm.model.physical.Slot</instClassName>
    <instanceClassId>6156</instanceClassId>
    
<instanceName>com.cisco.dcbu.dcm.model.physical.Slot:neId=2,chassisId=TBM11256510,slotNumb
er=12</instanceName>
    <instanceState>Unmodified</instanceState>
    <version>1</version>
    <chassisRef xsi:type="physical:Chassis">
    
<instanceName>com.cisco.dcbu.dcm.model.physical.Chassis:neId=2,chassisId=TBM11256510</inst
anceName>
    </chassisRef>
    <slotNumber>12</slotNumber>
   </itemSet>
   <itemSet xsi:type="physical:Slot">
    <instClassName>com.cisco.dcbu.dcm.model.physical.Slot</instClassName>
    <instanceClassId>6154</instanceClassId>
    
<instanceName>com.cisco.dcbu.dcm.model.physical.Slot:neId=2,chassisId=TBM11256510,slotNumb
er=11</instanceName>
    <instanceState>Unmodified</instanceState>
    <version>1</version>
    <chassisRef xsi:type="physical:Chassis">
    
<instanceName>com.cisco.dcbu.dcm.model.physical.Chassis:neId=2,chassisId=TBM11256510</inst
anceName>
    </chassisRef>
    <slotNumber>11</slotNumber>
   </itemSet>
   </slotCol>
  </itemList>
  </return>
 </m:getAllChassisInNetworkResponse>
 </env:Body>
</env:Envelope>

Error Handling

Exceptions that can occur are listed under each method.

Licensing Requirements for Web Services

The following table shows the licensing requirements for this feature:

Product
License Requirement

DCNM

Web services requires no license. Any feature not included in a license package is bundled with the Cisco DCNM and is provided at no charge to you. For a complete explanation of the DCNM licensing scheme, see the Cisco DCNM Licensing Guide.


Additional References

For additional information related to implementing the Web Services API, see the following sections:

Related Documents

Standards

Related Documents

Related Topic
Document Title

XML management interface

Cisco Nexus 7000 Series NX-OS XML Management Interface User Guide, Release 4.0

DCNM client

Cisco DCNM Fundamentals Configuration Guide, Release 4.0


Standards

Standards
Title

No new or modified standards are supported by this feature, and support for existing standards has not been modified by this feature.