如何開始使用WhatsUp Gold的新RESTful API

上個月，我們發布了WhatsUp Gold 2019.1，隨之添加了一個功能強大的REST API，可讓您輕鬆地將其他系統或您自己的腳本與WUG整合。

使用新的REST API，您現在可以使用各種REST API呼叫從WhatsUp Gold獲取其他系統的資料，或者將資料輸入WhatsUp Gold或讓其他系統進行更改。目前已有大量的自動化案例，可以幫助IT團隊更快、更高效的運用。示範案例包括在進行更改之前自動將設備置於維護模式的能力，自動添加或刪除設備和監控工具的功能等。

最重要的是，REST API與語言和平台無關，這使它們能夠規避客戶端 – 服務器依賴性維護的無休止需求，並跨越任何環境組合。

如果您以前使用過REST API，那麼學習WhatsUp Gold的REST API應該很容易。 API通過Swagger公開，可讓您輕鬆瀏覽API及其選項。使用Swagger，您可以嘗試不同的API調用，並準確了解每個API對輸入的期望，以及它為輸出生成的內容。 Swagger的“試用”功能將針對實時WUG服務器運行API，因此您可以測試每個API並觀察結果。

下面，我們將簡要介紹如何開始使用WUG的新RESTful API，以及如何使用Swagger探索API和測試調用。有關API的更深入的指南，包括路徑和定義，請訪問我們的完整 RESTful API指南。

您需要了解的內容

首先，您需要知道如何與REST API進行通信。通常，此RESTful API需要以下謂詞：GET（查詢記錄），PUT（創建記錄），PATCH（修改/更新記錄）或DELETE（刪除記錄）。

您還需要了解以下REST端點及其提供的資源：

/api/v1/token 允許您獲取，續訂或刷新會話令牌。
/api/v1/device-groups 為您提供有關給定組的設備的信息。
/api/v1/devices 讓您在WUG中管理，監控和輪詢設備。
/api/v1/product 將為您提供產品和版本信息。
/api/v1/devices/{deviceId}/reports/ 將為給定的設備提供報告。
/api/v1/device-groups/{groupId}/devices/reports/ 將為給定的一組設備提供報告。
/api/v1/errors 是用於獲取錯誤模板信息的實用程序端點。
/api/v1/monitors 將允許您獲取配置和應用監視器模板。
/swagger 將為您提供實時的swagger UI交互式文件。

在開始使用WUG的REST API之前，您需要一些基礎知識：

部署的WhatsUp Gold 2019系統的主機名。
目標WhatsUp Gold系統上用戶的用戶名和密碼。
您最喜歡的HTTP客戶端（以下示例使用CURL實用程序）。

您還需要以下網址：

Swagger UI： http://<your-whatsup-gold-server>:9644/swagger/ui/index#/

主REST API端點： http://<your-WhatsUp-Gold-server>:9644/swagger/api/v1

Swagger API規範和文檔： http://<your-WhatsUp-Gold-server>:9644/swagger/docs/v1

從這裡，您可以通過https://<your-WhatsUp-Gold-server-server>:9644/swagger/docs/v1進入您的Web瀏覽器（<your-WhatsUp-Gold-server-server>WhatsUp Gold系統的主機IP）快速檢查REST API是否已經在WhatsUp Gold主機上監聽請求。如果此調用返回JSON對象，則API正在運行，您可以使用此主機名開始後續步驟。

使用Swagger UI，交互式REST API客戶端

如上所述，Swagger UI提供了一種使用實例瀏覽WhatsUp Gold REST文檔的簡便方法，並提供了一個簡單的開發客戶端，用於測試WhatsUp Gold REST調用。但是，應該注意的是，這些示例是針對您的WhatsUp Gold環境的實時調用（未模擬）。如果您只是為了開發目的而測試和探索REST API的功能，那麼最好是針對WhatsUp Gold的非生產實例運行。

要開始使用Swagger，請按照以下步驟操作：

打開瀏覽器 https://my-whatsup-gold-host:9644/swagger/ (my-whatsup-gold-host 是您安裝的WhatsUp Gold主機)
單擊“ 登錄” 按鈕。
瀏覽和構建查詢並查看JSON結果對象。

有關更深入的概述，請查看以下視頻：

檢索訪問令牌

要使用WhatsUp Gold RESTful API設置會話，您必須檢索訪問令牌。（令牌端點支持的語法，用法和字段在RESTful API指南的Retrieve API Token 和 Revoke API令牌中有詳細說明）。這是請求：

curl -k --request POST --url https://my-whatsup-gold-host:9644/api/v1/token --data "grant_type=password&username=emmacurtis&password=1a2B3cA1b2C3"

你應該得到這個輸出， my-whatsup-gold-host你的WhatsUp Gold UI運行的主機名在哪裡，你提供用戶名和密碼的值（例如你為這個RESTful客戶端應用程序創建的WhatsUp Gold用戶）。

{
  "access_token": "X03w.....dziTwmA",
  "token_type": "bearer",
  "expires_in": 86399,
  "refresh_token": "X03w.....dziTwmA"
}

獲取設備列表

從這裡，您可以將訪問令牌作為標頭參數傳遞，鍵入“Bearer”並獲取您的用戶信息。請注意，這my-whatsup-gold-host是您運行WhatsUp Gold WebUI的主機名。您還必須X03w…..dziTwmA使用自己的278字節訪問令牌替換佔位符字符串。組ID為零（“0”）表示由MY NETWORK管理的整個設備。

curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer X03w.....dziTwmA' 'http://my-whatsup-gold-host:9644/api/v1/device-groups/0/devices'

你應該得到以下輸出：

{
  "paging": {
    "size": 96
  },
  "data": {
    "devices": [
      {
        "hostName": "192.168.37.1",
        "networkAddress": "192.168.37.1",
        "bestState": "Up",
        "worstState": "Up",
        "name": "192.168.37.1",
        "id": "14"
      },
      {
        "hostName": "192.168.37.100",
        "networkAddress": "192.168.37.100",
        "bestState": "Maintenance",
        "worstState": "Maintenance",
        "name": "192.168.37.100",
        "id": "16"
      },
      [list shortened for purposes of documentation]
}

從這裡，您可以設置自己的腳本，以您認為合適的任何方式使用我們的新REST API。有關API及其功能的完整技術說明，請下載 WhatsUp Gold REST API指南。然後加入我們的Progress | Ipswitch社區，分享腳本並討論您的想法。我們迫切希望了解您如何利用WhatsUp Gold！快樂的編碼！

How to Get Started with WhatsUp Gold’s New RESTful API – WhatsUp Gold

譯自WhatsUp Gold官方部落格