如何使用 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 類負責建立遠程系統的證書，以執行安全的調用。