Abstract This guide provides details on getting started with programming using the EMC Smarts Network Configuration Manager API and includes samples and usage details. January 2015 EMC ® Smarts ® Network Configuration Manager Version 9.4 Application Program Interface (API) Programmer’s Guide 302-001-514 Rev 01
25
Embed
Smarts Network Configuration Manager - Data Storage ... · PDF fileusing the EMC Smarts Network Configuration Manager ... Use this guide to determine how to get those first ......
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Transcript
Abstract
This guide provides details on getting started with programming using the EMC Smarts Network Configuration Manager API and includes samples and usage details.
January 2015
EMC® Smarts® Network Configuration Manager Version 9.4
Application Program Interface (API) Programmer’s Guide
302-001-514 Rev 01
2 EMC Smarts Network Configuration Manager 9.4 API Programmer’s Guide
Sample - Creating a Network Using Perl ......................................................................... 21
Sample - Assigning a Device Server to a Network Using Perl ........................................... 22
Sample - Creating an Account Credential Using Perl ....................................................... 23
Sample - Creating a Community String Credential Using Perl .......................................... 24
4 EMC Smarts Network Configuration Manager 9.4 API Programmer’s Guide
Overview The EMC Smarts Network Configuration Manager Application Program Interface (API) Javadoc Reference Guide is the “what”--and, this EMC Smarts Network Configuration Manager Application Program Interface (API) Programmer’s Guide is the “how”.
Use this guide to determine how to get those first few operations completed. After getting a feel for programming with the API, the EMC Smarts Network Configuration Manager Application Program Interface (API) Javadoc Reference Guide will be more easily understood and usable.
There are two API interfaces available. One is a J2EE version, and the other is a Web Services version. Which one you use depends on your specific situation. Both have the same functionality.
The J2EE version requires the client be written in Java.
The Web Services version is required for cross-language support. It allows for Perl, C++, PHP, (and Java) clients to use the API by programming against the WSDL interface. All the code samples listed in this document use the Web Services interface.
Accessing the API Reference Guide (Javadoc) The EMC Smarts Network Configuration Manager Application Program Interface (API) Javadoc Reference Guide and a number of code samples are available online from the Network Configuration Manager server at the following URL. https://SERVER_IP_ADDRESS:8880/Api
Where SERVER_IP_ADDRESS is the IP Address of the machine where the API is installed. https://SERVER_IP_ADDRESS:8880/Api/javadoc
Here is the online EMC Smarts Network Configuration Manager Application Program Interface (API) Javadoc Reference Guide in javadoc format.
5 EMC Smarts Network Configuration Manager 9.4 API Programmer’s Guide
Conventions The functionality in the API follows a number of conventions. When reading the documentation, watch for the following conventions.
For CRUD functions (create, read, update, delete), the functions start with either create, get, update, or delete respectively.
Functions starting with build provide factory methods for creating complex objects. These are not persisted, but are offered as a helper service to the client code.
Data structures end with Info. These represent the domain objects in the system.
Functions that do not follow the above conventions are either providing association between domain objects, or executing some business logic.
ResourceIdentityInfo is the identity object, which contains the unique identifier in the attributed key. This is the object identifier or primary key unique to every object in the system.
The architecture of the API is such that the Web Services interface uses the J2EE interface in the background. The EMC Smarts Network Configuration Manager Application Program Interface (API) Javadoc Reference Guide is a document generated from the J2EE interface, causing some discrepancies between the document and the code generated from Web Services tools, such as Apache Axis.
That is because the Web Services Interface Definition (WSDL) is a translation. All the functions and parameters are the same in the J2EE version and the WSDL version, but the data structures of the parameters may differ slightly.
The WSDL is the interface definition for the web services interface, the javadoc serves to document the functions.
If you are using the Web Services interface, you need to be using the WSDL as the precise definition for each function. The EMC Smarts Network Configuration Manager Application Program Interface (API) Javadoc Reference Guide is still a good reference document if you are using Web Services, but there are some differences between what you see in the guide and the actual implementation of the code.
Collections in the guide are Arrays in Web Services implementations.
In some situations, the order of parameters can change between the WSDL and J2EE interface. The most notable example is with ResourceIdentityInfo. Keep this in mind when programming, and check the generated objects (if applicable) if you suspect this.
The java Date type is translated into a Calendar type for the WSDL interface.
6 EMC Smarts Network Configuration Manager 9.4 API Programmer’s Guide
Finally, a note about LDAP-style name lookups. In the documentation, the name lookup capability is detailed. Unfortunately, this is expensive. Some of the name lookups have been removed for performance reasons.
As a best practice, these lookup-style calls should only be used as an entry point to the API, before any internal Ids (OIDs or keys in the Resource Identity Info objects) have been obtained. Once the programmer has an entry point into the system, OIDs should always be used for API calls.
For best practices, keep in mind the load being put on the Network Configuration Manager system. Remember that a program can interact much faster with the application than users can. High volume traffic through the API can simulate many concurrent users of the system.
Note the following when making decisions concerning multi-threading a client program:
Technically, this is entirely possible, but is it a good thing to do from a system perspective?
You might also consider running high volume operations against the API when there are a minimum of users on the system.
Installing the API The Application Program Interface (API) is installed with the application by default.
API versions are named by the minor version number, and indicated stable API signatures for the duration of that version. For example, the 9.x API is the programmatic interface starting with version 9.x. The signatures present at that release remain unchanged throughout the life of the 9.x API. Additional signatures, if added during the 9.x.y release, remain stable during the lifetime of the 9.x API.
Backward compatibility with Version 4.x is not supported. Also, two different versions of an API in a release is not supported.
Getting Started
Accessing Network Configuration Manager API
There are two manifestations of the API available. One is a J2EE version, and one is a Web Services version. Which one you use depends on your specific situation. Both have the same functionality, but certain usage scenarios tend to lend themselves better to using one over the other.
NCM Public API Secure Connection
For successfully establishing a secure connection with the Network Configuration Manager server and to use the public API, do the following:
7 EMC Smarts Network Configuration Manager 9.4 API Programmer’s Guide
1. Access the API using https and port 8880.
2. Export the selfsigned certificate from [ProductDirectory]/conf/voyence-ssl.keystore to a file (for example, Linux server command), run:
3. Click Enter on receiving a prompt for the password.
4. Copy the exported certificate file to the client machine.
5. Import the server certificate into the client running the API client code. For example, while running a java client code, the certificate needs to be imported into the jdk using the following command on a Windows client:
6. Enter the following password after receiving a prompt: changeit
This is the default password, unless otherwise modified.
7. Type Yes on receiving a prompt, “Trust the certificate”.
Samples
The most valuable part of the documentation set to programmers is the extensive set of samples and example code provided. You can access these samples at the following location on machine where NCM is installed:
[ProductDirectory]/ncmcore/webapps/Api/samples
Download the samples directory to have all the example code on your local system.
8 EMC Smarts Network Configuration Manager 9.4 API Programmer’s Guide
Using the J2EE Interface
The J2EE interface is a service, or bean, called ApiService. The functions available on the API are all available through this service.
A handle to the bean is obtained in Spring Application context lookup. Some other parameters are required. See the samples provided for an example of these settings. Each sample is standalone, and has the settings to obtain a handle to the service. Many of the samples have assumptions about data, so it is important you read the code and understand your server environment (data you have available to you).
You have to change the IP address, user name, and password in the sample before you can run them against your server.
Accessing the J2EE Interface
To access the Java interface, download/get the J2EE folder from the server. This folder is located at the following location:
[ProductDirectory]/ncmcore/webapps/Api/samples/J2EE in the deploy folder of your NCM installation.
The following table lists the jar files that must be in your client’s CLASSPATH for your Java client application to work properly. As a convenience, all the required jar files, and a sample build file in the samples directory have been included.
This document has been written from the perspective of using the Web Services Interface. As this section indicates, there is also a J2EE interface that can be used.
The examples in this guide are using Java derived from the Web Services Interface. The EMC Smarts Network Configuration Manager Application Program Interface (API) Javadoc Reference Guide, however, has been generated from the J2EE interface. The functions in the J2EE interface and Web Services Interface are the same.
Occasionally, some parameters have been changed. Usually, it is a collection being expressed as an array. The most notable example is that of the parameter order of the ResourceIdentityInfo.
This section details how to use the Web Services Interface.
11 EMC Smarts Network Configuration Manager 9.4 API Programmer’s Guide
Obtaining the Interface Definition
There are two methods to obtain the WSDL document, which is the interface definition:
Method 1 – Obtain from the URL
You can get the WSDL document through the browser. However, getting the document through the browser actually generates the WSDL, and the namespace contains the URL used to obtain the document. This may not be desirable. For example, the package names of generated Java code then contain the URL where you obtained the interface definition.
Now that you have the WSDL document, it is up to you how you use it. As a Web Services programmer, you can choose whatever library or toolkit you desire. From there, you can compile it to any supported language, or you may already have a product that can consume it directly.
Check Section “Generating Client-side Stubs using Axis 1.3 or Higher” on page 40 for more information.
API Naming Network Configuration Manager resources are identified and named through an object identifier. This identifier, referred to as an Object Identifier (OID), uniquely identifies a resource within the Network Configuration Manager system. Using the OID, programmers can directly lookup a Network Configuration Manager resource.
Network Configuration Manager resources also have human-readable names. Most of these names do not have uniqueness constraints within the Network Configuration Manager system (the notable exception is network names; two networks cannot have the same name within the Network Configuration Manager system).
For example, a Network Configuration Manager device can have the same name. However, two devices under a given network cannot have the same name.
12 EMC Smarts Network Configuration Manager 9.4 API Programmer’s Guide
The Network Configuration Manager API provides lookup by OID for all the domain objects. Along with this, it also provides a mechanism to lookup by name for primary domain objects like Network, Operational Device, Folder, Site, and Job. Network Configuration Manager recommends avoiding lookups by name for performance reasons. Try to retrieve the object by name once, and cache the OID for subsequent calls.
If a programmer supplies both the resource OID and the resource name, then the OID is used. Otherwise, the name is used.
Lookup By OID
The following is an example to lookup a domain object by OID. // Look up device R1230-5 in network SOUTHWEST-REGION by OID
// R1230-5's OID is c0a857081bf8e93fe3d5e46b00010000
// SOUTHWEST-REGION is c0a857080d6bb23ffbfa048200010000
ResourceIdentityInfo networkId =
new ResourceIdentityInfo(
"c0a857080d6bb23ffbfa048200010000",
null,
"network");
ResourceIdentityInfo deviceId =
new ResourceIdentityInfo(
"c0a857081bf8e93fe3d5e46b00010000",
null, "device");
OperationalDeviceInfo info =
api.getOperationalDeviceInfo(networkId, deviceId,
false);
Lookup By Name
The following is an example to lookup a domain object by Name. ResourceIdentityInfo networkId =
new ResourceIdentityInfo(
null,
"SOUTHWEST-REGION",
"network");
ResourceIdentityInfo deviceId =
new ResourceIdentityInfo(
null,
"R1230-5",
13 EMC Smarts Network Configuration Manager 9.4 API Programmer’s Guide
"device");
OperationalDeviceInfo info = api.getOperationalDeviceInfo(networkId,
deviceId, false);
Composite Names
Most of the Network Configuration Manager resources do not exist in a hierarchical fashion, or have only a single level of hierarchy. For example, Network Configuration Manager Workspaces exist directly under Network Configuration Manager Networks.
The notable exception to the hierarchy rule is Network Configuration Manager Sites and Folders. Sites and folders can have an arbitrary tree-like structure. To support this hierarchy at the API level, the notion of a composite name is introduced (the remainder of this section uses sites to illustrate composite name concepts).
A composite name is an array of ResourceIdentityInfo objects. Each element of the array specifies the particular Network Configuration Manager resource that comprises a full, hierarchical name. This approach allows for an arbitrary number of levels.
The following is an example of a composite name. following is a graphical representation of a Network Configuration Manager Network, and several sites/sub-sites contained under the network. Note the name and unique key is shown at each level. Networks
o Southwest-Region (key: C0A8572F3468993F953401C7FC000000)
|____ o Sites
|_____ o Austin (key: C0A8572F40BFE83FA73801C7FC000000)
| |_____ o 100 Congress (key: C0A8572F40EFB981A73801C7FC000000)
|_____ o Santa Fe (key: C0A8572F40BEF38FA73801C7FC000000)
The Santa Fe Site under the Southwest-Region network would be represented as a composite name by a two-element array of ResourceIdentityInfo objects. The ResourceIdentityInfo object at index 0 of the array would have the following values: ResourceIdentityInfo.resourceKey = "C0A8572F3468993F953401C7FC000000"
The ResourceIdentityInfo object at index 1 of the array would have the following values: ResourceIdentityInfo.resourceKey = "C0A8572F40BEF38FA73801C7FC000000"
ResourceIdentityInfo.resourceType = "site"
ResourceIdentityInfo.resourceName = "Santa Fe"
14 EMC Smarts Network Configuration Manager 9.4 API Programmer’s Guide
The following is a pseudo-code representation of the previous example: . . .
ResourceIdentityInfo [] compositeName = new ResourceIdentityInfo(2);
compositeName[0] =
new ResourceIdentityInfo(
"C0A8572F3468993F953401C7FC000000",
"Southwest-Region",
"network");
compositeName[1] =
new ResourceIdentityInfo(
"C0A8572F40BEF38FA73801C7FC000000",
"Santa Fe",
"site");
To represent the 100 Congress child Site of the top level Austin Site, under the Southwest-Region network, a three-element array of ResourceIdentityInfo objects would be needed. The following pseudo-code illustrates this: ResourceIdentityInfo [] compositeName = new ResourceIdentityInfo(3);
compositeName[0] =
new ResourceIdentityInfo(
"C0A8572F3468993F953401C7FC000000",
"Southwest-Region",
"network");
compositeName[1] =
new ResourceIdentityInfo(
"C0A8572F40BFE83FA73801C7FC000000",
"Austin",
"site");
compositeName[2] =
new ResourceIdentityInfo(
"C0A8572F40EFB981A73801C7FC000000",
"100 Congress",
"site");
In addition to those methods that deal with Sites and Folders, certain job-related methods require a composite name as a parameter.
15 EMC Smarts Network Configuration Manager 9.4 API Programmer’s Guide
Best Practices
Following are the best practices you should follow for optimal performance.
Use OIDs wherever possible. Using the LDAP method of lookup using Resource Names affects performance.
On getXXXXInfo() calls, use fullDataSet option only when necessary. Passing a value of true for fullDataSet argument retrieves all the associations, and affects performance.
API Usage
API Usage in JAVA
This section details the API usage in JAVA.
Using the J2EE Interface
The following are the general steps a typical client would complete after downloading the required jar files to access the API using the J2EE interface. Samples and examples in this section provide working illustrations of these concepts.
Prepare the Server Variable, UserName and Password
The following variables needs to be set in config.properties file present at the following location: [ProductDirectory]/ncmcore/webapps/Api/samples/J2EE/conf
#Replace the <server-ip> with the actual IP Address of the NCM server.
After completing the steps of obtaining the WSDL document, you will be generating the client-side stubs and compiling them. The following are general steps for using the API.
Get a handle to ApiService using the Service Locator class ApiServiceSoapBindingStub api;
try {
ApiServiceServiceLocator locator = new ApiServiceServiceLocator();
// Use the line below to change the Service EndPoint
address.
// Replace 192.168.24.213 with the IP address of the
voyence control
17 EMC Smarts Network Configuration Manager 9.4 API Programmer’s Guide
Samples All the Java Samples listed in this section use the Web Services interface. Download the J2EE Samples from: https://<serverip>:8880/api
There are many samples in the location specified above. These samples are the most effective way to get started with programming against the API. Even though you may be programming against the J2EE interface, the Web Services examples may also help to illustrate usage scenarios, or vice versa. The samples in the different directories are not the same, so do not hesitate to look in more than one place for example usage.
The recommended access to the API is through Web Services, using object-oriented clients that have tool support for WSDL. For example, good choices would be Java using Apache axis orOR c#.
21 EMC Smarts Network Configuration Manager 9.4 API Programmer’s Guide
Perl users will have to construct the SOAP calls directly. The Perl examples have been left in this document because there is no online sample Perl code at this time, however, the J2EE, Web Services, and PHP examples are now online.
Perl is not the recommended choice for complex integrations, because the SOAP calls must be constructed manually, and the data structures make this a difficult task. Use higher-level languages for complex integrations.
Sample - Creating a Network Using Perl # Create a new Network "TestNetwork” using Voyence API.
# Refer to API Usage section for how to
# create an instance of SOAP::Lite
# ie $soap_client = new SOAP::Lite ....
# create a network RII object for new net
$new_net_rii = {
resourceName => 'TestNetwork',
resourceType => 'NETWORK',
resourceKey => undef};
bless $new_net_rii, 'ResourceIdentityInfo';
#create a NetworkInfo object and insert netRII in it