基于 IBM Active Energy Manager 的 REST 应用程序编程

用 REST 编写您的第一个动态能源管理应用程序

您已经厌烦等待 GUI 显示能源数据了吗?希望在任何地方,甚至是远程位置快速访问数据吗?只需具备一些基本的 Java™ 编程技能并花些时间,就可以利用 IBM Active Energy Manager REST API 的强大功能。本文首先介绍一些 REST 基本知识,然后开发一个用来访问和报告电力使用量指标的 AEM REST 程序。

Paul Sonnenberg, 软件工程师, IBM

Paul Sonnenberg 是一位有 30 多年经验的软件测试专家,测试过许多产品。最近,他负责 Active Energy Manager Release 4.2 的 REST API 的系统检验测试。



2011 年 2 月 17 日

概述

IBM Systems Director Active Energy Manager (AEM) 这个工具用于监视和管理数据中心中的系统和设施的电力使用量和热量。IBM Systems Director 中包含 AEM,也可以作为 IBM Systems Director 的插件使用。REST 应用程序编程接口是这两个产品新增的特性。IBM Systems Director 6.1.2 和 AEM 4.2 版包含这些 API;这两个版本都是在 2009 年 12 月发布的。本文将带领您体验我作为产品测试员的经历:首先理解 REST 和 RESTful 编程的基本概念,然后编写一个简单的程序,最后开发一个比较复杂的 AEM 应用程序。读者只需要基本了解 Java 编程和超文本传输协议 (HTTP)。

理解 REST 和 RESTful 编程

我的第一个任务是了解 REST。在网上做了一番研究并与同事们讨论之后,我总结出以下基本知识:REST (Representation State Transfer) 是 Roy Fielding 在 2000 年的博士论文中提出的概念。在本质上,它是一种 web 服务类型。它是指一种无状态的客户机/服务器架构,在这种架构中 web 服务被看作资源,资源可以由 Uniform Resource Identifier (URI) 标识。这些服务只限于标准的 GET、POST、PUT 和 DELETE HTTP 方法。采用这种架构开发的软件就是 RESTful (REST 式)的。

REST API 的基本形式是可以执行单一操作的 URI。对于 AEM,有用于获取能源指标和设置能源管理功能的 URI。例如,URI /IBM/director/rest/resources/PowerOutletGroup 返回一个包含电源插座组列表的资源。

  • 资源:可以通过 URI 寻址的对象或操作。
  • JSON (Java Script Object Notation):所有 AEM 资源采用的格式。这是一种轻量的交换格式,人和软件都可以方便地读写这种格式。

REST API 独立于编程语言。只要有 HTTP 客户机库,就可以从用任何语言编写的程序访问它们,包括 Java、Python、Perl 等等。我主要使用 Java,这是因为它是我最熟悉的语言。可以在 IBM Systems Director Software Development Kit (SD) 的信息中心找到这些 API 的详细信息。除了全面详细的语法信息之外,还有示例部分,其中包含许多有用的 Java 方法。我使用 REST Utilities.java 类中的方法获取响应字符串和执行日志记录。

网上有许多关于 REST 的文章,我强烈推荐其中一篇(由于其简单性和创造性),即 Ryan Tamiko 在 2004 年撰写的 “How I explained REST to my wife”(见 参考资料)。

REST 客户机 —— 一个简单的应用程序

对 REST 概念有了基本认识之后,我的下一个任务是了解如何在 Java 编程中运用这些知识。适合我的方法是找一个相当简单的应用程序,以它为基础构建程序。

对于此任务,我选择了 Agile commons.org 网站提供的 REST 客户机应用程序。我做了几个用以处理 Secure Socket Layer (SSL) 证书和解析 JSON 格式的资源的修改,在几天内就完成了一个简单的 Java 应用程序。

与 Perl 或 Python 相比,在这个环境中使用 Java 的缺点之一是,如果要在 Systems Director 服务器所在的系统之外的远程系统上运行,首先需要把 SSL 证书导入本地信任存储,以便使用 SSL 保护 HTTP 连接。IBM 信息中心提供获取证书的详细步骤。

对 REST 客户机所做的涉及 SSL 的修改包括添加几行代码以输入信任存储安全证书的位置和密码,然后设置适当的安全属性:

清单 1. 设置 SSL 安全的示例代码
...
System.setProperty("javax.net.ssl.trustStore", certfile);
System.setProperty("javax.net.ssl.trustStorePassword", certpass);
...

解析 JSON 格式的资源需要包含 JSON 库。我从 JSON.org Java 网站下载了 Java 和 HTML 源代码文件,运行以下命令创建库文件 JSON.jar。

javac C:/dz/json/*.java 
jar -cvf C:/$user/libs/json.jar C:/dz/json/*.class

编写解析 JSON 的代码很容易。JSON 库提供用来解析、选择和更新 JSON 资源的全套方法,很容易把它们合并到通用应用程序中。在学习过程中,我在 REST 客户机中添加了以下代码段。这段代码根据 GET 调用产生的字符串数据创建一个 JSON 对象。然后,我输出此对象以查看原始数据。最后,通过检查此对象是否包含冷却率乘数测试解析过程。如果包含冷却率乘数,就输出它的值。

清单 2. 解析 JSON 对象的示例代码
try {
	JSONObject jsonResponse = new JSONObject(result); 
	System.out.println("jsonResponse " + jsonResponse);
	
	  if (jsonResponse.has("CoolingRateMultiplier")) {
	  String coolingRate = jsonResponse.getString("CoolingRateMultiplier");
	  System.out.println("");
	  System.out.println("cooling rate " + coolingRate);
	  }
	} 
   catch (JSONException e) {
	RESTUtilities.log(Level.SEVERE, logger, CLASSNAME, "main", 
	"FAIL: Exception occurred parsing JSON object.", e); }
	...

只要客户机系统能够通过网络连接 Director 服务器,就可以从命令行调用 REST 客户机。

对于 get 和 delete:

java -jar restclient.jar [-quiet] user pass certfile certpass GET/DELETE url

对于 put 和 post,要作为请求体发送一个文件的内容:

java -jar restclient.jar [-quiet] user pass certfile certpass PUT/POST url filename
表 1. REST 客户机执行选项
选项说明
Quiet这个可选参数指定只输出响应体,如果没有这个参数,在输出中会包含响应头和时间信息。
UserSystems Director 用户 ID。
PassSystems Director 用户密码。
Cert file包含密钥存储证书的文件。从 Systems Director 服务器获取此文件。
Cert pass证书文件的密码。
URIURI。
Filename包含 JSON 格式的字符串的文件,用于 put 或 post 请求。

用法示例:输入

java -jar restclient.jar -quiet root eserve1a C:\\dz\\security\\mycerts ibmpassw0rd 
GET https://pla1098:8422/ibm/director/rest/energysettings

用法示例:输出

jsonResponse 
{"MeteringActive":true,"MeteringInterval":5,"DefaultVoltage":220,"ThermalUnit":"CELSIUS",
"CoolingRateMultiplier":1.5,"PowerFactor":0.707,"PriceKWh":0,"PromptUser":true,
"uri":"/ibm/director/rest/energysettings","CurrencyType":"USD","PowerUnit":"WATTS",
"GUIRefreshInterval":1,"RetainDataDuration":365}

cooling rate 1.5"

总之,这个简单的应用程序使用来自命令行和本地文件的输入执行所有基本的 REST 服务(GET、POST、PUT 和 DELETE)。它是开发更复杂的应用程序的基础。

用 Firefox web 浏览器研究 REST API

在讨论下一个应用程序之前,我想先谈谈一种可以大大简化 RESTful 编程的简便工具。REST 的出色特性之一是可以通过包括 web 浏览器在内的多种方法使用 API。我发现带 JSONView 附加件的 Firefox web 浏览器(3.5.8 版)是很有用的应用程序开发工具(见 参考资料)。

打开 Firefox web 浏览器并输入 URI。在第一次这么做时,会提示输入您的 Systems Director 用户 ID 和密码。浏览器中显示的结果与 XML 文档相似。资源已经格式化并突出显示,可以把数组和对象收拢。

图 1. 对 AEM 支持的资源组的 REST 请求产生的格式化 JSON 输出示例
对 AEM 支持的资源组的 REST 请求产生的格式化 JSON 输出示例

根本不需要编写任何代码,就能够看到 URI 产生的资源,这真的很不错。我在编写下一个应用程序时经常使用这种方法,这节省了大量时间。

AEMpwrReport(AEM 电力报告)应用程序

AEMpwrReport 是一个比较复杂的应用程序,客户可以考虑通过编写这样的应用程序从 AEM 提取有用的数据。它在指定的持续时间内以一定的时间间隔用 REST API 轮询 Director 服务器,收集 AEM 监视的所有端点的电力输入数据。在结束运行之前,它输出各个端点的聚合数据以及监视的所有端点的汇总信息。用户可以控制轮询时间间隔和执行持续时间。用户还可以通过跟踪机制查看返回电力数据的每个调用的结果。

从 REST 的角度来看,这个应用程序相当简单。它由对以下 URI 的单一调用组成,这个调用产生包含 AEM 监视的所有端点的所有电力输入数据的单一资源。

…:8422/ibm/director/rest/groups/AEM_SUPPORTED_RESOURCES_GROUP/monitors/
[com.ibm.aem.console.base.AEMMetricProviderID][inputPower]/monitordata

难点在于决定什么时候获取电力数据以及轮询的频率。理想的解决方案是等待 JAMS 消息或者查询某个表示有更新的电力数据可用的标志,然后再执行 GET。糟糕的是,API 的最初版本不提供此功能。原来的解决方案是在每个 GET 检查所有端点之后以可由用户指定的时间间隔执行 GET。检查电力输入的状态标志是否设置为 "Valid",如果是的话,检查自从上一次更新以来时间戳是否更新过。

下面的代码说明如何解析 JSON 资源并执行必要的检查:

清单 3. 监视电力数据的示例代码
...
try {  
 JSONObject jsonResponse = new JSONObject(result); 
 JSONArray jsonarr = jsonResponse.getJSONArray(MONITORDATA);
 	index = 0;
 	int length = jsonarr.length();
  	
  // for each JSON object within the array represents an AEM monitored endpoint 
 	for (int  = 0; i  < length; i++)
    {
    JSONObject aemmetric = jsonarr.getJSONObject(i);
    //"Valid" status indicates that the object contains valid 
    // or current input power data 
   	if (aemmetric.has(STATUS) & aemmetric.getString(STATUS).equals(VALID))
      { 
        ...
       pwr.timestamp.set(index,aemmetric.getString(TIMESTAMP));
       pwr.DisplayName.set(index,aemmetric.getString(DISPLAYNAME));
       
      // check to see if new input data is available. 
      // Prior_timestamp is used to store the last time new data 
      // was available.  The first time it needs to be initialized to an empty string.  
      // Check to see if the current timestamp is newer than the prior one, 
      // if it is process new data.
      if (pwr.prior_timestamp.get(index) == null) pwr.prior_timestamp.set(index,""); 
      if(pwr.timestamp.get(index).compareTo(pwr.prior_timestamp.get(index)) !=0)
        {
      	...

用法:

Java –jar aem_pwr_report.jar [-quiet] server user pswd certfile certpswd 
duration delay tracing [tracefile]
表 2. AEMpwrReport 执行选项
选项说明
Quiet这个可选参数指定只输出响应体,如果没有这个参数,在输出中会包含响应头和时间信息。
UserSystems Director 用户 ID。
PassSystems Director 用户密码。
Cert file包含密钥存储证书的文件。从 Systems Director 服务器获取此文件。
Cert pass证书文件的密码。
Duration以小时为单位的运行持续时间。最小值为 1 小时。
Delay以秒为单位的轮询新输入数据的时间间隔。
Tracingtrue 或 false —— 设置为 true 时,收集所有电力输入数据和时间戳数据,这些数据保存在指定的跟踪文件中。
Trace file用于存储跟踪数据的输出文件。

用法示例:输入

Java –jar aem_pwr_report.jar pla1079.pdl.pok.ibm.com root eserve1a 
C:\\dz\\security\\mycerts ibmpassw0rd 1 0 true C:\\dz\\aem\\4.2\\AEMpwrReport.trace

用法示例:输出

  1. 如果没有指定 quiet 标志,会产生下面的标准输出,在默认情况下输出显示在屏幕上:
    Power Report Application Started at: Wed Dec 09 14:38:50 EST 2009 Running for 
    1 hrs collecting data from Director Server: pla1079.pdl.pok.ibm.com 
    Monitoring 81 end points
    ******************************************************************
    
    HTTP Return Code 200
    ****** Time required to process All 81 Objects 1657 ms Average processing 
    time 1657 ms *******
    current timestamp 2009-12-09 14:38:52.453
    target timestamp 2009-12-09 15:38:50.796
    
    HTTP Return Code 200
    ****** Time required to process All 81 Objects 1265 ms Average processing 
    time 1461 ms *******
    current timestamp 2009-12-09 14:38:53.718
    target timestamp 2009-12-09 15:38:50.796
    ...

    完成每个 HTTP GET 请求之后,程序会继续输出消息并处理产生的数据。

    下面是应用程序完成之后显示的消息示例。注意,即使指定了 –quiet,也会出现这些消息。

    ******************************************************** 
    Completed at: Mon Dec 07 17:57:48 CST 2009
    
    The following 22 end points reported input power
    OID 4131 Name IBM MtVM 01v Q000109
    OID 4131 Total and Average Input power 16724.09/176.04 in WATTS
    OID 4131 Number of inputs 95
    
    OID 4119 Name IBM MtVM 01v Q000107
    OID 4119 Total and Average Input power 16724.09/176.04 in WATTS
    OID 4119 Number of inputs 95
    …

    AEM Support Group 中的许多端点没有报告电力输入。下面是完整的列表:

    The following 59 end points reported NO input power
    OID 4539 Name Outlet Group 7
    OID 4503 Name Outlet Group 2
    OID 4560 Name Outlet Group 4
    OID 4495 Name Probe Temperature
    OID 4470 Name Outlet Group 6
    OID 4537 Name Outlet Group 6
    …

    输出的末尾是电力输入和获取数据花费的处理时间的汇总信息。

    Monitoring completed after 1 hrs starting at 2009-12-09 15:10:38.687 finishing 
    at 2009-12-09 16:10:41.203
    Summary: Total number of end points monitored 81 Total pwr consumed 80886.13 
    Total processing time (ms) 3601999
  2. 跟踪输出:

    跟踪输出包含由连字符分隔的记录。每当一个端点报告新的电力输入数据时,创建一个记录。

    ---------------------------------
    OID 4590 Name IBM 7978 AC1 KQFTXMD
    metric number 1
    time stamp 2009-12-09 15:03:49.0
    Input Power Value 222.75599670410156
    Cumulative Power 222.75599670410156
    ----------------------------------
    OID 4590 Name IBM 7978 AC1 KQFTXMD
    metric number 2
    time stamp 2009-12-09 15:08:51.0
    Input Power Value 222.7830047607422
    Cumulative Power 445.53900146484375
    …

如您所见,AEMpwrReport 能够报告管理的所有端点的电力使用量统计数据。另外,一定要注意获取这些数据花费的时间。可以看到我能够在几秒内获取并处理 81 个端点的数据!您用 GUI 试试看要多长时间。注意,这个时间会随 Systems Director 服务器的处理能力以及 Systems Director 服务器和运行 AEMpwrReport 的客户机之间的可用网络带宽而变。

结束语

总之,只要具备一点儿编程背景,学习 RESTful 编程的基本知识只需花费很少的时间和精力。我只花了大约一个月就掌握了 RESTful 编程和 AEM REST API。一旦花时间掌握了它,就可以按自己希望的方式在需要的时候获取需要的数据。


下载

描述名字大小
Zip 文件AEM_rest_java_code.zip16KB

参考资料

学习

  • Architectural Styles and the Design of Network based Software Architectures”(Roy Thomas Fielding,University of California at Irvine,2000 年):Fielding 的博士论文描述了 REST。
  • Java 中的 JSON:JSON (Java Script Object Notation) 的网站,可以从这里下载 JSON java 和 HTML 文件并了解 JSON 数据交换格式。
  • IBM Systems Management SD 信息中心:在这里了解 REST、Systems Director 和 AEM REST API。
  • Java 中的基本 REST 客户端操作样例:可以从这里获取 REST 客户机代码。
  • Ryan Tamiko 撰写的 “How I explained REST to my wife”:以有趣的方式了解 REST。
  • Firefox 的附件:下载 Jonie,这是一种用来开发 URI 调用原型的工具。
  • 使用 XML-RPC 为 C++ 应用程序启用 Web 服务(Karthik Subbian 和 Ramakrishnan Kannan,developerWorks,2006 年 6 月):详细讲解如何以服务的形式公开 C++ 方法。
  • AIX and UNIX 专区:developerWorks 的“AIX and UNIX 专区”提供了大量与 AIX 系统管理的所有方面相关的信息,您可以利用它们来扩展自己的 UNIX 技能。
  • AIX and UNIX 新手入门:访问“AIX and UNIX 新手入门”页面可了解更多关于 AIX 和 UNIX 的内容。
  • AIX and UNIX 专题汇总:AIX and UNIX 专区已经为您推出了很多的技术专题,为您总结了很多热门的知识点。我们在后面还会继续推出很多相关的热门专题给您,为了方便您的访问,我们在这里为您把本专区的所有专题进行汇总,让您更方便的找到您需要的内容。
  • AIX and UNIX 下载中心:在这里你可以下载到可以运行在 AIX 或者是 UNIX 系统上的 IBM 服务器软件以及工具,让您可以提前免费试用他们的强大功能。
  • IBM Systems Magazine for AIX 中文版:本杂志的内容更加关注于趋势和企业级架构应用方面的内容,同时对于新兴的技术、产品、应用方式等也有很深入的探讨。IBM Systems Magazine 的内容都是由十分资深的业内人士撰写的,包括 IBM 的合作伙伴、IBM 的主机工程师以及高级管理人员。所以,从这些内容中,您可以了解到更高层次的应用理念,让您在选择和应用 IBM 系统时有一个更好的认识。
  • 随时关注 developerWorks 技术活动和网络广播,了解各种 IBM 产品和 IT 行业话题。
  • 加入 免费的 developerWorks Live! 简介,获取最新的 IBM 产品、工具以及 IT 行业趋势的资讯。
  • 观看 developerWorks 按需演示,包括面向初学者的产品安装和设置演示,以及为经验丰富的开发人员提供的高级功能。

获得产品和技术

  • 以最适合您的方式 评估 IBM 产品:下载产品试用版,在线试用产品,在云环境下试用产品,或者在 SOA Sandbox 中花费几个小时来学习如何高效地实现 Service Oriented Architecture。

讨论

条评论

developerWorks: 登录

标有星(*)号的字段是必填字段。


需要一个 IBM ID?
忘记 IBM ID?


忘记密码?
更改您的密码

单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件

 


在您首次登录 developerWorks 时,会为您创建一份个人概要。您的个人概要中的信息(您的姓名、国家/地区,以及公司名称)是公开显示的,而且会随着您发布的任何内容一起显示,除非您选择隐藏您的公司名称。您可以随时更新您的 IBM 帐户。

所有提交的信息确保安全。

选择您的昵称



当您初次登录到 developerWorks 时,将会为您创建一份概要信息,您需要指定一个昵称。您的昵称将和您在 developerWorks 发布的内容显示在一起。

昵称长度在 3 至 31 个字符之间。 您的昵称在 developerWorks 社区中必须是唯一的,并且出于隐私保护的原因,不能是您的电子邮件地址。

标有星(*)号的字段是必填字段。

(昵称长度在 3 至 31 个字符之间)

单击提交则表示您同意developerWorks 的条款和条件。 查看条款和条件.

 


所有提交的信息确保安全。


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=10
Zone=AIX and UNIX, Java technology
ArticleID=627391
ArticleTitle=基于 IBM Active Energy Manager 的 REST 应用程序编程
publish-date=02172011