如何使用 Java 测试 IBM Systems Director 的 REST API

 

转自： http://www.ibm.com/developerworks/cn/aix/library/au-aix-systemsdirector/section2.html

如何使用 Java 测试 IBM Systems Director 的 REST API

让咱们开始吧

关于 REST API

1. REST 表明 Representational State Transfer。REST 风格的架构由客户端和服务器组成。IBM Systems Director 也提供一个基于 RESTFul webservices 的接口。IBM Systems Director 是一个基于 Web 的工具，并为 REST 提供大量支持。几乎全部经过 CLI 和 GUI 支持的功能也能够经过 REST API 支持。REST 使用 HTTP 协议。它支持如下 HTTP 方法：

   • POST：该方法用于建立一个新的资源。
   • PUT：该方法用于修改一个现有资源。
   • GET：该方法用于检索有关资源的信息。
   • DELETE：该方法用于删除资源。
2. REST 操做和返回代码的类型：

   有两种类型的 REST 操做：

   1. 同步操做：

      在这种操做类型中，在做业完成以前，REST API 调用一直保持阻塞。做业完成后，该操做类型将返回 HTTP 返回代码和响应（如适用）。这种操做类型的返回代码示例以下：

      • 200: 请求成功。全部 GET 操做都返回 200。
      • 204: 无内容
      • 304: 无变动
   2. 异步操做：

      在这种操做类型中，REST API 调用将启动一个做业，并提供返回代码和位置，使用户可以肯定做业的状态。用户能够查询位置，或者使用基于 JMS 的侦听程序，直到操做完成。这种操做类型的返回代码示例以下：

      • 201 CREATED: 资源已建立。全部 POST 操做都会返回 201。
      • 202 ACCEPTED: 请求已接受，等待处理。部分 PUT 和 DELETE 操做会返回此代码。
3. 3. 一些 HTTP 错误代码：
   • 400：请求无效。请求可能不正确，或者请求中的数据格式不正确。
   • 401：请求须要用户身份验证。
   • 404：IBM Systems Director Server 没有找到任何结果能够匹配请求 URI 中的指定资源。
   • 500：IBM Systems Director 遇到了一个意外状况，阻止它处理请求。

测试 REST API 的方法

1. 手动（使用工具）：使用一些外部 REST 客户端，如 Firefox Poster、http4e 等，并手动调用 REST API。咱们在本教程中使用了 Poster。您能够使用本身喜欢的 REST 客户端。
2. 自动：使用编程语言或脚本自动调用 REST API。本教程将介绍使用 Java 进行自动测试。您能够使用本身喜欢的任何其余语言或脚本。

这两个方法的说明以下：

1. 手动（使用 Poster）：

   在本节中，咱们将讨论使用 Poster 手动测试一些 IBM Systems Director 的基本功能：

1. 得到资源列表（GET 操做）
2. 发现新资源 （POST 操做）
3. 修改已发现的资源（PUT 操做）
4. 删除资源（DELETE 操做）
1. 得到资源列表（GET 操做）：

   如图 1 所示，您使用 GET 操做能够列出资源。GET 检索有关该资源的信息。检索资源的请求如图 1 所示：

   
   
   图 1. 使用 Poster 的 GET 操做 
    
   
   

   在图 1 中，您做为用户能够看到如下信息：

   1. URL: 检索有关服务器信息的 URI。
   2. Actions: 选定的操做是 GET。
   3. Header 部分：用户须要在这部分中输入如下内容：
   • ISDAPIVersion: IBM Systems Director 的版本。
   • Authorization: 这是一个 base64 转换的用户 ID 和密码，用于 IBM Systems Director。
   • Accept: 可接受的内容类型

   响应如图 2 所示：

   
   
   图 2. GET 操做的响应
    
   
   

   在图 2 中，您能够看到 IBM Systems Director 对 GET 请求的响应。响应包括一个返回代码和响应正文。图 2 中的返加代码是 200 (OK)，而响应正文是 IBM Systems Director 所返回的全部资源的列表。

2. 发现资源（POST 操做）

   发现是 IBM Systems Director 的一个很是基本的操做，用于发现资源。您须要使用 POST 方法进行发现，所以，您须要提供 HTTP 正文 (JSON) 与 HTTP 头。发现的 HTTP 正文以下：

   
   
   清单 1. 输入 POST 发现操做的 JSON
   

   { "IPAddress": ["9.1.2.3"], "ResourceTypes": ["Server", "OperatingSystem"] }

   
   

   您须要提供资源的 IP 地址和资源类型。使用 POST 操做能够发现新源，如图 3 所示。

   
   
   图 3. POST 操做发现资源
    
   
   

   响应如图 4 所示：

   
   
   图 4. 发现的 POST 操做的响应
    
   
   

   在图 4 的 HTTP 响应中要注意一些重要事项：

   • 返回代码：对于 POST 请求是 201
   • Location: POST 操做是异步操做，它包括返回的位置。位置是一个 URL，它能够用于检查使用 GET 操做的做业状态，如图 1 所示。

   使用 Location URI 的 GET 操做的响应如图 5 所示。

   
   
   图 5. 使用 Location URI 的 GET 操做的响应
    
   
   

   在 HttpResponse 中，如图 5 所示，您能够看见如下值：

   • URI: 它是以前 POST 操做的 "Location"。
   • Percent Complete: 它以百分比显示任务的完成状态。在图 5 中它是 100%，意味着任务已经完成。
   • DiscoveryStatus: 该字段显示做业的状态，即，它是否成功。在图 5 中，它的值是 "Ok"，这意味着做业已成功完成。
3. 修改资源（PUT 操做）：

   要修改一个现有资源，您须要使用 PUT 操做。对于 PUT 操做，您须要传递 HTTP 正文和 HTTP 头。用于修改资源的 HTTP 正文以下：

   
   
   清单 2. 清单 2. 输入 PUT 修改资源操做的 JSON 
   

   { "Properties": {"DisplayName" : "NewName"} }

   
   

   您能够使用 PUT 操做来修改资源，如图 6 所示。

   
   
   图 6. PUT 操做来修改资源
    
   
   

   对 PUT 请求的响应如图 7 所示：

   
   
   图 7. 对 PUT 请求的响应
    
   
   

   如图 7 所示，IBM Systems Director 返回了 204 做为返回代码，这意味着，它没有内容要返回，而且请求已成功提交。

4. 删除资源（DELETE 操做）：

   当您须要删除资源时，应使用 DELETE 方法。您须要将想删除的资源 OID 追加到 URI 自己。使用 DELETE 操做可删除资源，如图 8 所示。

   
   
   图 8. DELETE 操做删除资源。
    
   
   

   DELETE 操做的响应如图 9 所示。

   
   
   图 9. DELETE 操做的响应
    
   
   

   如图 9 所示，IBM Systems Director 返回了 204 做为返回代码，这意味着它没有内容要返回，而且 DELETE 请求已成功提交。

   咱们已介绍了使用 Poster 的四种基本 ISD REST API 操做。一样地，您也能够利用该工具或其余一些您喜欢的工具，手动地测试或使用其余 IBM Systems Director 功能。您也能够经过使用编程方式访问这些 REST API，自动化整个过程。本教程的下一节讨论使用 Java 程序执行全部上述 IBM Systems Director REST API 功能所需的步骤。

2. 自动（使用 Java 代码）：

   在这里，咱们也将看到在上面已经讨论过的四个相同功能。咱们已经使用 Apache 的 HttpClient 和 HttpResponse 类调用 REST API，并读取响应。咱们使用这些类来简化更新请求头以及将 HTTP 正文做为参数传递的过程。您甚至能够使用 Java 的 HttpURLConnection 类，或者您所喜欢的任何其余实用工具来进行调用。您可以以编程方式来调用 ISD REST API，以下：

1. 列出资源 （GET 操做）：

   GET 操做列出有关该资源的信息。为了运行 IBM Systems Director 的 GET 请求，咱们须要针对 IBM Systems Director 相关的条目修改 HttpClient 的 sendGetRequest 方法，如清单 3 所示：

   
   
   清单 3. 在 HttpClient.java 中的 sendGetRequest 方法
   

   . . . sendGetRequest(String uri){ GetMethod method = new GetMethod(uri); method.addRequestHeader(new Header("Accept","application/json")); method.addRequestHeader(new Header("Accept-Language", "en_us")); method.addRequestHeader(new Header("ISDAPIVersion","6.2.1.0")); method.addRequestHeader(new Header ("Authorization", "Basic cm9vdDpnbzRic==")); int statusCode = client.executeMethod(method); return statusCode; }

   
   

   在清单 3 的代码片断中，您能够看到如下信息：

   1. 初始化 GetMethod 类的一个对象，并将 URI 传递给它。
   2. 使用 addRequestHeader () 方法将 Request 头添加给 GetMethod 对象。如下 IBM Systems Director 特定条目须要被添加到请求头：
      • Accept: 拥有 "application/json" 值的 Accept 头。
      • Accept-Language: 值能够是任意支持的语言。咱们使用了 en_us。
      • ISDAPIVersion: IBM Systems Director 版本 "6.2.1.0"。
      • Authorization: base64 转换的用户名和密码。
   3. 调用 HttpClient 的执行方法并将 GetMethod 的对象传递给它。

   在更新 HttpClient 以后，您须要编写本身的客户端，以调用 HttpClient 类的 sendGetRequest 方法，以 URI 做为一个参数。咱们使用了基于 JUnit 的测试来调用 sendGetRequest 方法并检查返回代码。

   
   
   清单 4. 清单 4. 测试 GET 的 JUnit 测试用例
   

   private DWHttpClient httpClient = null; String hostURI = null; @Test public void testListRes() { httpClient = new DWHttpClient(); properties = new Properties(); try { hostURI = "https://1.2.3.4:8422/ibm/director/rest/resources/System"; statusCode = httpClient.sendGetRequest(hostURI); assertEquals(HttpStatus.SC_OK, statusCode); } catch (Exception e) { fail("unexpected exception has happened "+e.getMessage()); e.printStackTrace(); } }

   
   

   在清单 4 的代码中，咱们首先初始化 HttpClient 类的对象，咱们在清单 3 中已修改过该对象。接着，咱们初始化 hostURI，它用于从 IBM Systems Director 检索资源信息，最后，调用 sendGetRequest() 方法以运行 GET 请求。

   咱们使用 JUnit 的 assertEquals() 方法检查了状态代码，验证它是否 HttpStatus.SC_OK，这实际上表示返回代码 200。

2. 发现资源（POST 操做）：

   该 POSToperation 发现了在 IBM Systems Director 中的资源。为了运行 IBM Systems Director 的 POST 请求，咱们须要针对 IBM Systems Director 相关的条目修改 HttpClient 的 sendPostRequest 方法，并编写咱们本身的客户端来调用请求和检查结果。sendPostRequest 和客户端的代码片断如清单 5 所示：

   
   
   清单 5. HttpClient.java 中的 sendPostRequest 方法
   

   . . . sendPostRequest(String hostURI, String requestData){ PostMethod method = new PostMethod(uri); method.addRequestHeader(new Header("Content-Type","application/json")); method.setRequestEntity (new StringRequestEntity (requestData, "application/json", "UTF-8")); method.addRequestHeader (new Header ("Authorization", "Basic cm9vdDpnbzRicm9rZQ==")); method.addRequestHeader(new Header("ISDAPIVersion", "6.2.1.0")); int statusCode = client.executeMethod(method); return statusCode; }

   
   

   在清单 5 的代码片断中，您能够看到如下信息：

   1. 初始化一个 PostMethod 的对象并将 URI 传递给它。
   2. 将 Request 头添加到 PostMethod 对象，其中包括 Content-Type、Authorization 和 ISDAPIVersion。
   3. 设置一个 Request Entity 以传递请求数据。
   4. 最后经过传递 PostMethod 对象来运行方法。

   基于 JUnit 的客户端调用 POST 请求如清单 6 所示：

   
   
   清单 6. 测试 POST 的 JUnit 测试用例
   

   private DWHttpClient httpClient = null; String hostURI = null; @Test public void testDiscovery() { httpClient = new DWHttpClient(); try { hostURI = "https://1.2.3.4:8422/ibm/director/rest/discover"; String requestData = "{\"IPAddress\": [\"5.6.7.8\"], \"ResourceTypes\": [\"Server\", \"OperatingSystem\"]}"; statusCode = httpClient.sendPostRequest(hostURI, requestData); assertEquals(HttpStatus.SC_CREATED, statusCode); } catch (Exception e) { fail("unexpected exception has happened "+e.getMessage()); e.printStackTrace(); } }

   
   

   在清单 6 的代码中，咱们首先初始化了 HttpClient 类的对象，咱们已在清单 5 的代码中修改过该对象。而后咱们初始化 hostURI，它用于发如今请求数据中所说起的资源。

   在下一步中，咱们调用了 HttpClient 的 sendPosttRequest() 方法，使用 hostURI 和 requestData 做为参数，而后咱们使用 assertEquals() 方法检查返回代码。在请求成功执行后，它返回一个代码 201，这表示 "CREATED"（已建立）。

   因为 POST 是一个异步操做，您须要跟踪做业的进度，出于这个缘由，它始终将位置做为头的一部分返回。您须要从请求返回的响应对象中检索响应头。您能够使用位置头的值来检查进度。请参考下载小节中的样例类，得到完整代码。

3. 修改资源（PUT 操做）：

   当您须要修改资源时，要使用 PUT 请求。为了运行 IBM Systems Director 的 PUT 请求，咱们须要针对 IBM Systems Director 相关的条目修改 HttpClient 的 sendPutRequest 方法，并编写咱们本身的客户端来调用请求和检查结果。sendPutRequest 和客户端的代码片断如清单 7 所示。

   
   
   清单 7. HttpClient.java 中的 sendPutRequest 方法
   

   . . . sendPutRequest(String uri, String requestData){ PutMethod method = new PutMethod(uri); method.addRequestHeader(new Header ("Content-Type","application/json")); method.addRequestHeader(new Header("ISDAPIVersion", "6.2.1.0")); method.setRequestEntity(new StringRequestEntity (requestData, "application/json", "UTF-8")); method.addRequestHeader(new Header ("Authorization", "Basic cm9vdDpnbzRicm9rZQ==")); int statusCode = client.executeMethod(method); return statusCode; }

   
   

   基于 JUnit 的客户端调用 PUT 请求，如代码清单 8 所示：

   
   
   清单 8. 测试 PUT 的 JUnit 测试用例
   

   private DWHttpClient httpClient = null; String hostURI = null; @Test public void testModifyResource() throws IOException { httpClient = new DWHttpClient(); hostURI = "https:1.2.3.4:8422/ibm/director/rest/resources/Server/12345"; String requestData = " {\"Properties\": {\"DisplayName\" : \"NewResName\"}}"; statusCode = httpClient.sendPutRequest(hostURI, requestData); assertEquals(HttpStatus.SC_NO_CONTENT,statusCode); }

   
   

   在请求成功执行后，IBM Systems Director 返回代码 204，如代码清单 8 所示

4. 删除资源（DELETE 操做）：

   当您须要删除资源时，应使用 DELETE 方法。您须要将想删除的资源 OID 追加到 URI 自己。为了运行 IBM Systems Director 的 DELETE 请求，咱们须要针对 IBM Systems Director 相关的条目修改 HttpClient 的 sendDeleteRequest 方法，并编写咱们本身的客户端来调用请求和检查结果。sendDeleteRequest 和客户端的代码片断以下所示：

   
   
   清单 9. HttpClient.java 中的 sendDeleteRequest 方法
   

   . . . sendDeleteRequest(String uri){ DeleteMethod method = new DeleteMethod(uri); method.addRequestHeader(new Header ("Authorization", "Basic cm9vdDpnbzRicm9rZQ==")); method.addRequestHeader(new Header("ISDAPIVersion", "6.2.1.0")); int statusCode = client.executeMethod(method); return statusCode; }

   
   

   基于 JUnit 的客户端调用 DELETE 请求，以下所示：

   
   
   清单 10. 测试 DELETE 的 JUnit 测试用例
   

   private DWHttpClient httpClient = null; String hostURI = null; @Test public void testDiscovery() throws IOException { httpClient = new DWHttpClient(); hostURI = "https://1.2.3.4:8422/ibm/director/rest/resources/Server/12345"; statusCode = httpClient.sendDeleteRequest(hostURI); assertEquals(HttpStatus.SC_NO_CONTENT, statusCode); }

   
   

   在请求成功执行后，IBM Systems Director 会返回代码 204，如代码清单 10 所示

使用 HTTP 客户端自动化 REST API 测试的样例代码

咱们已对本教程中所说起的全部场景以及一些其余 POST 操做场景编写了样例代码。该代码能够从本教程的下载小节处下载。该代码包括如下部分：

• 列出资源（GET 操做）
• 发现新资源（POST 操做）
• 请求访问已发现的资源（POST 操做）
• 收集清单（POST 操做）
• 修改资源（PUT 操做）
• 删除资源（DELETE 操做）

若是有须要，能够重用样例代码。该代码也包括一些实用工具类和属性文件，以下所示：

• HttpClient：该类定义全部 HTTP 操做，如 GET、POST、PUT 和 DELETE。该类还包含了 Director 服务器的证书验证代码。
• HttpResponse：该类用于格式化 HTTP 响应。
• Read Properties file：该类用于从属性文件读取属性。
• Util：该类包含一些实用工具方法，用于检索资源的 OID 等。
• config.properties：该文件中的属性针对不一样系统而有所不一样。

为了使代码更灵活并能够实现重用，咱们引入了一个属性文件，您能够在该文件中输入 IBM Systems Director 和全部端点的信息。测试用例会在运行时读取该属性文件，以检索这些信息。只需更新该属性文件，便可在任何系统上运行此代码。

您能够运行各个类，以执行任何特定操做。咱们还引入了一个 TestSuite 文件，一次运行全部脚本。

咱们已经建立了一个 ISDSuite 文件，并推出了套装文件，从 Eclipse 运行全部测试。图 10 显示了执行的结果。

图 10. JUnit TestSuite 执行的结果
 

您还能够使用如下命令，从命令提示符运行全部测试：

java org.junit.runner.JUnitCore ISDSuite

 

要注意几个重点：

1. 为了运行 REST API，您要将用户名和密码的组合转换成 base 64 编码。
   • 对于 Linux®：您须要使用如下格式: usrename:password

     将上述字符串转换成 base 64 编码，并在字符串前面追加 "Basic"，而后把它放在 Authorization 头。例如，Basic "Base64 converted string"

   • 对于 Microsoft® Windows®：用户须要使用如下格式：domain\\usrename:password

     将上述字符串转换成 base 64 编码，并在字符串前面追加 "Basic"，而后把它放在 Authorization 头。例如，Basic "Base64 converted string"

2. IBM Systems Director 证书：DWHttpClient 类负责建立远程系统的证书，以执行安全的调用。