Setting Up the Environment

Before using the Java SDK, prepare the following software and files:

• Java 8
• A Java IDE, such as IntelliJ IDEA or Eclipse
• sdk-5.1.0.jar from the ZStack ZSphere installation package
• Third-party JAR dependencies of the SDK

Using the SDK

1. Create a Java Maven project.
2. Add the SDK JAR to the project libraries and add the required third-party JARs.
3. Write code by referring to the Java SDK example in the corresponding API topic.
4. Compile and run the project.

Example: Querying VMs

The following example logs in to ZStack ZSphere and queries VMs by using the Java SDK:

import org.zstack.sdk.*;

import java.math.BigInteger;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.io.UnsupportedEncodingException;
import java.util.List;

public class ZSphereSDKDemo {
    public static void main(String[] args) {
        String serverHostname = "MANAGEMENT_NODE_IP";
        String accountName = "ACCOUNT_NAME";
        String password = "ACCOUNT_PASSWORD";

        ZSClient.configure(
                new ZSConfig.Builder()
                        .setHostname(serverHostname)
                        .setPort(8080)
                        .setContextPath("zstack")
                        .build()
        );

        String sessionId = getSessionByLoginAccount(accountName, password);

        QueryVmInstanceAction action = new QueryVmInstanceAction();
        action.sessionId = sessionId;
        QueryVmInstanceAction.Result result = action.call();
        result.throwExceptionIfError();

        List<VmInstanceInventory> vmList = result.value.getInventories();
        System.out.println("Number of VMs: " +
                (vmList != null ? vmList.size() : 0));
    }

    private static String getSessionByLoginAccount(
            String accountName, String password) {
        LogInByAccountAction action = new LogInByAccountAction();
        action.accountName = accountName;
        action.password = encryptToSHA512(password);

        LogInByAccountAction.Result result = action.call();
        result.throwExceptionIfError();
        return result.value.getInventory().getUuid();
    }

    private static String encryptToSHA512(String input) {
        try {
            MessageDigest md = MessageDigest.getInstance("SHA-512");
            md.update(input.getBytes("utf8"));
            BigInteger number = new BigInteger(1, md.digest());
            return String.format("%0128x", number);
        } catch (NoSuchAlgorithmException |
                 UnsupportedEncodingException e) {
            throw new RuntimeException(e);
        }
    }
}

Replace the management node IP address, account name, and password in the example, and then compile and run the code.

Setting Up the Environment

The Python SDK is compatible with Python 2.7. On the management node, run the following command to activate the Python environment used by the ZStack-ZSphere CLI:

source /var/lib/zstack/virtualenv/zstackcli/bin/activate

To use the SDK on another host, copy /var/lib/zstack/virtualenv/zstackcli from the management node to that host. Python 2 must be installed and the host must be able to communicate with the management node.

Specify the management node IP address:

export ZS_SERVER_IP=MANAGEMENT_NODE_IP

Using the SDK

After activating the Python environment and specifying the management node IP address, write code by referring to the Python SDK example in the corresponding API topic.

Example: Querying VMs

The following example logs in to ZStack ZSphere and queries VMs by using the Python SDK:

import hashlib
import os

from apibinding import api
import apibinding.api_actions as api_actions

server_ip = os.environ['ZS_SERVER_IP']
account_name = 'ACCOUNT_NAME'
password = 'ACCOUNT_PASSWORD'


def sync_call(action, session_uuid):
    api_instance = api.Api(host=server_ip, port='8080')
    if session_uuid:
        api_instance.set_session_to_api_message(action, session_uuid)
    name, reply = api_instance.sync_call(action)
    if not reply.success:
        raise api.ApiError(api.error_code_to_string(reply.error))
    return reply


def async_call(action, session_uuid):
    api_instance = api.Api(host=server_ip, port='8080')
    if session_uuid:
        api_instance.set_session_to_api_message(action, session_uuid)
    name, event = api_instance.async_call_wait_for_complete(action)
    if not event.success:
        raise api.ApiError(api.error_code_to_string(event.error))
    return event


login = api_actions.LogInByAccountAction()
login.accountName = account_name
login.password = hashlib.sha512(password).hexdigest()
session_uuid = async_call(login, None).inventory.uuid

query = api_actions.QueryVmInstanceAction()
query.conditions = []
vm_list = sync_call(query, session_uuid).inventories
for vm in vm_list:
    print 'VM found [uuid:%s]' % vm.uuid

logout = api_actions.LogOutAction()
logout.sessionUuid = session_uuid
async_call(logout, session_uuid)

Replace the account name and password in the example, and then run the Python script.