Web Services API. Avocent DSView Management and Rack Power Manager Software
โฆษณา
โฆษณา
Web Services API
The Web Services API allows applications to interact with other applications by using open standards such as
EXtensible Markup Language (XML) and Simple Object Access Protocol (SOAP). This interaction enables your applications, tools and systems to manage information in the DSView or Rack Power Manager software and provides support for accessing information, performing some unit control and adding events to the event log.
Syntax Conventions
This documentation uses the following syntax conventions:
•
Bold type indicates user-supplied values.
•
Square brackets ([ ]) enclose optional values.
Web Operating Environment
Protocols
The web operating environment uses the following protocols:
•
SOAP version 1.1 - messaging protocol
•
HTTPS Internet protocol - used in a production environment with the Enterprise DSView software
•
HTTP or HTTPS Internet protocol - used in a development environment with the SDE
Applications
Your applications can reside on the same system as the DSView software server or on another server.
Supported languages include, but are not limited to:
•
Java Axis 1.2
•
C++ using Axis C++ 1.4 (only on Microsoft Windows systems)
Implementation
The implementation of the Web Services API is based on Axis (Apache Axis 1.2), an open-source SOAP server and client.
Definition Files
EXtensible Markup Language (XML) is a platform-independent markup language that describes data contents, not format. Two XML-based languages are Web Service Description Language and XML Schema Definition
Language. The Web Service API includes the following XML files:
•
WSDL files define the web services, port types, messages and service bindings
•
XSD files define schemas for SOAP fault codes, common headers and messages, components and structures
Web Services API definition files are located in the libs directory.
22
.....
Full Software Development Kit Installer/User Guide
SOAP Message Structure
The following table contains the syntax and sequence of the SOAP message (envelope) structure. The same structure applies to requests and responses. In actual applications, italicized text is replaced by applicationspecific, site-specific or user-specific values.
SOAP Message Syntax and Sequence
Name
<soapenv:Envelope>
<soapenv:Header>
<sessionHeader>
<sessionId>sessionID</sessionId>
<username>username</username>
<password>password
</password>
<zonename/>
<servicename/>
</sessionHeader>
</soapenv:Header>
<soapenv:Body>
<someMethod>Body of request or response
<someMethodAttributes></someMethodAttributes>
Description
Opening tag for a standard SOAP envelope.
Opening tag for a standard SOAP header.
Opening tag for a DSView software session header. Generally, the header on an initial request passes the username and password for user authentication and authorization. In all responses that report success, the header includes the session
ID for session reuse on subsequent calls.
Unique user session ID created by the DSView software. The user session ID, which is used for authentication and authorization, can be:
•
Created by supplying user credentials (username and password) in a request.
•
Created by an authenticate request.
•
Destroyed by a logout request.
Each Web Services API session exclusively uses one session license from the pool of available sessions.
Username component of credentials for a DSView software user account. This is required in all request headers if a valid session ID is not provided. If a username is provided in the request header, it is also returned in the response header.
Password component of credentials for a DSView software user account. This is required in all request headers if a valid session ID is not provided. If a password is provided in the request header, it is also returned in the response header.
Name of the zone that the user and service account belong to.
The user and service account must belong to the same zone. If no zone name is provided, the top level zone name is used by default.
Name of the service account.
Closing tag for a DSView software session header.
Closing tag for a standard SOAP header.
Opening tag for a standard SOAP body.
In a request, this section contains any parameters or attributes needed to perform the request. Parameter data values are user-supplied. In a response, this section contains any returned
Web Services API .....
23
Name
</someMethod>
</soapenv:Body>
</soapenv:Envelope>
Description
data.
Opening tag for a standard SOAP body.
Closing tag for a standard SOAP envelope.
Example SOAP request
An example of a SOAP request for all unit details for the unit at IP address 192.168.1.1 is as follows.
POST /dsview/services/UnitServiceApi?wsdl HTTP/1.0
Content-Type: text/xml; charset=utf-8
Accept: application/soap+xml, application/dime, multipart/related, text/*
User-Agent: Axis/1.2
Host: localhost:8081
Cache-Control: no-cache
Pragma: no-cache
SOAPAction: "urn:units:webservices:server:dsview:avocent:com#getUnitDetail"
Content-Length: 1099
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header>
<ns1:sessionHeader soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" soapenv:mustUnderstand="0" xmlns:ns1="urn:common:webservices:server:dsview:avocent:com">
<ns1:credentials>
<ns1:sessionId>3fn5lc16l9s47</ns1:sessionId>
<ns1:username>admin</ns1:username>
<ns1:password>password</ns1:password>
</ns1:credentials>
</ns1:sessionHeader>
</soapenv:Header>
<soapenv:Body>
<getUnitDetail xmlns="urn:schema:units:webservices:server:dsview:avocent:com">
<getUnitDetailRequest xsi:type="ns2:GetUnitDetailRequestType" xmlns:ns2="urn:schema:units:webservices:server:dsview:avocent:com">
<unitId>
<ns3:address xmlns:ns3="urn:common:webservices:server:dsview:avocent:com">
192.168.1.1</ns3:address>
</unitId>
24
.....
Full Software Development Kit Installer/User Guide
<showFields>
<ns4:fields xmlns:ns4="urn:common:webservices:server:dsview:avocent:com">
</ns4:fields>
</showFields>
</getUnitDetailRequest>
</getUnitDetail>
</soapenv:Body>
</soapenv:Envelope>
Example SOAP response
An example of a SOAP response to a SOAP request for all unit details for the unit at IP address 192.168.1.1 is as follows.
HTTP/1.1 200 OK
Date: Wed, 06 Jul 2005 18:41:36 GMT
Server: Jetty/4.2.12 (Windows XP/5.1 x86 java/1.5.0_03)
Set-Cookie: JSESSIONID=tgr8f2752ier;path=/dsview
Content-Type: text/xml; charset=utf-8
<?xml version="1.0" encoding="utf-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<soapenv:Header>
<ns1:sessionHeader soapenv:actor="http://schemas.xmlsoap.org/soap/actor/next" soapenv:mustUnderstand="0" xmlns:ns1="urn:common:webservices:server:dsview:avocent:com">
<ns1:credentials>
<ns1:sessionId>3fn5lc16l9s47</ns1:sessionId>
<ns1:username>admin</ns1:username>
<ns1:password>password</ns1:password>
</ns1:credentials>
</ns1:sessionHeader>
</soapenv:Header>
<soapenv:Body>
<getUnitDetailResponse xmlns="urn:schema:units:webservices:server:dsview:avocent:com">
<ns2:version xmlns:ns2="urn:common:webservices:server:dsview:avocent:com">1.0
</ns2:version>
<return>
<unitId>9217</unitId>
<name>target</name>
Web Services API .....
25
<address>192.168.1.1</address>
</return>
</getUnitDetailResponse>
</soapenv:Body>
</soapenv:Envelope>
Session Management Service
Operations in the Session Management Service allow your application to control the lifespan of user sessions established with the Web Services API.
A session is initiated by supplying user credentials (username, password and optional service name and zone name). However, the session begins only after the DSView software server authenticates the user credentials (the Web Services API requires that all requests be authenticated) and grants the session exclusive use of one of a limited number of licenses for user sessions.
The Web Services API does not support multi-step authentication. For example, if you belong to the RSA
SecurID external authentication service and New Pin Mode is configured, additional prompting at the login is required and the authentication from the Web Services API fails. You must log in to the DSView software and change the account settings so that multi-step authentication is not required.
The DSView software server then includes your credentials and a newly-created session ID in its response to the application. To conserve licenses, your application can reuse this session ID in subsequent requests. If your application attempts to reuse a session ID after the session has timed out, the DSView software server creates a new session with the passed credentials and then processes the request.
NOTE: After a user is authenticated, the DSView software server authorizes information access based on configured access rights.
The session ends when either of the following conditions occur:
•
The idle time for the session equals the session time-out value configured in the DSView software. This is the default behavior.
•
Your application explicitly terminates the session (logs out) when the session is no longer needed. This is the better practice.
Service accounts
In the DSView software, you can configure user accounts or service accounts that never expire. This is useful for applications and systems that use a fixed or dedicated account to access the DSView software using the
Web Services API.
Both the username and servicename must represent valid users in the DSView software. The service account must be an internal user account while the impersonated user can be either an internal or external account.
A service account cannot be used to log in as a regular user through either the Web Services API or the
DSView software. The username and password fields of the SessionHeader for the request must not contain the credentials for a service account. Certificate log-in is not supported.
To log in as a service account and impersonate another user:
Enter the following values in the SessionHeader:
26
.....
Full Software Development Kit Installer/User Guide
•
servicename field - the name of a service account
•
password field - the password for the service account
•
username field - the name of the user
•
zone name field - the name of the zone that the user and service account belong to. The user and service account must belong to the same zone. If no zone name is provided, the top level zone name is used by default.
The session rights are the intersection of the rights assigned to the service account and the user account. The
DSView software logs the session activity for the user.
NOTE: The GUI Access API does not support impersonated user sessions. However, you can use impersonated user sessions with the GUI Access API if a session is first established with the Web
Services API. Use the session ID returned from the impersonated user session to make requests to the
GUI Access API.
To log in as a service account without impersonating another user:
Enter the following values in the SessionHeader:
•
servicename field - the name of a service account
•
password field - the password for the service account
Do not include the username field in the request. The session rights are the rights assigned to the service account.
To log in as a regular user not using a service account:
Enter the following values in the SessionHeader:
•
password field - the password for the user account
•
username field - the name of a non-service account
•
zone name field - the name of the zone that the user belongs to. If no zone name is provided, the top level zone name is used by default.
Do not include the servicename field in the request. The session rights are the rights assigned to the user.
Definition file
The filename for the DSView software session management service definition file is dsviewService-
SessionMgmt.wsdl
Visit https://dsviewServer[:dsviewPort]/dsview/services/ EventServiceApi?wsdl to retrieve the WSDL dynamically generated for you.
Operations
The following table describes Session Management Service operations.
Web Services API Session Management Service Operations
Name Description
getVersion
Requests the current version of the Session Management Service from the DSView software server. The
Web Services API .....
27
Name
authenticate logout
Description
format of the returned string is: majorVersion.minorVersion.
A change in minorVersion indicates the service is modified but maintains backward compatibility with existing client implementations at the same majorVersion level. A change in majorVersion indicates the service is modified and cannot maintain backward compatibility.
Requests the DSView software server to authenticate the user credentials (username and password) or session ID provided in the session header of a SOAP envelope and if successful:
•
Log in the user associated with the request.
•
Grant exclusive use of one user session license.
•
Start the session.
Respond to the request with the user credentials and a newly created session ID in the sessionHeader. The
DSView software server compares the provided credentials with user accounts in its internal database. This operation is redundant and provided for completeness. The DSView software server validates user credentials and session IDs provided in the session header of all requests. Generally, if you explicitly request authentication, it should be done before any other Web Services API requests.
Requests the DSView software server:
•
Log out the current user associated with the request.
•
Relinquish the user session license.
•
Terminate the active user session for the Web Services API.
•
Retire the session ID from further use.
Event Service
Operations in the Event Service allow your application to add events to the DSView software event log.
Definition file
The filename for the DSView software event service definition file is dsviewService-Event.wsdl.
Visit http[s]://dsviewServer[:dsviewPort]/dsview/services/UnitServiceApi?wsdl to retrieve the WSDL dynamically generated for you.
Operations
The following table describes the Event Service operations.
Web Services API Event Service Operations
Name Description
getVersion
Requests the current version of the Event Service from the DSView software server. The format of the returned string is: majorVersion.minorVersion.
A change in minorVersion indicates the service is modified but maintains backward compatibility with existing client implementations at the same majorVersion level. A change in majorVersion indicates the service is modified and cannot maintain backward compatibility. The following lists the DSView software version and
28
.....
Full Software Development Kit Installer/User Guide
Name Description
the corresponding API returns:
•
DSView 4 returns API version 1.1
•
DSView 4.5.0.247 returns API version 1.2
•
DSView 4.5 SP5 returns API version 2.0
addEvent getEvent
Requests the DSView software server log an event in its event log. The event is based on the information provided in the body of a SOAP envelope. This supplements event-related functionality in the DSView software.
Requests the event details for Access Control, Appliance, Authentication, Data Logging, External, IPMI,
Modem, Session, SSH Passthrough, Status, System, Tasks, Units, Users and Virtualization. The input parameters are:
•
Severities (Mandatory) - When entering multiple severities, separate them with a comma.
•
Categories (Optional) - When entering multiple categories, separate them with a comma.
•
dateRange (Optional) - Enter the date and time in UTC format.
•
State (Optional) - Enter either New or Acknowledged.
•
unitOnly (Optional) - Enter either True or False.
DoAcknowledgeEvent
Sets the event status to acknowledged. The input parameters are:
•
EventOid (Mandatory) - When entering multiple OIDs, separate them with a comma.
SetDCPEventSettings
Updates the event settings for the DCP server information. The input parameters are:
•
trapEnabled (Mandatory) - Enter true if it is enabled and false if it is disabled. If you enter false, the
DSView and Rack Power Mount software does not enable the trap function and does not push event data to the DCP.
•
trapInterval (Mandatory) - Enter a minute value between one and 60.
•
Severities (Mandatory) - When entering multiple severities, separate them with a comma.
•
Categories (Optional) - When entering multiple categories, separate them with a comma.
•
Hostname: Enter or update the DCP IP address.
•
apiPort (Mandatory) - Enter the DCP web service port number which is always fixed at 8443.
•
authPort (Mandatory) - Enter the AMP authentication port number which is always fixed at 8092.
•
Account (Mandatory) - Enter the account name for the DCP user who has administrative rights.
•
Password (Mandatory) - Enter the password for the account.
•
apiVersion (Mandatory) - Enter the version number of the DCP integration web service APIs which is fixed at 1.
User Service
Operations in the User Service allow a third party client to manage DSView software users.
Definition file
The filename for the DSView software user service definition file is dsviewService-User-wsdl.
Web Services API .....
29
Visit http[s]://dsviewServer[:dsviewPort]/dsview/services/UserServiceApi?wsdl to retrieve the WSDL dynamically generated for you.
Operations
The following table describes the User Service operations. The operations addUserToUserGroup, removeUserFromUserGroup and removeUserFromAllUserGroup returns one of the following integers:
•
1 = Operation successful.
•
2 = Operation failed; user provided in request was invalid.
•
3 = Operation failed; user group data provided in request was invalid.
•
4 = Operation failed; logged in user did not have adequate rights.
•
5 = Operation failed; the group to be removed contained the last DSView software user administrator in the system.
•
6 = Invalid unit name/OID.
•
7 = No such unit from the database.
•
8 = Invalid right.
•
9 = Invalid unit group name/OID.
•
10 = Invalid authentication or preemption level.
•
11 = Username already exists.
Name Description
getVersion addUserToUserGroups
Determines the current version of the User Service.
Adds a user in the DSView software to internal user group(s).
removeUserFromUserGroups Removes a user in the DSView software from internal user group(s).
removeUserFromAllUserGroups Removes a user in the DSView software from all internal user groups this user is assigned to.
getUserGroupsAssignedToUser Determines which internal user groups a user in the DSView software is assigned to.
addLocalUser
Creates a new local user in the DSView software.
The input parameters are:
•
Administrative credentials which include the following:
•
Username - DSView software admin username
•
Password - DSView software admin user password
•
UserName - Username to be added into the DSView software
•
UserPass - Password
•
authServerName - Authorization server in which the user is added. The authServerName value for DSView is ‘DSView Internal’.
•
User Group Name (optional) – The Group Name in which the user must be added. The
Group ID for built-in user groups are:
•
1 = DSView software administrators
•
2 = User administrators
30
.....
Full Software Development Kit Installer/User Guide
Name
deleteLocalUser modifyLocalUserDetail queryAllLocalUsers
Description
•
3 = Appliance administrators
•
4 = Auditors
•
5 = Users
•
User Group Type (optional)– Group Type is the parent node where group name resides and includes the following:
•
User Group Type 1 - To add user under built-in group
•
User Group Type 2 - To add user under user defined group
Deletes a local user from the DSView software.
The input parameters are:
•
Administrative credentials which include the following:
•
Username - DSView software admin username
•
Password - DSView software admin user password
•
Username - The username to be deleted from the DSView software
Modifies local user details such as preemption level, password, address, email addresses, contact numbers and notes.
The input parameters are:
•
Administrative credentials which include the following:
•
Username - DSView software admin username
•
Password - DSView software admin user password
•
Preemption Level - The preemption level of the user which ranges from 1 to 4
•
Password - User password
•
Home Address - User's home address
•
Business Address - User’s business address
•
Business Phone - User’s business phone
•
Home Phone - User’s home phone
•
Mobile Phone - User’s mobile phone
•
Mobile Business Phone - User’s mobile business phone
•
Email Addresses - Primary and additional email addresses
•
Notes - Notes about the local user
Finds all internal users from the DSView software.
The input parameters are:
•
Administrative credentials which include the following:
•
Username - DSView software admin username
•
Password - DSView software admin user password
•
Search string (optional) – Keyword to search for all the users that contain this search string
Name
addRightsToUser deleteRightsFromUser
Web Services API .....
31
Description
Adds rights to a local user on specific units/unit groups.
The input parameters are:
•
Administrative credentials which include the following:
•
Username - DSView software admin username
•
Password - DSView software admin user password
•
Username - Name of the user that rights are being set for
•
List of rights - The list of available rights
•
Right Name - Right to be set. The codes for the rights include:
•
0 = View unit information
•
1 = Reboot appliance and disconnect sessions
•
2 = Flash upgrade appliance
•
3 = Configure unit settings
•
4 = Configure appliance local user accounts
•
5 = Establish viewer sessions
•
6 = Control target device power
•
7 = Establish virtual media sessions
•
8 = Establish reserved virtual media sessions
•
9 = View data logging
•
List of Units - The list of available units to assign user rights to and the following information for each unit:
•
Unit ID - Unit ID
•
Unit Name (optional) – Unit Name
•
List of Unit Groups - The list of available user groups to assign user rights and the following information for each group:
•
Unit Group Id - Group id
•
Unit Group Name (optional) – Group Name
Deletes rights of a local user on specific units/unit groups.
The input parameters are:
•
Administrative credentials which include the following:
•
Username - DSView software admin username
•
Password - DSView software admin user password
•
Username - The name of the user that rights are being removed from
•
List of rights - The list of available rights to be removed
•
Right Name - Right to be set. The codes for the rights include:
•
0 = View unit information
32
.....
Full Software Development Kit Installer/User Guide
Name
modifyRightsToUsers
Description
•
1 = Reboot appliance and disconnect sessions
•
2 = Flash upgrade appliance
•
3 = Configure unit settings
•
4 = Configure appliance local user accounts
•
5 = Establish viewer sessions
•
6 = Control target device power
•
7 = Establish virtual media sessions
•
8 = Establish reserved virtual media sessions
•
9 = View data logging
•
List of Units - The list of available units to remove user rights from and the following information for each unit:
•
Unit Id - Unit id
•
Unit Name (optional) – Unit Name
•
List of Unit Groups - The list of available unit groups to remove rights from and the following information for each group:
•
Unit Group Id - Group id
•
Unit Group Name (optional) – Group Name
Modifies (adds/deletes) the rights of a local user on specific units.
The input parameters are:
•
Administrative credentials which include the following:
•
Username - DSView software admin username
•
Password - DSView software admin user password
•
Username - The name of the user with rights being modified
•
Right Name - Right to be set. The codes for the rights include:
•
0 = View unit information
•
1 = Reboot appliance and disconnect sessions
•
2 = Flash upgrade appliance
•
3 = Configure unit settings
•
4 = Configure appliance local user accounts
•
5 = Establish viewer sessions
•
6 = Control target device power
•
7 = Establish virtual media sessions
•
8 = Establish reserved virtual media sessions
•
9 = View data logging
•
List of rights to be modified and the following information:
Web Services API .....
33
Name Description
•
Right Name - Right to be set.
•
List of Units - The available units to modify user rights and the following information for each unit:
•
Unit ID - Unit ID
•
Unit Name (optional) – Unit name
•
List of Unit Groups - The available unit groups to modify user rights queryRightsToUser getUserAndAuthServers
Lists the rights of a local user on specific units/Units Groups.
The input parameters are:
•
Administrative credentials which includes the following:
•
Username - DSView software admin username
•
Password - DSView software admin user password
•
Username - Username being queried
•
Unit Name - Unit name being queried
Returns all of the User Oids (useroid), User Names (username), Authentication Service Oids
(authServiceOid) and Authentication Service Names (authServerName) of every user (excluding virtual users) within the DSView 4 database.
The input parameters are:
•
Administrator credentials which include the following:
•
Username - DSView software admin username
•
Password - DSView software admin user password getUserGroupAndAuthServers getUserEffectiveRights
Returns all of the User Group Oids (userOid), User Group Names (userName), Authentication
Server Oids (authServerOid) and Authentication Server Names (authServerName) within the
DSView 4 database.
The input parameters are:
•
Administrator credentials which include the following:
•
Username - DSView software admin username
•
Password - DSView software admin user password
Returns all the effective rights on each unit for the specified user/user group.
The input parameters are:
•
Administrator credentials which include the following:
•
Username - DSView software admin username
•
Password - DSView software admin user password
•
Target User or User Group including the following:
•
Authentication Server Name
34
.....
Full Software Development Kit Installer/User Guide
LDAP User Service
Operations in the LDAP User Service allow a third party client to manage external LDAP users.
Definition file
The filename for the DSView software LDAP user service definition file is dsviewService-LdapUser.wsdl.
Visit https://dsviewServer[:dsviewPort]/dsview/services/LdapUserServiceApi?wsdl to retrieve the WSDL dynamically generated.
Operations
One of the following operations from the LDAP user service is returned:
•
1 = Operation success
•
2 = Invalid username
•
3 = Invalid user group
•
4 = Insufficient rights for operation
•
5 = Admin only
•
6 = Invalid unit name/OID
•
7 = No such unit
•
8 = Invalid right
•
9 = Invalid unit group name/OID
•
10 = Invalid authentication or preemption level
•
11 = Username already exists
Name
getExternalAuthServices getExternalLDAPUsers addLDAPUsers
Description
Lists all the external LDAP authentication services.
The input parameters are:
•
Administrative credentials Username including the following:
•
DSView software admin username password
•
DSView software admin user password
Lists all the external LDAP users belonging to one LDAP server.
The input parameters are:
•
Administrative credentials Username including the following:
•
DSView software admin username password
•
DSView software admin user password
•
LDAP Server - LDAP server name
Adds an LDAP user into DSView management software.
The input parameters are:
•
Administrative credentials which include the following:
Name
deleteLDAPUsers modifyLDAPUsers getLDAPUsers
Web Services API .....
35
Description
•
Username - DSView software admin username
•
Password - DSView software admin user password
•
Username - Username to be added into the DSView software
•
LDAP Server - LDAP Server name in which the user is added
•
User Group Name - The group name in which the user must be added
•
User Group Type (optional) – Group type is a parent node where group name resides and includes the following:
•
User Group Type 1 - To add a user under a built-in group
•
User Group Type 2 - To add a user under a user-defined group
•
Preemption Level - The preemption level of the user which ranges from 1 to 4
Deletes LDAP users from DSView management software.
The input parameters are:
•
Administrative credentials which include the following:
•
Username - DSView software admin username
•
Password - DSView software admin user password
•
LDAP Server - LDAP server name in which the user is to be deleted
•
Username - Username to be deleted into the DSView software
Modifies the DSView software group of an LDAP user in the DSView software.
The input parameters are:
•
Administrative credentials which include the following:
•
Username - DSView software admin username
•
Password - DSView software admin user password
•
LDAP Server - LDAP server name
•
Username - Username to be modified in the DSView software
•
New Name - The new name for the LDAP user
•
Full Name - The full name of the LDAP user
Lists all the LDAP users added in the DSView software.
The input parameters are:
•
Administrative credentials which include the following:
•
Username - DSView software admin username
•
Password - DSView software admin user password
•
LDAP Server - LDAP server name
•
Search String - Keyword search for all the users that contain this search string
•
Group Name - Group name
36
.....
Full Software Development Kit Installer/User Guide
Name Description
•
Group Type - Group type addRightsToLDAPUser
Sets rights to a user in units/unit groups.
The input parameters are:
•
Administrative credentials which include the following:
•
Username - DSView software admin username
•
Password - DSView software admin user password
•
LDAP Server - LDAP server name
•
Username - LDAP username that rights are set for
•
List of Units - Units on which the rights are set
•
List of Unit Groups - Unit groups that rights are set for removeRightsFromLDAPUser
Removes user rights in units/unit groups.
The input parameters are:
•
Administrative credentials which include the following:
•
Username - DSView software admin username
•
Password - DSView software admin user password
•
LDAP Server - LDAP server name
•
Username - LDAP username to remove rights
•
List of Units –The available units with user rights to be removed
•
List of Unit Groups - The available unit groups with user rights to be removed modifyRightsForLDAPUser getRightsFromLDAPUser
Modifies rights of a user in units.
The input parameters are:
•
Administrative credentials which include the following:
•
Username - DSView software admin username
•
Password - DSView software admin user password
•
LDAP Server - LDAP server name
•
Username - LDAP username to modify rights
•
List of rights to be added
•
List of rights to be removed
•
List of Units - Units with user rights to be modified
•
List of Unit Groups - Unit Groups with user rights to be modified
Lists all the rights of a LDAP user in units.
The input parameters are:
•
Administrative credentials which include the following:
•
Username - DSView software admin username
Web Services API .....
37
Name Description
•
Password - DSView software admin user password
•
LDAP Server - LDAP server name
•
Username - LDAP username to view rights
•
List of Units - Units to review the user rights
•
List of Unit Groups - Unit groups to review the user rights
User Group Service
This web service provides operations to third-party clients to manage LDAP user groups in DSView software and set the rights on them.
Definition file
The filename for the DSView software user group service definition file is dsviewService-UserGroup.wsdl.
Visit https://dsviewServer[:dsviewPort]/dsview/services/UserGroupsServiceApi?wsdl to retrieve the WSDL dynamically generated for you.
Operations
One of the following operations from the User Group service is returned:
•
1 = Operation success
•
2 = Invalid unit/unit group
•
3 = Invalid user group
•
4 = Insufficient rights
•
5 = Invalid right
•
6 = Right does not exist
•
7 = LDAP authentication server does not exist
•
8 = Invalid Role ID
•
9 = User group does not exist
•
10 = Invalid preemption level
•
11 = User group already exists
User Group Service Options
Name Description
listExternalAuthService getUserGroupsFromLDAP addUserGroup deleteUserGroup
Lists the external authentication services
Gets the User Group list from LDAP
Adds an LDAP user group into the DSView software
Deletes LDAP groups from the DSView software
38
.....
Full Software Development Kit Installer/User Guide
Name
modifyUserGroup queryUserGroup addUserGroupRights deleteUserGroupRights modifyUserGroupsRights getListUserGroupsRights
Description
Modifies the User Group Name, Preemption Level and Role of a given LDAP group
Lists all the LDAP groups added into the DSView software
Sets the rights to an LDAP user group on specific units
Removes the rights of an LDAP user group on specific units
Modifies the LDAP user group rights on given units
Lists all the rights of an LDAP user group on specific units
Remote Session Service
This web service provides a feature to open a video viewer session (KVM/Serial) remotely through which a third-party client can access the target devices.
Definition file
The filename for the DSView software remote session service definition file is dsviewService-
RemoteSession.wsdl.
Visit https://dsviewServer[:dsviewPort]/dsview/services/ RemoteSessionServiceApi?wsdl to retrieve the
WSDL dynamically generated for you.
Operations
One of the following operations from the Remote Session Service is returned:
•
001 = Operation is success
•
002 = Input data missing
•
003 = Remote system does not exist
•
004 = Remote system is closed
•
005 = User does not have authentication
•
006 = Operation not allowed for this remote unit
•
007 = Invalid input
•
008 = Remote session is used, but client does not want to preempt
•
009 = Remote unit does not match session type
Remote Session Service Options
Name Description
connVMSession
Opens viewer for KVM/Serial session.
The input parameters are:
•
Administrative credentials which include the following:
•
Username - DSView software admin username
•
Password - DSView software admin user password
Web Services API .....
39
Name
terminateVMSession
Description
•
Session Type - KVM/Serial session
•
Target Name - Target device name
Terminates a KVM/Serial session.
The input parameters are:
•
Administrative credentials which include the following:
•
Username - DSView software admin username
•
Password - DSView software admin user password
•
OID - Appliance OID of the target device to be connected
•
Name - Appliance name of the target device to be connected
•
Address - Appliance address of the target device to be connected
•
Target Name - Target device name to which a session needs to be opened
Unit Service
Operations in the Unit Service allow your application to manage units (target devices and managed appliances) using the DSView software.
Definition File
The filename for the DSView software unit service definition file is dsviewService-Unit.wsdl.
Visit http[s]://dsviewServer[:dsviewPort]/dsview/services/UnitServiceApi?wsdl to retrieve the WSDL dynamically generated for you.
Operations
One of the following operations from the TDPowerOperation is returned:
•
1 = Operation success
•
2 = Operation failed; User provided request is invalid
•
3 = Remote system does not exist
•
4 = User does not have a right
One of the following operations from the getRequestStatus is returned:
•
0 = A request was received and processed
•
1 = ID for the request is not created
•
2 = Unit was not found
•
3 = No path found to contact unit
•
4 = No owner (plug-in) found to execute the request
•
5 = Request Id is invalid
•
6 = Request completed
•
7 = Invalid operation type
•
8 = Invalid request
40
.....
Full Software Development Kit Installer/User Guide
•
9 = Owner does not support the operations interface
•
10 = Request completion could not be verified
•
11 = No more room in the request queue
•
12= Request received and is in process
Web Services API Unit Service Operations
Name Description
getVersion getUnitList getUnitDetail doAction
Requests the current version of the Unit Service from the DSView software server. The format of the returned string is: majorVersion.minorVersion.
A change in minorVersion indicates the service is modified but maintains backward compatibility with existing client implementations at the same majorVersion level. A change in majorVersion indicates the service is modified and cannot maintain backward compatibility.
Requests the DSView software server retrieve a list of units that match a filter. You can identify a set of attributes to be returned for each unit, along with the set of attributes to be searched (if any) for a match by the filter. The valid data types in this request are:
•
Unit types
•
Unit attributes
•
Unit filter attributes
•
Unit actions
Requests the DSView software server retrieve a set of attributes for a specific unit. The valid data types in this request are:
•
Unit types
•
Unit attributes
•
Unit actions
Requests the DSView software server perform the requested action on the specified unit. The valid data type in this request is unit actions.
performTDPowerOperation
Requests the DSView software server power off and power on the specified units.
The input parameters are:
•
Username - DSView software admin username
•
Password - DSView software admin password
•
Names - Device name to be power cycled
•
IP address (optional) – IP address of the device to be power cycled getRequestStatus getEffectiveRights
Requests DSView software server to get the status of all the devices that have been powered off and powered on. Request ID - requests device IDs from the devices returned as a result of the performTDPowerOperation
Show the user and user group effective rights for a unit or unit group when the target information is entered.
Web Services API .....
41
Name
GerPowerStatus
DoAction getUnitDetailForDCP
Description
The input parameters are:
•
Target (Mandatory) - Enter one of the following values: Unit Name, Unit ID, Unit IP Address,
Unit Group Name or Unit Group ID
•
Type (Optional) - Enter user or usergroup; if you leave the field blank the web service displays both user and user group
Returns the current power status for the outlet.
The input parameters are:
•
OID (Optional) - Enter the object identifier
•
Name (Optional) - Enter the name of the PDU or outlet
Performs the tool action for the device. The following appliance and PDU commands are supported for this release:
•
Reboot (appliance)
•
Shutdown (appliance)
•
Power Operation (PDU and outlets)
The input parameters are:
•
OID - Enter the object identifier
•
Name (Optional) - Enter the name of the PDU or outlet
•
IP address (Optional) - Enter the appliance or PDU IP address
•
Command (Optional) - Enter one of the following commands:
•
acvtWallPowerOff/avctWallPoweron/avctWallPowerCycle
•
avctIPMIPowerON/avctIPMIPowerOff/avctIPMIPowerGracefulOff/ avctIPMIPowerCycle
•
avctIPMIReset/avctIPMIIdentityOn/avctIPMIIdentityOff/avctReboot/avctShutdown
Returns all detailed information for a particular unit including supported power operations, reboot and shutdown details.
The input parameters are:
•
OID - Enter the object identifier
•
Name (Optional) - Enter the name of the PDU or outlet
•
IP address (Optional) - Enter the appliance or PDU IP address
•
showFields (Optional)
Unit Service data definitions
Data types
Data types are generally used for input or parameters in certain Web Services API requests. The following table lists the data types and the Unit Service operations that use them.
42
.....
Full Software Development Kit Installer/User Guide
Web Services API Data Types
Data Type Unit Service Operations That Use This Data Type
Unit Types getUnitList() getUnitDetail()
Unit Attributes
Unit Filter Attributes
Unit Actions getUnitList() getUnitDetail() getUnitList() getUnitList() getUnitDetail() doAction()
Unit types
The DSView software has well-defined unit types for managed appliances, cascade devices and power devices. In addition, as a user of the DSView software, you can define unit types for target devices. By default, the unit type for target devices is blank (empty). The user-defined unit types are strings and can be used in Web Service API requests in the same manner as any of the well-defined unit types.
The SDE recognizes only the Avocent DSR1021, CCM1650 and DSI5100 managed appliances.
The following table lists the unit types and models. See the Avocent® DSView
™
4.5 Management Software
Release Notes for a current list of supported unit types and models.
Web Services API Unit Types
DSView Software Unit Types
ACS advanced console server
Avocent® AutoView
Avocent® MergePoint Unity™
Avocent® Power Management Distribution Unit (PM PDU)
Avocent® SPC power control devices
Avocent® Universal Management Gateway
Emerson® Rack PDUs
Liebert® GXT4™ UPS devices
Liebert® PDUs
APC
Blades
Citrix XenServer
Models
ACS6000
AV2108 and AV2216
1016, 1016DAC, 104E, 108E, 108EDAC, 2016, 2016DAC,
2032, 2032DAC, 4032, 4032DAC, 8032 and 8032DAC
PM1000, PM2000 and PM3000
N/A
2000, 4000 and 6000
MPH2™ and MPX™ (with RPC-2000 cards)
N/A
MPH™ and MPX™ (with RPC-1000 cards)
AP78xx, AP79xx, AP8881, AP8661 and AP8941
Dell DRAC MC, Dell M1000e, FSC BX600, Generic Blade
Chassis, HP BladeSystem, HP BladeSystem c-Class, HP
BladeSystem p-Class, IBM BladeCenter, IBM BladeCenter
H, IBM BladeCenter HT and IBM BladeCenter T
6.5 Standard
Web Services API .....
43
DSView Software Unit Types
Dell Appliances
Dell Remote Console Switch
FW Digital KVM Switch
Fujitsu KVM s4 Appliances
HP Console Switch G2
HP G3 KVM Console Switch
IBM Console Switch
KVM Switch
Lenovo GCM
Lenovo LCM
Microsoft Hyper-V2 on Windows 2008 R2
Microsoft Hyper- V3 on Windows 2012 and 2012 R2
ServerTech Sentry Switched CDU
VMware
Models
Dell 2161DS-2, Dell 2321DS, Dell 4161DS and Dell
8321DS
1082DS, 2162DS and 4322DS
FW-D1008NP, FW-D2016NP, FW-D2032NP, FW-
D4016NP and FW-D8032NP
KVM s4-0812, KVM s4-1622 and KVM s4-3242
Server Console Switch G2 0x2x16, Server Console Switch
G2 0x2x32, IP Console Switch G2 1x1Ex8, IP Console
Switch G2 2x1Ex16 and IP Console Switch G2 4x1Ex32
0x1x8 G3 KVM Console Switch and 0x2x16 G3 KVM
Console Switch
GCM16/32 product family
1x1x8 switch, 2x1x16 switch and 8x1x32 switch
16/32 console switch product family
8/16 switch product family
N/A
N/A
CW-8H1*, CW-8H2*, CW-16V1*, CW-16V2*, CW-24V2*,
CW-24V3*, CW-32VD1*, CW-32VD2*, CW-48V5Z454-
A1P, CW-24VY-L30M, CWG-24V4Z423A9/QR, CW-
8H1A413,CW-24V4K425A9, STV-4501C,STV-6502M and STV-4501C
NOTE: Models with an asterisk (*) must be attached to a managed appliance such as the Avocent®
MergePoint Unity™ KVM over IP and serial console switch.
5.5, 5.5u2 and 6.0
NOTE: If using VMware 6.0, the VI Client link under the
Virtual Center no longer points to a location where the
VMWare Client can be downloaded. VMWare has removed this link, so customers must manually download the VMWare Client executable from VMWare or ESXi.
Unit attributes
The following table describes the unit attributes that can be retrieved from DSView software.
44
.....
Full Software Development Kit Installer/User Guide
Web Services API Unit Attributes
Unit Attribute Description
avctUnitId Unique ID that represents a specific unit in the DSView software. This attribute is always returned.
avctUnitName avctUnitType avctUnitAddress avctUnitNotes avctUnitCustom0
Unit name.
Unit type.
Unit address.
Notes associated with the unit.
Custom field 0 associated with the unit.
avctUnitCustom1 avctUnitCustom2
Custom field 1 associated with the unit.
Custom field 2 associated with the unit.
avctUnitSupportedActions Actions supported by the unit.
avctUnitSessions Comma separated list of sessions available on the unit.
Unit filter attributes
The following table describes the unit attributes that can be searched (used as a filter) for getUnitList requests.
Web Services API Unit Filter Attributes
Unit Filter Attribute Description
avctUnitID avctUnitName avctUnitType avctUnitAddress avctUnitNotes avctUnitCustom0 avctUnitCustom1 avctUnitCustom2
Unit ID
Unit name
Unit type
Unit address
Notes associated with the unit
Custom field 0 associated with the unit
Custom field 1 associated with the unit
Custom field 2 associated with the unit
Unit Actions
The following table describes the unit actions that are supported by the DSView software and can be returned as supported actions of a unit.
Web Services API Unit Actions
Unit Action Description
avctWallPowerOff Powers off each of the SPC sockets connected to the unit
Web Services API .....
45
Unit Action Description
avctWallPowerOn avctWallPowerCycle avctIPMIPowerOn
Powers on each of the SPC sockets connected to the unit
Power cycles each of the SPC sockets connected to the unit
Issues the power on command to each of the IPMI connections to the unit avctIPMIPowerOff Issues the power off command to each of the IPMI connections to the unit avctIPMIPowerGracefulOff Issues the graceful power off command to each of the IPMI connections to the unit avctIPMIPowerCycle avctIPMIReset avctIPMIIdentityOn
Issues the power cycle command to each of the IPMI connections to the unit
Issues the reset command to each of the IPMI connections to the unit avctIPMIIdentityOff
Issues the identity on command to each of the IPMI connections to the unit
Issues the identity off command to each of the IPMI connections to the unit and disables the Identity feature
SOAP Faults
All service requests can potentially cause an error condition. The service attempts to handle error conditions where possible and continue processing the request. Error conditions that prevent the service from completing successfully return a SOAP fault.
SOAP fault fields
The following fields appear in the DSView software:
•
faultcode - A field in that contains fault code values. The following table defines the error status of each fault code.
•
faultstring - A field that contains a brief description of the problem or error.
•
faultactor - The URI of the service causing the fault.
•
detail - A field in the DSView software that is unused.
Web Services API SOAP Fault Codes
Fault Code Value
BadCredentials
SystemError
LicenseLimitReached
UserSessionExpired
UserAccountDisabledLocked
UserPasswordExpired
OperationRequiresAuthentication
Description
Credentials (username or password) not valid.
DSView software system level error. Normally not expected.
Maximum number of allowed user sessions is reached.
User session (HTTP session) used with the request has expired.
User account associated with the request is disabled or locked.
User account associated with the request has an expired password.
Request requires user credentials or a previously established session. User authentication is required.
46
.....
Full Software Development Kit Installer/User Guide
Fault Code Value
NotAuthorized
UnitRequestedNotFound
Description
User account associated with the request is not authorized to perform this request.
Unit associated with the request is not defined in the DSView software system.
UnitRequestedCannotPerformAction Action requested is not supported by the specified unit.
WebServicesDisabled Requested service is not operational.
MultipleMatchingUnitsFound
Unit associated with the request identifies multiple units and the request is intended to be applied to a single unit.
NOTE: Additional SOAP faults can also be generated. These are the SOAP-defined faults for SOAP version 1.1. These faults cannot follow the previously provided format.
Definition file
The filename for the SOAP fault definition file is serviceComponent-Common.xsd.
Java Sample Using Axis
The following procedure runs the sample application Java client, displays SOAP requests and responses and shows the effect in the SDE.
To run the Java client sample application:
1.
Run the SDE.
2.
Run scripts related to the sample Java client.
3.
Change to the directory where the scripts reside:
•
On a Microsoft Windows system, the directory is avocent\dssdk\samples\WebService\Java.
•
On a Linux system, the directory is avocent/dssdk/samples/WebService/Java.
NOTE: A keystore for HTTPS (SSL) holds keys and digital certificates for trusted certificate authorities.
See the following procedure for steps to create a keystore.
4.
If connecting to the SDE with HTTPS (SSL), create a keystore.
-or-
Get the certificate of the DSView software server and save it as dsview.cer in the sample/webservices/java directory.
5.
Build the sample Java client by double-clicking the following script:
•
Microsoft Windows: buildClient.bat
•
Linux: buildClient.sh
6.
Press a key after the prompt.
7.
Run the sample Java client in its own screen by double-clicking the following script:
•
Microsoft Windows: runClient.bat
•
Linux: runClient.sh
Web Services API .....
47
8.
To run the TCP monitor and see SOAP requests and responses in their own screen, double-click the following script:
•
Microsoft Windows: runTcpmon.bat
•
Linux: runTcpmon.sh
NOTE: By default, the TCP Monitor is listening on port 8081 and forwarding messages to port 8080 (the port number of the DSView software server). SOAP messages can only be viewed if HTTP is used.
9.
Select the XML Format checkbox in the TCP Monitor screen.
10. In the sample Java Client screen, enter 100 at the Enter Selection prompt.
a. Enter http://localhost:8080 to change the protocol, server and port number at the Enter URL Base prompt.
b. Enter the number of the desired menu entry.
c. Enter the responses to other prompts and read the bracketed DSView software server responses.
11. To verify an added event in the sample Java Client screen in the SDE, click the Reports tab and click
Event Log Views - All in the side navigation bar.
NOTE: The TCP Monitor screen contains the SOAP request that corresponds to your request and the
SOAP response from the DSView software server.
To create a keystore:
1.
Run the following script:
•
Microsoft Windows: createkeystore.bat
•
Linux: createkeystore.sh
2.
Press a key after the prompt.
3.
Enter the keystore password when prompted.
NOTE: WebServiceSample.java must be modified to uncomment the lines in the constructor relating to the keystore setup.
C++ Sample Using Axis
The following procedure runs the sample application C++ client, displays SOAP requests and responses and shows the effect in the SDE.
To run the C++ client sample application:
1.
Run the SDE.
2.
In the Microsoft Visual Studio® .NET 2003 development system, open the WebServiceSample.vcproj in the avocent/dssdk/samples/WebService/CPP directory.
3.
From the Build menu, click Build Solution.
4.
From the Debug menu, click Start.
5.
In the TCP Monitor screen, select the XML Format checkbox.
6.
In the sample C++ Client screen:
48
.....
Full Software Development Kit Installer/User Guide a. Enter 100 at the Enter Selection prompt.
b. Enter http://localhost:8080 to change the protocol, server and port number at the Enter URL Base prompt.
c. Enter the number of the desired menu entry.
d. Enter the responses to other prompts and read the bracketed DSView software responses.
7.
To verify an added event in the sample C++ client screen in the SDE, click the Reports tab and click
Event Log Views - All in the side navigation bar.
ดาวน์โหลด
ลิงก์สาธารณะได้รับการอัปเดตแล้ว
ลิงก์สาธารณะไปยังแชทของคุณได้รับการอัปเดตแล้ว You may view and manage your chat links after registration here.
ลิงก์สาธารณะของเอกสาร
โฆษณา
