Web Service API Reference Guide for Cisco Application Networking Manager 5.2 and 5.1

Transcription

1 Web Service API Reference Guide for Cisco Application Networking Manager 5.2 and 5.1 Version 5.2 and 5.1 February 2012 Americas Headquarters Cisco Systems, Inc. 170 West Tasman Drive San Jose, CA USA Tel: NETS (6387) Fax: Text Part Number:

2 THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS, INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS. THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY, CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY. The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB s public domain version of the UNIX operating system. All rights reserved. Copyright 1981, Regents of the University of California. NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED AS IS WITH ALL FAULTS. CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE. IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1110R) Any Internet Protocol (IP) addresses used in this document are not intended to be actual addresses. Any examples, command display output, and figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses in illustrative content is unintentional and coincidental Cisco Systems, Inc. All rights reserved.

3 CONTENTS Preface ix Audience ix Organization ix Related Documentation x Conventions x Open-Source Software Included in the Cisco Application Networking Manager Obtaining Documentation and Submitting a Service Request xi xi CHAPTER 1 Introduction to the Cisco 1-1 ANM Web Services Overview 1-1 Using the ANM Web Services 1-2 Required Software, Web Standards, and Supported Hardware 1-2 Enabling the Web Services Interface 1-2 Obtaining the Web Services Language File 1-3 Generating the Client Code to Invoke a Web Service 1-3 Calling an ANM Web Service and Posting a SOAP Request 1-4 CHAPTER Mapping Table 2-1 OperationManager Web Service APIs 2-3 login 2-4 logout 2-6 listdeviceids 2-7 listvirtualcontexts 2-9 listvirtualservers 2-11 listserverfarms 2-14 listrservers 2-16 listserverfarmrservers 2-18 listanswers 2-21 listdnsrules 2-23 activatevirtualserver 2-25 suspendvirtualserver 2-27 addrservertoserverfarm 2-29 removerserverfromserverfarm 2-32 iii

4 Contents activateserverfarmrserver 2-35 suspendserverfarmrserver 2-38 changeserverfarmrserverweight 2-41 activateanswer 2-44 suspendanswer 2-46 activatednsrule 2-48 suspenddnsrule 2-50 getvmmappinginfo 2-52 ApplicationTemplateManager Web Service APIs 2-54 listtemplatedefinitions 2-54 gettemplatedefinitionmetadata 2-58 createtemplateinstance 2-63 listtemplateinstances 2-68 deletetemplateinstance 2-69 listcheckpoints 2-71 createcheckpoint 2-73 deletecheckpoint 2-75 rollbackcheckpoint 2-77 freeformshow 2-79 CHAPTER 3 Web Service Objects 3-1 Answer 3-2 Checkpoints 3-2 DeviceID 3-2 DeviceType 3-3 DnsRule 3-3 MatchCondition 3-4 Rserver 3-4 Serverfarm 3-4 SessionToken 3-4 SfRserver 3-5 TemplateDefinition 3-5 TemplateInput 3-6 TemplateInstance 3-6 VMMappingInfo 3-6 Vserver 3-7 WSException 3-7 iv

5 Contents CHAPTER 4 Troubleshooting Problems 4-1 SOAP Message Traffic and Time Taken to Invoke an API 4-1 Custom Application Errors 4-2 Modifying the Number of Concurrent Sessions Allowed 4-3 Use Case 1: SampleWSClient A-1 Use Case 2: ActivateSuspendSfRserverClient A-5 Use Case 3: Virtual Server WS Client A-10 Use Case 4: GSSWSClient A-17 Use Case 5: ApplTemplateCreateWSClient A-23 I NDEX v

6 Contents vi

7 Preface This guide describes the Cisco Application Networking Manager Web Services application program interface (API) implementation and explains how to use it to manage your network. This preface provides information about using this guide. This preface includes the following sections: Audience, page ix Organization, page ix Related Documentation, page x Conventions, page x Open-Source Software Included in the Cisco Application Networking Manager, page xi Obtaining Documentation and Submitting a Service Request, page xi Audience This API guide is written for the knowledgeable application programmer who understands the basic architecture of the Cisco Application Networking Manager (ANM). This document provides detailed descriptions of Web Service APIs supported by ANM. Depending on the configuration required, readers should have specific knowledge in the following areas: Networking and data communications Network security Router configuration Datacenter products Organization This document contains the following sections: Chapter 1, Introduction to the Cisco provides an overview of the programmable interface and the methods and schemas used to perform configuration operations using the API. Chapter 2, lists all APIs and describes them. Chapter 3, Web Service Objects lists the data types that are defined structures or objects in the. ix

8 Preface Chapter 4, Troubleshooting Problems lists the custom application errors. Appendix A, Use Case Examples lists the use case sample code examples. Related Documentation In addition to this installation guide, the Application Networking Manager (ANM) documentation set includes the following publications. You can access the ANM documentation on at: Installation Guide for the Cisco Application Networking Manager Includes complete installation and configuration information for the ANM software. Installation Guide for the Cisco Application Networking Manager Virtual Appliance Includes complete information about ANM virtual appliance functionality, installation, configuration, and administration procedures. User Guide for the Cisco Application Networking Manager Includes complete information about ANM functionality and detailed procedures for its use. Contains all of the information found in online help. Available either on cisco.com or from the ANM online help. Context-sensitive online help Includes help topics for all pages in the UI (also provides access to PDFs of the user guide). Select an option from the ANM GUI, and click Help. Supported Devices Table for the Cisco Application Networking Manager Includes complete supported device and firmware versions for ANM. Supplemental License Agreement for the Cisco Application Networking Manager Describes licensing limitations and restrictions. Conventions This document uses the following conventions: Item Commands and keywords Variables for which you supply values Displayed session and system information Information you enter Variables you enter Menu items and button names Choosing a menu item in paragraphs Choosing a menu item in tables Convention boldface font italic font screen font boldface screen font italic screen font boldface font Option > Network Preferences Option > Network Preferences Note Means reader take note. Notes contain helpful suggestions or references to material not covered in the publication. x

9 Preface Caution Means reader be careful. In this situation, you might do something that could result in equipment damage or loss of data. Open-Source Software Included in the Cisco Application Networking Manager The Cisco Application Networking Manager includes the following open-source software, which is covered by the Apache 2.0 license ( Ant, Avalon Logkit, Commons, Ehcache, Jetty, Log4J, Oro, Commons_Logging, Xmlrpc. The Cisco Application Networking Manager includes the following open-source software, which is covered by The Legion of the Bouncy Castle ( license: BouncyCastle. The Cisco Application Networking Manager includes the following open-source software, which is covered by the GNU Lesser General Public License Version 2.1 ( c3p jar, Enterprise DT, Jasperreports 1.2, Jcommon 1.2, Jfreechart The Cisco Application Networking Manager includes the following open-source software, which is covered by the Mozilla Public License Version 1.1 ( Itext 1.4. Obtaining Documentation and Submitting a Service Request For information on obtaining documentation, submitting a service request, and gathering additional information, see the monthly What s New in Cisco Product Documentation, which also lists all new and revised Cisco technical documentation, at: Subscribe to the What s New in Cisco Product Documentation as a Really Simple Syndication (RSS) feed and set content to be delivered directly to your desktop using a reader application. The RSS feeds are a free service and Cisco currently supports RSS version 2.0. xi

10 Preface xii

11 CHAPTER 1 Introduction to the Cisco This chapter describes the Cisco ANM Web Services application programming interface (API), which provides a programmable interface for system developers to integrate with customized or third-party management applications. This chapter contains the following sections: ANM Web Services Overview, page 1-1 Obtaining the Web Services Language File, page 1-3 Using the ANM Web Services, page 1-2 ANM Web Services Overview The ANM Web Services are a Web Service implementation, which is defined by the W3C standard as a software system designed to support interoperable machine-to-machine (client and server) interaction over the network. Client and server communication follows the Simple Object Access Protocol or Service Oriented Architecture Protocol (SOAP) standard. SOAP, which exchanges XML-based messages over the network using HTTP or HTTPS, is the foundation layer of the Web Service stack. It provides a basic messaging framework that allows more abstract layers to build on. SOAP encoding wraps XML headers and tags in a SOAP envelope. ANM is a Java application that uses Java SE 6. Java SE 6 is a standard with Web Services support in the form of JSR 224, Java API for XML-Based Web Services (JAX-WS) 2.0. ANM makes use of Java SE 6 Web Services support to implement its Web Services-based NBI. Java SE 6 also supports JSR 181, Web Services Metadata for the Java Platform. JSR 181 makes it possible to develop web services. Additionally, Java SE 6 makes it extremely easy to publish a Java Web Service by using javax.xml ws.endpoint of JAX-WS. ANM provides the following Web Services to support the operation of the devices it manages, such as the Cisco Application Control Engine: Operation Manager Perform operational tasks such as: Log in and out of ANM. List objects such as virtual contexts, real servers, virtual servers, serverfarms, serverfarm real servers, VIP answers, and DNS rules. Activate or susupend objects. ApplicationTemplateManager Perform the following tasks: Manage application templates used to configure ACE devices. 1-1

12 Using the ANM Web Services Chapter 1 Introduction to the Cisco Manage configuration checkpoints. Obtain specific show command output. For a complete list of the devices that the ANM Web Services support, see the Required Software, Web Standards, and Supported Hardware section on page 1-2. Using the ANM Web Services This section describes how to use the ANM Web Services. It contains the following topics: Required Software, Web Standards, and Supported Hardware, page 1-2 Enabling the Web Services Interface, page 1-2 Obtaining the Web Services Language File, page 1-3 Generating the Client Code to Invoke a Web Service, page 1-3 Calling an ANM Web Service and Posting a SOAP Request, page 1-4 Required Software, Web Standards, and Supported Hardware The ANM Web Services are supported in ANM software Version 4.1 and later. The API examples in this document require the following development environment: Java SE 6 Note Java SE 6 is applicable only if the client code is java-based. WSDL Support: 1.1 SOAP 1.1 The is supported on the following product types: Cisco Application Control Engine (ACE) module and applicance Cisco Content Services Switch (CSS) Cisco Content Switching Module (CSM) Cisco Content Switching Module with SSL (CSM-S) Cisco Global Site Selector (GSS) Enabling the Web Services Interface ANM uses the following ports for Web Services: http port: 8080 https port: 8443 After you have installed the ANM software, you can reconfigure ANM configuration properties, such as enabling HTTP(S) for Web Services. For information about enabling Web Services, see the Changing ANM Configuration Property Values section in the User Guide for the Cisco Application Networking Manager

13 Chapter 1 Introduction to the Cisco Using the ANM Web Services Obtaining the Web Services Language File In the ANM Web Services, Web Services Language (WSDL) is used with SOAP and XML schemas to provide Web Services. WSDL is an XML-based service that describes the functionality offered by the Web Service and defines the actions, parameter names, input parameter data types, and return data types for the Web Service. When you connect to a Web Service through a web browser, you can read the WSDL file to determine which functions are available on the server. Any special data types that are used are embedded in the WSDL file in an XML schema. You can then call one of the functions listed in the WSDL file by sending a SOAP request message. To obtain the WSDL file defined for a particular service in the implementation, submit a URL to the service with a?wsdl suffix. For example, to retrieve the WSDL for the OperationManager service running on call the WSDL file by using the following URL: For more examples, see the Generating the Client Code to Invoke a Web Service section on page 1-3. Generating the Client Code to Invoke a Web Service To generate the client source code, follow these steps: Step 1 Step 2 Step 3 Download the WSDL file from the server using the following WSDL URL formats: OperationManager WSDL: or ApplicationTemplateManager WSDL: or where the host/ip value is the hostname or IP address of the ANM that has the service running. Save the file as either OperationManager.wsdl or ApplicationTemplateManager.wsdl, depending on which one you are downloading. Generate and compile the source code by using the wsimport command as follows: wsimport -d <specify where to place generated output files> -s <specify where to place generated source files> {OperationManager.wsdl ApplicationTemplateManager.wsdl The above command generates the java source code from the wsdl file and then compiles it and puts the class file in the same location where the source file.wsimport file is located in the dir $JAVA_HOME/bin. Note This step is applicable only if the client code is a java-based code. 1-3

14 Using the ANM Web Services Chapter 1 Introduction to the Cisco Calling an ANM Web Service and Posting a SOAP Request To call a service, you connect to a particular ANM through a web browser by using a service URL that contains the IP address or hostname of the ANM and the name of the particular service (such as OperationManager). For example, is the service URL for the OperationManager Web Service. You use the same format to call the ApplicationTemplateManager Web Service. By default, ANM 5.1 supports up to 10 concurrent sessions for Web Services (see the Modifying the Number of Concurrent Sessions Allowed section on page 4-3). Next, you must post a SOAP request written in a XML format to retrieve the information. The request calls for a particular action (such as login) and the input parameter content when required. The ANM responds with a SOAP envelope that contains the answer in an XML format. The response contains the output values for this action. Example Request The following example shows an XML-formatted SOAP request to perform the login action. There are no input parameters for this particular action. <?xml version="1.0" encoding="utf-8"?> <SOAP-ENV:Envelope xmlns:soap-env=" xmlns:xsd=" xmlns:xsi=" <SOAP-ENV:Body> <login xmlns=" <user xmlns="">admin</user> <password xmlns="">admin</password> </login> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Example Response The following example shows the XML response to the login request. The response contains output values such as the SessionToken. <?xml version="1.0" encoding="utf-8"?> <S:Envelope xmlns:s=" <S:Body> <ns2:loginresponse xmlns:ns2=" <SessionToken xmlns=""> <sid> </sid> </SessionToken> </ns2:loginresponse> </S:Body> </S:Envelope> 1-4

15 CHAPTER 2 This chapter describes the s, which allows you to manage the Cisco Application Control Engine (ACE) module, Cisco Application Control Engine (ACE) appliance, Cisco Content Services Switch (CSS) and Cisco Content Switching Module (CSM), Cisco Content Switching Module with SSL (CSM-S), and Cisco Global Site Selector (GSS) using ANM. ANM Web Services provide APIs to support configuration functionalities. All APIs are implemented as synchronous calls and each call is a transaction. This chapter contains the mapping table and describes the following ANM APIs: Mapping Table OperationManager Web Service APIs ApplicationTemplateManager Web Service APIs Mapping Table Table 2-1 displays the mapping of each API with the specified role and the domain, where F = Full access N = No access Table 2-1 Mapping Table API Name Role Name VM-Mapper SSL-Cert-Key-Admin SSL-Admin SLB-Admin Server-Maintenance Server-Appln-Maintenance Security-Admin Org-Admin Network-Monitor Network-Admin ANM-Admin ACE-Admin listdeviceids N F N F F N N N N N N N listvirtualcontexts F F F F F N N N N N N N listvirtualservers F F N F F N F F F N N N 2-1

16 Mapping Table Chapter 2 Table 2-1 Mapping Table (continued) API Name Role Name VM-Mapper SSL-Cert-Key-Admin SSL-Admin SLB-Admin Server-Maintenance Server-Appln-Maintenance Security-Admin Org-Admin Network-Monitor Network-Admin ANM-Admin ACE-Admin listserverfarms F F N F F N F F F N N N listrservers F F N F F N F F F N N N listserverfarmrservers F F N F F N F F F N N N listanswers N F N N F N F F F N N N listdnsrules N F N N F N F F F N N N activatevirtualserver F F N N F N N N F N N N suspendvirtualserver F F N N F N N N F N N N addrservertoserverfarm F F N F F N F F F N N N removerserverfromserverfarm F F N N F N F N F N N N activateserverfarmrserver F F N N F N F F F N N N suspendserverfarmrserver F F N N F N F F F N N N changeserverfarmrserverweight F F N N F N F F F N N N activateanswer N F N N F N N F F N N N suspendanswer N F N N F N N F F N N N activatednsrule N F N N F N N F F N N N suspenddnsrule N F N N F N N F F N N N getvmmappinginfo N F N N F N N N N N N F listtemplatedefinitions F F N N F N N N N N N N gettemplatedefinitionmetadata F F N N F N N N N N N N createtemplateinstance F F N N F N N N N N N N listtemplateinstances F F N N F N N N N N N N deletetemplateinstance F F N N F N N N N N N N listcheckpoints F F N N F N N N N N N N createcheckpoint F F N N F N N N N N N N deletecheckpoint F F N N F N N N N N N N rollbackcheckpoint F F N N F N N N N N N N freeformshow F F N N F N N N N N N N 2-2

17 Chapter 2 OperationManager Web Service APIs OperationManager Web Service APIs This section describes the APIs associated with the OperationManager Web Service, which are as follows: login logout listdeviceids listvirtualcontexts listvirtualservers listserverfarms listrservers listserverfarmrservers listanswers listdnsrules activatevirtualserver suspendvirtualserver addrservertoserverfarm removerserverfromserverfarm activateserverfarmrserver suspendserverfarmrserver changeserverfarmrserverweight activateanswer suspendanswer activatednsrule suspenddnsrule getvmmappinginfo 2-3

18 OperationManager Web Service APIs Chapter 2 login This request logs in an application user to ANM. The login API validates the credentials and returns a session token. The session times out after being idle for 30 minutes even if the logout is not called.by default, ANM allows 10 concurrent API logins, but you can modify this number (see the Modifying the Number of Concurrent Sessions Allowed section on page 4-3). Input Parameters Parameter Username Password Username of the application user. Password of the application user. Output Parameters Parameter SessionToken Session key of the application user. Exceptions Type Exception Maximum session limit configured_limit reached for WS. Note The default is 10 (see the Modifying the Number of Concurrent Sessions Allowed section on page 4-3). Invalid username or password. Please try again. Session ID is in use. Please try again later. Username cannot be null. Password cannot be null. Example Request The following example shows an XML-formatted SOAP request to perform the login action. The input parameters for this particular action are username and password. <?xml version="1.0" encoding="utf-8"?> <SOAP-ENV:Envelope xmlns:soap-env=" xmlns:xsd=" xmlns:xsi=" <SOAP-ENV:Body> <login xmlns=" <user xmlns="">admin</user> <password xmlns="">admin</password> </login> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Example Response The following example shows the XML response: <?xml version="1.0" encoding="utf-8"?> 2-4

19 Chapter 2 OperationManager Web Service APIs <S:Envelope xmlns:s=" <S:Body> <ns2:loginresponse xmlns:ns2=" <SessionToken xmlns=""> <sid> </sid> </SessionToken> </ns2:loginresponse> </S:Body> </S:Envelope> 2-5

20 OperationManager Web Service APIs Chapter 2 logout This request logs out an application user from the ANM. The session times out after being idle for 30 minutes even if the logout is not called. In case of a session timeout, the following exception string is generated: Invalid Session Id. Input Parameters Parameter SessionToken Session key of the application user. Output Parameters Parameter None None. Exceptions Type Exception Invalid Session ID. Example Request The following example shows an XML-formatted SOAP request to perform the logout action. Session token is the input parameter for this particular action. <?xml version="1.0" encoding="utf-8"?> <SOAP-ENV:Envelope xmlns:soap-env=" xmlns:xsd=" xmlns:xsi=" <SOAP-ENV:Body> <logout xmlns=" <sessiontoken xmlns=""> <sid> </sid> </sessiontoken> </logout> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Example Response The following example shows the XML response that contains no output parameter: <?xml version="1.0" encoding="utf-8"?> <S:Envelope xmlns:s=" <S:Body> <ns2:logoutresponse xmlns:ns2=" </S:Body> </S:Envelope> 2-6

21 Chapter 2 OperationManager Web Service APIs listdeviceids This request lists all device IDs for a device type from the ANM inventory. If none of the devices is imported in ANM, it returns an empty list. Input Parameters Parameter SessionToken DeviceType Session key of the application user. List of device types including the device name and status. For example, CSS, CSM, CAT6K, GSS, VIRTUAL_CONTEXT, ACE4710, and ACE_BLADE. Output Parameters Parameter DeviceIDs List of device IDs including the device name, device type, IP address, slot, and chassis IP address attributes. Exceptions Type Exception Invalid Session ID. Unsupported Device Type: device_type. Device Type should not be null. Example Request The following example shows an XML-formatted SOAP request to perform the listdeviceids action. SessionToken and DeviceType are the input parameters for this particular action. <?xml version="1.0" encoding="utf-8"?> <SOAP-ENV:Envelope xmlns:soap-env=" xmlns:xsd=" xmlns:xsi=" <SOAP-ENV:Body> <listdeviceids xmlns=" <sessiontoken xmlns=""> <sid> </sid> </sessiontoken> <devicetype xmlns="">virtual_context</devicetype> </listdeviceids> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Example Response The following example shows the XML response that contains DeviceID as the output parameter: <?xml version="1.0" encoding="utf-8"?> <S:Envelope xmlns:s=" <S:Body> <ns2:listdeviceidsresponse xmlns:ns2=" <DeviceIDs xmlns=""> 2-7

22 OperationManager Web Service APIs Chapter 2 <item> <name>admin</name> <devicetype>virtual_context</devicetype> <ipaddr> </ipaddr> </item> <item> <name>vc1</name> <devicetype>virtual_context</devicetype> <ipaddr> </ipaddr> </item> <item> <name>vc2</name> <devicetype>virtual_context</devicetype> <ipaddr> </ipaddr> </item> <item> <name>vc3</name> <devicetype>virtual_context</devicetype> <ipaddr> </ipaddr> </item> <item> <name>vc4</name> <devicetype>virtual_context</devicetype> <ipaddr> </ipaddr> </item> <item> <name>admin</name> <devicetype>virtual_context</devicetype> <slot>3</slot> <chassisipaddr> </chassisipaddr> </item> <item> <name>vc1</name> <devicetype>virtual_context</devicetype> <slot>3</slot> <chassisipaddr> </chassisipaddr> </item> <item> <name>admin</name> <devicetype>virtual_context</devicetype> <slot>4</slot> <chassisipaddr> </chassisipaddr> </item> <item> <name>vc1</name> <devicetype>virtual_context</devicetype> <slot>4</slot> <chassisipaddr> </chassisipaddr> </item> </DeviceIDs> </ns2:listdeviceidsresponse> </S:Body> </S:Envelope> 2-8

23 Chapter 2 OperationManager Web Service APIs listvirtualcontexts This request lists all the virtual contexts for an Application Control Engine (ACE) module or ACE appliance from the ANM inventory. This API is supported only on ACE modules and appliances (device type: ACE_BLADE and ACE4710). Input Parameters Parameter SessionToken DeviceID Session key of the application user. ACE module: Device ID includes the device type, slot, and chassis IP address attributes. ACE appliance: Device ID includes the device type, IP address, and name attributes. Output Parameters Parameter DeviceIDs List of virtual context device IDs including the device type, IP address, slot, and chassis IP address attributes. Exceptions Type Exception Invalid Session ID. Given ACE module is not yet imported in ANM. Given ACE Appliance does not exist in ANM. None of the devices are imported. Unsupported Device Type: device_type. Given ACE module does not exist in the chassis: Chassis_IPaddress. Device Type should be not null. chassisipaddr and ipaddr are not added in deviceid. Either should be provided. Both chassisipaddr and ipaddr are added in deviceid. Only one of them can be added. DeviceID should not be not null. DeviceType is set as ACE_BLADE, but the mandatory field slot is set as null or empty. DeviceType is set as ACE4710, but the mandatory field ipaddr is set as null or empty. Invalid IP Address: IPaddress. DeviceType is set as ACE_BLADE, but the mandatory field slot is set as null or empty. Example Request The following example shows an XML-formatted SOAP request to perform the listvirtualcontexts action. SessionToken and DeviceID are the input parameters for this particular action. 2-9

24 OperationManager Web Service APIs Chapter 2 <?xml version="1.0" encoding="utf-8"?> <SOAP-ENV:Envelope xmlns:soap-env=" xmlns:xsd=" xmlns:xsi=" <SOAP-ENV:Body> <listvirtualcontexts xmlns=" <sessiontoken xmlns=""> <sid> </sid> </sessiontoken> <deviceids xmlns=""> <devicetype>ace_blade</devicetype> <slot>3</slot> <chassisipaddr> </chassisipaddr> </deviceids> </listvirtualcontexts> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Example Response The following example shows the XML response that contains the list of virtual context DeviceIDs as the output parameter: <?xml version="1.0" encoding="utf-8"?> <S:Envelope xmlns:s=" <S:Body> <ns2:listvirtualcontextsresponse xmlns:ns2=" <DeviceIDs xmlns=""> <item> <name>admin</name> <devicetype>virtual_context</devicetype> <slot>3</slot> <chassisipaddr> </chassisipaddr> </item> <item> <name>vc1</name> <devicetype>virtual_context</devicetype> <slot>3</slot> <chassisipaddr> </chassisipaddr> </item> </DeviceIDs> </ns2:listvirtualcontextsresponse> </S:Body> </S:Envelope> 2-10

25 Chapter 2 OperationManager Web Service APIs listvirtualservers This request lists all the virtual servers configured on the specified device. The device can be a CSS, CSM, or a virtual context (VIRTUAL_CONTEXT) on an ACE module or ACE appliance. Input Parameters Parameter SessionToken DeviceID allvss Session key of the application user. Virtual context DeviceID, which contains the virtual server name, device type, IP address, chassis slot, and chassis IP address attributes. (Optional) Input parameter that instructs ANM to return a list of all virtual servers that match ANM s virtual server definition and those that do not match this definition but that ANM can recognize as virtual servers using SNMP polling. By default, ANM returns only the virtual servers that match ANM s virtual server definition. Output Parameters Parameter vservers List of all virtual servers including the virtual server name, policy-map name, and IP address attributes. Exceptions Type Exception Invalid Session ID. Maximum session limit configured_limit reached for WS. Note The default is 10 (see the Modifying the Number of Concurrent Sessions Allowed section on page 4-3). Given ACE module is not yet imported in ANM. Given ACE Appliance does not exist in ANM. None of the devices are imported. Unsupported Device Type: device_type. Given ACE module does not exist in the chassis: Chassis_IPaddress. Device Type should be not null. chassisipaddr and ipaddr are not added in deviceid. Either should be provided. Both chassisipaddr and ipaddr are added in deviceid. Only one of them can be added. DeviceID should not be not null. DeviceType is set as VIRTUALCONTEXT, but the mandatory field slot is set as null or empty. DeviceType is set as VIRTUALCONTEXT, but the mandatory field name is set as null or empty. 2-11

26 OperationManager Web Service APIs Chapter 2 Invalid IP Address: IPaddress. Given virtual context name [VC name] does not exist in the ACE Devices. DeviceType is set as CSS, but the mandatory field ipaddr is set as null or empty. DeviceType is set as VIRTUAL_CONTEXT, but the mandatory field ipaddr is set as null or empty. Device Type is set as CSM, but the mandatory field chassisipaddr is set as null or empty. Device Type is set as CSM, but the mandatory field slot is set as null or empty. Example Request The following example shows an XML-formatted SOAP request to perform the listvirtualservers action. SessionToken, DeviceID, and allvss are the input parameters for this particular action. <?xml version="1.0" encoding="utf-8"?> <SOAP-ENV:Envelope xmlns:soap-env=" xmlns:xsd=" xmlns:xsi=" <SOAP-ENV:Body> <listvirtualservers xmlns=" <sessiontoken xmlns=""> <sid> </sid> </sessiontoken> <deviceid xmlns=""> <name>admin</name> <devicetype>virtual_context</devicetype> <ipaddr/> <slot>2</slot> <chassisipaddr> </chassisipaddr> </deviceid> <allvs xmlns="">false</allvs> </listvirtualservers> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Example Response The following example shows the XML response that contains the list of virtual servers as the output parameter: <?xml version="1.0" encoding="utf-8"?> <S:Envelope xmlns:s=" <S:Body> <ns2:listvirtualserversresponse xmlns:ns2=" <listvirtualservers xmlns=""> <item> <virtualservername>14_simple_vs</virtualservername> <policymapname>int2</policymapname> <matchconditions> <ipaddress> </ipaddress> <protocol>tcp</protocol> 2-12

27 Chapter 2 OperationManager Web Service APIs <port>2</port> </matchconditions> <serverfarms>14_simple_sf</serverfarms> <vlans>2</vlans> <adminstate>down</adminstate> <operstate>down</operstate> <lastpolledtime>fri May 27 16:52:31 IST 2011</lastPolledTime> </item> <item> <virtualservername>ds_simple_vs</virtualservername> <policymapname>int161</policymapname> <matchconditions> <ipaddress> </ipaddress> <protocol>tcp</protocol> <port>6</port> </matchconditions> <serverfarms>ds_simple_sf</serverfarms> <vlans>161</vlans> <adminstate>down</adminstate> <operstate>down</operstate> <lastpolledtime>fri May 27 16:52:31 IST 2011</lastPolledTime> </item> <item> <virtualservername>test</virtualservername> <policymapname>global</policymapname> <matchconditions> <ipaddress> </ipaddress> <protocol>tcp</protocol> <port>443</port> </matchconditions> <serverfarms>gh</serverfarms> <vlans/> <adminstate>up</adminstate> <operstate>down</operstate> <lastpolledtime>fri May 27 16:52:31 IST 2011</lastPolledTime> </item> </listvirtualservers> </ns2:listvirtualserversresponse> </S:Body> </S:Envelope> 2-13

28 OperationManager Web Service APIs Chapter 2 listserverfarms This request lists all server farms on a virtual context from the ANM inventory. This API is supported only on ACE devices (device type: VIRTUAL_CONTEXT). Input Parameters Parameter SessionToken DeviceID Session key of the application user. Virtual context device ID including the device name, device type, IP address, slot, and chassis IP address attributes. Output Parameters Parameter Serverfarms List of server farm objects including the name and type (host or redirect) attributes. Exceptions Type Exception Invalid Session ID. Maximum session limit [configured_limit] reached for WS. The default is 10 (see the Modifying the Number of Concurrent Sessions Allowed section on page 4-3). Given ACE module is not yet imported in ANM. Given ACE Appliance does not exist in ANM. None of the devices are imported. Unsupported Device Type: device_type. Given ACE module does not exist in the chassis: Chassis_IPaddress Device Type should be not null. chassisipaddr and ipaddr are not added in deviceid. Either should be provided. Both chassisipaddr and ipaddr are added in deviceid. Only one of them can be added. DeviceID should not be not null. DeviceType is set as VIRTUALCONTEXT, but the mandatory field slot is set as null or empty. DeviceType is set as VIRTUALCONTEXT, but the mandatory field name is set as null or empty. Invalid IP Address: IPaddress. Given virtual context name VC_name does not exist in the ACE Devices. Example Request The following example shows an XML-formatted SOAP request to perform the listserverfarms action. SessionToken and DeviceID are the input parameters for this particular action. <?xml version="1.0" encoding="utf-8"?> 2-14

29 Chapter 2 OperationManager Web Service APIs <SOAP-ENV:Envelope xmlns:soap-env=" xmlns:xsd=" xmlns:xsi=" <SOAP-ENV:Body> <listserverfarms xmlns=" <sessiontoken xmlns=""> <sid> </sid> </sessiontoken> <deviceid xmlns=""> <name>admin</name> <devicetype>virtual_context</devicetype> <ipaddr> </ipaddr> </deviceid> </listserverfarms> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Example Response The following example shows the XML response that contains the list of Serverfarm objects as the output parameter: <?xml version="1.0" encoding="utf-8"?> <S:Envelope xmlns:s=" <S:Body> <ns2:listserverfarmsresponse xmlns:ns2=" <serverfarms xmlns=""> <item> <name>sf1</name> <serverfarmtype>host</serverfarmtype> </item> <item> <name>sf2</name> <serverfarmtype>host</serverfarmtype> </item> </serverfarms> </ns2:listserverfarmsresponse> </S:Body> </S:Envelope> 2-15

30 OperationManager Web Service APIs Chapter 2 listrservers This request lists all the real servers on a virtual context from the ANM inventory. This API is supported only on ACE devices (device type: VIRTUAL_CONTEXT). Input Parameters Parameter SessionToken DeviceID Session key of the application user. Virtual context device ID including the device name, device type, IP address, slot, and chassis IP address attributes. Output Parameters Parameter Rservers List of real server objects including the name, IP address, admin state, and weight attributes. Exceptions Type Exception Invalid Session ID. Maximum session limit configured_limit reached for WS. The default is 10 (see the Modifying the Number of Concurrent Sessions Allowed section on page 4-3). Given ACE module is not yet imported in ANM. Given ACE appliance does not exist in ANM. None of the devices are imported. Unsupported Device Type: device_type. Given ACE module does not exist in the chassis: Chassis_IPaddress. Device Type should be not null. chassisipaddr and ipaddr are not added in deviceid. Either should be provided. Both chassisipaddr and ipaddr are added in deviceid. Only one of them can be added. DeviceID should not be not null. DeviceType is set as VIRTUALCONTEXT, but the mandatory field slot is set as null or empty. DeviceType is set as VIRTUALCONTEXT, but the mandatory field name is set as null or empty. Invalid IP Address: IPaddress. Given virtual context name VC_name does not exist in the ACE devices. Example Request The following example shows an XML-formatted SOAP request to perform the listrservers action. SessionToken and DeviceID are the input parameters for this particular action. <?xml version="1.0" encoding="utf-8"?> 2-16

31 Chapter 2 OperationManager Web Service APIs <SOAP-ENV:Envelope xmlns:soap-env=" xmlns:xsd=" xmlns:xsi=" <SOAP-ENV:Body> <listrservers xmlns=" <sessiontoken xmlns=""> <sid> </sid> </sessiontoken> <deviceid xmlns=""> <name>admin</name> <devicetype>virtual_context</devicetype> <ipaddr> </ipaddr> </deviceid> </listrservers> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Example Response The following example shows the XML response that contains the list of real server objects as the output parameter: <?xml version="1.0" encoding="utf-8"?> <S:Envelope xmlns:s=" <S:Body> <ns2:listrserversresponse xmlns:ns2=" <Rservers xmlns=""> <item> <name>rs1</name> <type>host</type> <state>is</state> <weight>8</weight> </item> <item> <name>rs2</name> <type>redirect</type> <state>is</state> </item> </Rservers> </ns2:listrserversresponse> </S:Body> </S:Envelope> 2-17

32 OperationManager Web Service APIs Chapter 2 listserverfarmrservers This request lists all the real servers present in the given server farm from the ANM inventory. If the server farm name is provided as empty or null in the input parameters, it lists all the real server objects in the given virtual context. This API is supported on CSS, CSM, and ACE devices (device type: CSS, CSM, and VIRTUAL_CONTEXT). Input Parameters Parameter SessionToken DeviceID Serverfarmname Session key of the application user. Device ID of the virtual context including the device name, device type, IP address, slot and chassis IP address attributes. Name of an existing server farm. It can be empty, null, or a specific server farm configured in the device. Output Parameters Parameter SfRservers List of server farm real server objects including server farm name, server farm real server name, IP address, admin state, weight, and port value attributes. Exceptions Type Exception Invalid session ID. Maximum session limit configured_limit reached for WS. The default is 10 (see the Modifying the Number of Concurrent Sessions Allowed section on page 4-3). Given ACE module is not yet imported in ANM. Given ACE appliance does not exist in ANM. None of the devices are imported. Unsupported Device Type: device_type. Given ACE module does not exist in the chassis: Chassis_IPaddress. Device Type should be not null. chassisipaddr and ipaddr are not added in deviceid. Either should be provided. Both chassisipaddr and ipaddr are added in deviceid. Only one of them can be added. DeviceID should not be not null. DeviceType is set as VIRTUALCONTEXT, but the mandatory field slot is set as null or empty. DeviceType is set as VIRTUALCONTEXT, but the mandatory field name is set as null or empty. Invalid IP Address: IPaddress. Given virtual context name VC_name does not exist in the ACE Devices. 2-18

33 Chapter 2 OperationManager Web Service APIs DeviceType is set as CSS, but the mandatory field ipaddr is set as null or empty. DeviceType is set as VIRTUAL_CONTEXT, but the mandatory field ipaddr is set as null or empty. Device Type is set as CSM, but the mandatory field chassisipaddr is set as null or empty. Device Type is set as CSM, but the mandatory field slot is set as null or empty. Example Request The following example shows an XML-formatted SOAP request to perform the listserverfarmrservers action. SessionToken, DeviceID, and Serverfarmname are the input parameters for this particular action. <?xml version="1.0" encoding="utf-8"?> <SOAP-ENV:Envelope xmlns:soap-env=" xmlns:xsd=" xmlns:xsi=" <SOAP-ENV:Body> <listserverfarmrservers xmlns=" <sessiontoken xmlns=""> <sid> </sid> </sessiontoken> <deviceid xmlns=""> <name>admin</name> <devicetype>virtual_context</devicetype> <ipaddr> </ipaddr> </deviceid> <serverfarmname xmlns="">sf1</serverfarmname> </listserverfarmrservers> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Example Response The following example shows the XML response that contains SfRserver as the output parameter: <S:Envelope xmlns:s=" <S:Body> <ns2:listserverfarmrserversresponse xmlns:ns2=" <SfRservers xmlns=""> <item> <serverfarmname>sf1</serverfarmname> <realservername> sanitytesting</realservername> <adminstate>is</adminstate> <operationstate>up</operationstate> <weight>8</weight> <port>0</port> <lastpolledtime>wed Jun 08 20:53:18 IST 2011</lastPolledTime> </item> <item> <serverfarmname>1</serverfarmname> <realservername>anm-vm-118</realservername> <adminstate>is</adminstate> 2-19

34 OperationManager Web Service APIs Chapter 2 <weight>19</weight> <port>0</port> </item> <item> <serverfarmname>sf1</serverfarmname> <realservername>test</realservername> <adminstate>oos</adminstate> <operationstate>up</operationstate> <weight>8</weight> <port>443</port> <ipaddr> </ipaddr> <lastpolledtime>wed Jun 08 20:53:18 IST 2011</lastPolledTime> </item> </SfRservers> </ns2:listserverfarmrserversresponse> </S:Body> </S:Envelope> 2-20

35 Chapter 2 OperationManager Web Service APIs listanswers This request lists all the VIP answers configured on the specified given GSS. Input Parameters Parameter SessionToken DeviceID Session key of the application user. GSS device ID, which contains the GSS name, device type, and IP address attributes. Output Parameters Parameter answers List of answer objects, including the answer name, IP address, configuration state, and type attributes. The type attribute is always vip. Exceptions Type Exception Invalid session token. GSS does not exist. Session timeout. Cannot reach the GSS. Example Request The following example shows an XML-formatted SOAP request to perform the listanswers action. SessionToken and DeviceID are the input parameters for this particular action. <?xml version="1.0" encoding="utf-8"?> <SOAP-ENV:Envelope xmlns:soap-env=" xmlns:xsd=" xmlns:xsi=" <SOAP-ENV:Body> <listanswers xmlns=" <sessiontoken xmlns=""> <sid> </sid> </sessiontoken> <deviceid xmlns=""> <name>gss</name> <devicetype>gss</devicetype> <ipaddr> </ipaddr> <slot>0</slot> <chassisipaddr/> </deviceid> </listanswers> </SOAP-ENV:Body> </SOAP-ENV:Envelope> 2-21

36 OperationManager Web Service APIs Chapter 2 Example Response The following example shows the XML response that contains answers as the output parameter: <?xml version="1.0" encoding="utf-8"?> <S:Envelope xmlns:s=" <S:Body> <ns2:listanswersresponse xmlns:ns2=" <Answers xmlns=""> <item> <ipaddr> </ipaddr> <answername>vip2131</answername> <type>null</type> <configstate>activate</configstate> <ansergroups>vipgrp1066</ansergroups> <location>null</location> <device>gss</device> <operstate>active</operstate> <pgssmtime>17:50:19</pgssmtime> </item> </DeviceIDs> </ns2:listanswersresponse> </S:Body> </S:Envelope> 2-22

37 Chapter 2 OperationManager Web Service APIs listdnsrules This request lists all the DNS rules configured on the specified given GSS. Input Parameters Parameter SessionToken DeviceID Session key of the application user. GSS device ID, which contains the GSS name, device type, and IP address attributes. Output Parameters Parameter dnsrules List of DNS rule objects, including the DNS rule name, source IP address, owner, and configuration state attributes. Exceptions Type Exception Invalid session token. GSS does not exist. Session timeout. Cannot reach the GSS. Example Request The following example shows an XML-formatted SOAP request to perform the listdnsrules action. SessionToken and DeviceID are the input parameters for this particular action. <?xml version="1.0" encoding="utf-8"?> <SOAP-ENV:Envelope xmlns:soap-env=" xmlns:xsd=" xmlns:xsi=" <SOAP-ENV:Body> <listdnsrules xmlns=" <sessiontoken xmlns=""> <sid> </sid> </sessiontoken> <deviceid xmlns=""> <name>40</name> <devicetype>gss</devicetype> <ipaddr> </ipaddr> </deviceid> </listdnsrules> </SOAP-ENV:Body> </SOAP-ENV:Envelope> Example Response The following example shows the XML response that contains dnsrules as the output parameter: <?xml version="1.0" encoding="utf-8"?> <S:Envelope 2-23

38 OperationManager Web Service APIs Chapter 2 xmlns:s=" <S:Body> <ns2:listdnsrulesresponse xmlns:ns2=" <listdnsrules xmlns=""> <item> <dnsrulename>dns1</dnsrulename> <sourceaddress>anywhere</sourceaddress> <domains>dom1</domains> <dnsconfigstate>active</dnsconfigstate> <answergroups>null</answergroups> <owner>system</owner> </item> </listdnsrules> </ns2:listdnsrulesresponse> </S:Body> </S:Envelope> 2-24

39 Chapter 2 OperationManager Web Service APIs activatevirtualserver This request activates an existing virtual server, putting it into service. This API is supported on CSS, CSM, and virtual contexts (VIRTUAL_CONTEXT) on ACE modules and appliances. Note For CSS and CSM devices, after changing the state, SNMP polling is triggered. The API does not return until the polling is complete. Input Parameters Parameter SessionToken DeviceID vserver Reason Session key of the application user. Virtual server device ID, including the device name, device type, IP address, slot, and chassis IP address attributes. Virtual server object, including the virtual server name, policy-map name, and IP address attributes. Reason for the activation. Output Parameters Parameter None None. Exceptions Type Exception Invalid session token. Virtual context does not exist. Session timeout. Cannot reach the virtual context. Virtual server does not exist. Config errors from the ACE, CSS, or CSM. Example Request The following example shows an XML-formatted SOAP request to perform the activatevirtualserver action. SessionToken, DeviceID, and virtualserver (vip1) are the input parameters for this particular action. <?xml version="1.0" encoding="utf-8"?> <SOAP-ENV:Envelope xmlns:soap-env=" xmlns:xsd=" xmlns:xsi=" <SOAP-ENV:Body> <activatevirtualserver xmlns=" <sessiontoken xmlns=""> <sid> </sid> </sessiontoken> <deviceid xmlns=""> 2-25