• Java开发工具（Intellij IDEA）

  根据自己使用习惯，下载并安装合适的Java开发工具，并完成初始化工作。例如：Intellij IDEA、Eclipse等，本文以Intellij IDEA为例进行介绍。

• Java JDK工具

  提前安装Java JDK工具，推荐使用Java 8版本Java JDK工具。

• ZStack Cloud Java SDK依赖jar包
  使用ZStack Cloud SDK前，需要提前获取Java SDK jar文件，该文件存放在ZStack Cloud安装包中：

  • ZStack Cloud安装包：
    • 软件名称：ZStack-Cloud-installer-5.2.0.bin
    • 下载地址：点击这里
  • Java SDK依赖包
    • 文件名称：sdk-5.2.0.jar
    • 存放路径：/usr/local/zstack/apache-tomcat/webapps/zstack/WEB-INF/lib/sdk-5.2.0.jar
• SDK依赖的第三方jar：
  依赖jar包内容详情如下：

  <dependencies>     <dependency>         <groupId>org.zstack</groupId>         <artifactId>sdk</artifactId>         <version>3.4.0</version>     </dependency>     <dependency>         <groupId>com.squareup.okhttp3</groupId>         <artifactId>okhttp</artifactId>         <version>3.5.0</version>     </dependency>     <dependency>         <groupId>com.google.code.gson</groupId>         <artifactId>gson</artifactId>         <version>2.1</version>     </dependency>     <dependency>         <groupId>commons-beanutils</groupId>         <artifactId>commons-beanutils</artifactId>         <version>1.9.3</version>     </dependency>     <dependency>         <groupId>javax.servlet</groupId>         <artifactId>servlet-api</artifactId>         <version>2.5</version>         <scope>provided</scope>     </dependency>     <dependency>         <groupId>commons-codec</groupId>         <artifactId>commons-codec</artifactId>         <version>1.9</version>     </dependency> </dependencies>

1. 准备ZStack Cloud环境，支持以下两种方式：
   • 直接安装ZStack Cloud环境至待用作管理节点的主机。
     • ZStack Cloud安装包：
       • 软件名称：ZStack-Cloud-installer-5.2.0.bin
       • 下载地址：点击这里
   • 使用本机新建一个虚拟临时环境目录，例如/var/lib/virtualenv，并执行以下命令拷贝已有ZStack Cloud环境目录 /var/lib/zstack/virtualenv/zstackcli 到本机新建的虚拟临时环境目录下：

     scp -r /var/lib/zstack/virtualenv/zstackcli $LocalHostIP:$VirtualDirectory //LocalHostIP为本机IP地址，VirtualDirectory为虚拟临时环境目录

     说明: 请确保本机与管理节点网络互通，且已安装Python2环境。
2. 启用ZStack-CloudCLI命令行工具，以调用Python SDK。
   • 若使用管理节点，执行以下命令启用：

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

   • 若使用本机，执行以下命令启用：

     source $VirtualDirectory/zstackcli/bin/activate //VirtualDirectory为虚拟临时环境目录

3. 执行以下命令指定管理节点IP地址：
   • 若使用管理节点，执行以下命令指定：

     export ZS_SERVER_IP=127.0.0.1

   • 若使用本机，执行以下命令指定：

     export ZS_SERVER_IP=MN_IP //MN_IP为管理节点IP地址

1. 在IDEA新建一个JAVA Maven项目，如图 1所示：

   
   
   

2. 添加SDK jar包到项目Libraires，并把依赖的三方包声明加到项目pom.xml文件里，如图 2所示：

   
   
   

3. 参考ZStack Cloud开发手册提供的SDK示例，实现调用API功能。

• Python形式调用API无需上述依赖准备，可直接参考SDK示例调用即可。

package org.zstack;   import org.zstack.sdk.*; import java.math.BigInteger; import java.security.MessageDigest; import java.security.NoSuchAlgorithmException; import java.util.List; import java.io.UnsupportedEncodingException;   /**  * 演示如何用Java SDK 查询VM列表  */ public class CloudSDKDemo {     public static void main(String[] args) {         String cloudServerHostname = "请输入管理节点IP地址";         String accountName = "请输入账号";         String password = "请输入账号密码";           ZSClient.configure(                 new ZSConfig.Builder()                         .setHostname(cloudServerHostname)                         .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(String.format("查询云主机列表成功，查询到%s台云主机",                 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();         System.out.println("登录成功");         return result.value.getInventory().getUuid();     }       private static String encryptToSHA512(String input) {         try {             MessageDigest md = MessageDigest.getInstance("SHA-512");             md.reset();             md.update(input.getBytes("utf8"));             BigInteger bigInteger = new BigInteger(1, md.digest());             return String.format("%0128x", bigInteger);         } catch (NoSuchAlgorithmException | UnsupportedEncodingException e) {             throw new RuntimeException(e);         }     }   }

1. 代码中，以下部分需要在对应位置，填写正确的管理节点IP、账号和密码信息。

   public static void main(String[] args) { String cloudServerHostname = "请输入管理节点IP地址"; String accountName = "请输入账号"; String password = "请输入账号密码"; ZSClient.configure(          new ZSConfig.Builder()                  .setHostname(cloudServerHostname)                  .setPort(8080)                  .setContextPath("zstack")                  .build() );

2. 代码中，以下部分为所调用API的SDK信息，调用不同API需要填写对应的SDK信息，可参考开发手册。

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

3. 代码编写完成后，编译、运行即可。

import time import os import sys import traceback import hashlib  import zstacklib.utils.log as log  # comment out next line to print detail zstack cli http command to screen. log.configure_log('/var/log/zstack/zstack-sdk.log', log_to_console=False)  import apibinding.api_actions as api_actions from apibinding import api import xml.etree.cElementTree as etree import apibinding.inventory as inventory  zstack_server_ip = os.environ['ZS_SERVER_IP'] # 请按需设置登录云平台的账户/用户名 user_name = 'admin' # 请按需设置登录云平台的密码 user_password = 'password' # 请指定云主机所在物理机的UUID host_uuid = 'acb492ce8cd640c8bb73bae75ea00adf'   # Must keep. def sync_call(apiCmd, session_uuid):     api_instance = api.Api(host=zstack_server_ip, port='8080')     if session_uuid:         api_instance.set_session_to_api_message(apiCmd, session_uuid)     (name, reply) = api_instance.sync_call(apiCmd, )     if not reply.success: raise api.ApiError("Sync call at %s: [%s] meets error: %s." % (         zstack_server_ip, apiCmd.__class__.__name__, api.error_code_to_string(reply.error)))     # print("[Sync call at %s]: [%s] Success" % (zstack_server_ip, apiCmd.__class__.__name__))     return reply   # Must keep. def async_call(apiCmd, session_uuid):     api_instance = api.Api(host=zstack_server_ip, port='8080')     api_instance.set_session_to_api_message(apiCmd, session_uuid)     (name, event) = api_instance.async_call_wait_for_complete(apiCmd)     time.sleep(1)     if not event.success: raise api.ApiError("Async call at %s: [%s] meets error: %s." % (         zstack_server_ip, apiCmd.__class__.__name__, api.error_code_to_string(reply.error)))     # print("[Async call at %s]: [%s] Success" % (zstack_server_ip, apiCmd.__class__.__name__))     return event   # Must keep. def login_as_admin():     accountName = user_name     password = user_password     return login_by_account(accountName, password)   # Must keep. #tag::login_by_account[] def login_by_account(name, password, timeout=60000):     login = api_actions.LogInByAccountAction()     login.accountName = name     # Login API will use encrypted password string.     login.password = hashlib.sha512(password).hexdigest()     login.timeout = timeout     session_uuid = async_call(login, None).inventory.uuid     return session_uuid #end::login_by_account[]   # logout must be called after session isn't needed. # Must keep. #tag::logout[] def logout(session_uuid):     logout = api_actions.LogOutAction()     logout.timeout = 60000     logout.sessionUuid = session_uuid     async_call(logout, session_uuid) #end::logout[]   # Must keep. def execute_action_with_session(action, session_uuid, async=True):     if session_uuid:         action.sessionUuid = session_uuid         if async:             evt = async_call(action, session_uuid)         else:             evt = sync_call(action, session_uuid)     else:         session_uuid = login_as_admin()         try:             action.sessionUuid = session_uuid             if async:                 evt = async_call(action, session_uuid)             else:                 evt = sync_call(action, session_uuid)         except Exception as e:             traceback.print_exc(file=sys.stdout)             raise e         finally:             # New login must be logout. If the active login session             # exceed the limit, no account login is allowed.             # The default active logined session limit is  500.             logout(session_uuid)      return evt   # All Query API need conditions. This help to generate common conditions. # The op including: =, >, <, in, not in, like etc. def gen_query_conditions(name, op, value, conditions=[]):     new_conditions = [{'name': name, 'op': op, 'value': value}]     new_conditions.extend(conditions)     return new_conditions   #tag::query_zone[] def query_zone(conditions=[], session_uuid=None):     action = api_actions.QueryZoneAction()     action.timeout = 3000     action.conditions = conditions     evt = execute_action_with_session(action, session_uuid)     print 'Zone infomation: %s ' % evt.inventories     return evt.inventories #end::query_zone[]   def query_vm_by_host(host_uuid, conditions=[], session_uuid=None):     action = api_actions.QueryVmInstanceAction()     action.conditions = gen_query_conditions('hostUuid', '=', host_uuid, conditions)     evt = execute_action_with_session(action, session_uuid)     return evt.inventories   if __name__ == '__main__':     session_uuid = login_as_admin()     vm_list = query_vm_by_host(host_uuid, session_uuid=session_uuid)     for vm in vm_list:         print '查询到的云主机[uuid:%s]\n' % vm.uuid     logout(session_uuid)

1. 在以上代码示例中，设置登录云平台的账户/用户名、密码、以及云主机所在物理机的UUID。
2. 执行python $代码示例文件全路径命令查询云主机。

• 在调用ZStack Cloud API之前，需要确保已获取一个登陆Session的UUID。Session使用完毕后 , 需调用对应的logout API退出Session。
  说明: 系统已预设登录Session的阈值，默认为500。若在短时间内大量调用登陆API且不退出登陆 , 达到阈值后会导致无法登陆新的Session。
• 登录ZStack Cloud对应的API代码：

  def login_by_account(name, password, timeout=60000):     login = api_actions.LogInByAccountAction()     login.accountName = name     # Login API will use encrypted password string.     login.password = hashlib.sha512(password).hexdigest()     login.timeout = timeout     session_uuid = async_call(login, None).inventory.uuid     return session_uuid

  说明: 登陆API使用的秘钥为经过sha512加密过的密文。
• 登出ZStack Cloud对应的API代码：

  def logout(session_uuid):     logout = api_actions.LogOutAction()     logout.timeout = 60000     logout.sessionUuid = session_uuid     async_call(logout, session_uuid)

• 查询云主机对应的API代码：

  def query_zone(conditions=[], session_uuid=None):     action = api_actions.QueryZoneAction()     action.timeout = 3000     action.conditions = conditions     evt = execute_action_with_session(action, session_uuid)     print 'Zone infomation: %s ' % evt.inventories     return evt.inventories

• 登录/登出/查询类API参数和返回值解析：
  • session_uuid 为可传入的参数 , 支持用户复用已登陆的 Session。
  • execute_action_with_session 函数是一个封装过的 API, 可以帮助执行所有ZStack Cloud的函数 , 若不传入 session_uuid , 该函数可确保执行 API 前后完成系统的登入和登出。因此建议用户使用该函数完成 API 调用。
  • 所有查询类API均需通过action.conditions参数设置数组结构的查询条件，例如action.conditions = ["name=TestZone","state=Enabled"]。若希望获取全部资源信息 , 可将参数设置为空数组。详细可参考查询 API。

  • API的返回值表示API的执行结果，例如 查询类API返回值为evt.inventories，为数组类型。 用户可以使用count获取该数组的大小 , 并使用python数组的使用方式完成数据调用。对于大部分非查询类API，ZStack Cloud返回对象类型数据 , 例如创建云主机 (CreateVmInstanceAction), 返回值为evt.inventory。详细可参考API使用规范。