WhatsUp Gold の新しい RESTful API の使用方法

Jeff Edwards | 投稿日 6月 2, 2021 | ネットワーク監視

プログレスは、先日、WhatsUp Gold 2019.1 のリリースを発表しました。この新バージョンに加えられたパブリック REST API サポート機能を利用すると、WhatsUp Gold を他の既存システムや独自のスクリプトと直接統合できます。

新しい機能により、広範囲の REST API 呼び出しを使用して、他のシステムから WhatsUp Gold のデータを取得したり、WhatsUp Gold にデータを入力したり、他のシステムから変更を加えたりすることが可能になりました。この機能を利用すれば、IT部門の迅速化と効率化に役立つ広範な自動化ユースケースが得られます。変更を行う前にデバイスを自動的にメンテナンスモードにしたり、デバイスを自動的に追加・削除したり、監視を追加したりなどといったことができます。

何よりも、REST API は言語とプラットフォームに依存しないので、クライアントとサーバーの依存関係を常にチェックして調整する必要がなくなり、環境の様々な組み合わせ（IoT、モバイルなど）に対応できます。

では、どのように始めればいいでしょうか？REST API の使用経験があれば、WhatsUp Gold の REST API を使うのは簡単だと思います。API は Swagger を介してアクセスでき、API とそのオプションを簡単に調べることができます。多様な API 呼び出しを試して、各 API が入力に何を期待しているか、何を出力として生成するかを正確に知ることができます。WhatsUp Gold の専用 Swagger インタフェースには、ライブの WhatsUp Gold サーバーに対して実際に API を実行する [Try it out] 機能もあります。この機能を使って、独自のスクリプト言語でどのように API 呼び出しを実装すればいいのかを確認することができます。

このブログで、WhatsUp Gold の新しい REST (RESTful) API の使用を開始する方法と、Swagger を使用して API をチェックしテストする方法の概要を説明します。パスや定義など、API の詳細なガイドについては、RESTful API Guide を参照してください。

開始するにあたって必要なこと

まず、REST API とどうコミュニケートするかを知っておく必要があります。この RESTful API で認識できる動詞としては、GET（レコードのクエリ）、PUT（レコードの作成）、PATCH（レコードの変更/更新）、DELETE（レコードの削除）があります。

また、次の REST エンドポイントと、それらが何を提供するかについても、理解しておいてください。

/api/v1/token：セッションのトークンを取得、更新
/api/v1/device-groups：デバイスグループの情報を取得
/api/v1/devices：デバイスの管理、監視、ポーリング
/api/v1/product：WhatsUp Gold のプロダクトとバージョン情報を取得
/api/v1/devices/{deviceId}/reports/：デバイスのレポート情報
/api/v1/device-groups/{groupId}/devices/reports/ ：デバイスグループのレポート情報

/api/v1/errors：エラー情報を取得
/api/v1/monitors：監視情報を取得、設定、適用
/swagger：ライブの Swagger UI インタラクティブ・ドキュメント

さらに、次の点も確認してください。

デプロイされた WhatsUp Gold 2019 システムのホスト名
対象 WhatsUp Gold システムのユーザーのユーザー名とパスワード
使いたい HTTP クライアント (ここで紹介する例では cURL ユーティリティを使用)

以下の URL もチェックしておく必要があります。

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

REST API のプライマリ・エンドポイント: https://<your-WhatsUp-Gold-server>:9644/swagger/api/v1

Swagger API の仕様とドキュメント: https://<your-WhatsUp-Gold-server>:9644/swagger/docs/v1

WhatsUp Gold ホストに REST API からのリクエストが届いているかどうかを確認するには、Web ブラウザに https://<your-WhatsUp-Gold-server-host>:9644/swagger/docs/v1 (ここでは、<your-WhatsUp-Gold-server-host> としていますが、ここに WhatsUp Gold システムのホスト名を入れます)と入力するとわかります。呼び出しが JSON オブジェクトを返してきたら、API は機能しています。このホスト名を使って以降のステップを試すことができます。

Swagger UI - インタラクティブ REST API クライアントの使用

Swagger UI は、ライブの例を含む WhatsUp Gold REST API ドキュメントをブラウズする簡単な方法を用意するとともに、WhatsUp Gold REST API 呼び出しをテストするためのシンプルな開発クライアントを提供します。含まれる例は、WhatsUp Gold 環境に対して実行されるライブ呼び出しであり、シミュレーションではないことに注意してください。したがって、開発目的で REST API の機能をテストしたり、調べている段階であれば、WhatsUp Gold の非プロダクション・インスタンスに対して実行することをお勧めします。

Swagger の使用を開始するには、次の手順に従ってください。

https://my-whatsup-gold-host:9644/swagger/(“my-whatsup-gold-host” は WhatsUp Gold をインストールしたホスト) へのブラウザを開く。
[Login] ボタンをクリックする。
ブラウズし、クエリを作成し、JSON の結果オブジェクトを表示する。

より詳しくは、このブログの末尾にある WhatsUp Gold REST API の概要ビデオをご覧ください。

アクセストークンの取得

WhatsUp Gold RESTful API を使用してセッションをセットアップするには、アクセストークンを取得する必要があります。（トークンの扱い方については、RESTful 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” とタイプするとユーザー情報を取得できます。プレースホルダーの文字列 “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 を使用できます。REST API の詳細は、WhatsUp Gold の RESTful API Guide (英語) をご参照ください。また、Progress コミュニティに参加して、スクリプトを共有し、各自のアイデアを議論してください。当社では、WhatsUp Gold をご利用のお客様が、REST API をどのように活用されるのかに、大いに注目しております。ハッピーコーディング！

WhatsUp Gold の新しい RESTful API の使用方法

開始するにあたって必要なこと

Swagger UI - インタラクティブ REST API クライアントの使用

アクセストークンの取得

デバイスのリストを取得

Tags

WhatsUp Gold をお試しください