RESTエクスポートAPI

はじめに

jvmguard UIでは、データビューにエクスポートボタンがあり、表示されているデータを機械可読形式で抽出してさらに処理できます。

外部データ分析を自動化したり、jvmguardを他の監視システムに接続したりするには、この手動エクスポートは実用的ではありません。その場合は、代わりにRESTエクスポートAPIを使用できます。

REST APIはデフォルトで有効になっています。config/application.yamlでrestApiEnabledプロパティをfalseに設定すると無効にできます。有効な場合、APIはWebサーバーと同じポートの/apiパスで提供され、同じプロトコル(HTTPまたはHTTPS)を使用します。

有効にすると、WebサーバーポートへのHTTP(S)呼び出しで記録データを取得できます。Web UIと同様に、単一のVMのデータを要求したり、特定のVMグループの累積データを要求したりできます。

APIの使用

APIへのアクセスはBasic HTTP認証で保護されています。これは、資格情報がHTTPSをプロトコルとして使用している場合にのみ暗号化されることを意味します。ユーザー名はjvmguardのログイン名で、パスワードはjvmguard UIで生成するAPIキーです。データエクスポートエンドポイントは、アクセスレベルに関係なく、APIキーを持つすべてのユーザーが利用できます。/api/triggerBackupエンドポイントには管理者が必要です。

APIキーは「外部アクセス」ページで作成できます。このページには、jvmguard UI上部のユーザードロップダウンから「アカウント設定」を開いて移動します。生成されたAPIキーは一度だけ表示されます。ダイアログを確認すると、新しいAPIキーが有効になり、以前のAPIキーは無効になります。

返される形式はHTTPリクエストの「Accept」ヘッダーに依存します。次のMIMEタイプがサポートされています。

text/plain: 出力はプレーンテキストになります。複数の列が利用可能な場合、CSVデータが書き込まれます。階層データの場合、トップレベルのみがエクスポートされます。区切り文字はデフォルトでカンマですが、csvSeparator URLクエリパラメータで変更できます。winLineBreak URLクエリパラメータは、デフォルトの改行をLFからCR+LFに変更します。Acceptヘッダーが送信されない場合、これがデフォルトです。
application/json: 出力はJSON形式になります。application/json;charset=UTF-8を使用すると、他のAcceptヘッダーに関係なく、出力がUTF-8エンコーディングになることを保証できます。
application/xml: 出力はXML形式になります。

REST APIの呼び出しは、/apiプレフィックス、1つ以上のURLセグメント、クエリパラメータのリストで構成されます。例えば、Webサーバーポートが8020の場合、次の呼び出しは

http://localhost:8020/api/groups

jvmguardに設定されているすべてのグループを一覧表示します。次のURLは

http://localhost:8020/api/transactions/callTree?group=Demo%2FWeb&interval=1h

VMグループ「Demo/Web」の過去1時間のコールツリーデータを取得します。グループ名のスラッシュがURLエンコードされていることに注意してください。

すべての開始時刻と終了時刻は、現在時刻と1970年1月1日午前0時(UTC)の間のミリ秒、または次のいずれかの形式で指定できます。

形式	例	説明
`yyyy-MM-dd'T'HH:mm:ss.SSS` `yyyy-MM-dd'T'HH:mm:ss` `yyyy-MM-dd`	2026-07-02T22:40:00.000 2026-07-02T22:40:00 2026-07-02	サーバーのローカル時間での日時。短縮版はすべてゼロを指定した場合と同等です。
`yyyy-MM-dd'T'HH:mm:ss.SSS'Z'` `yyyy-MM-dd'T'HH:mm:ss'Z'` `yyyy-MM-dd'Z'`	2026-07-02T22:40:00.000Z 2026-07-02T22:40:00Z 2026-07-02Z	UTCでの日時。短縮版はすべてゼロを指定した場合と同等です。

APIドキュメント

次のURLが利用可能です。

/api/groups: すべてのVMグループのリストを返します。グループ階層の区切りはスラッシュです。記録オプションのツリーテーブル内のすべてのノードが幅優先で返されます。XMLとJSONでは、「pool」属性がグループがVMプールかどうかを示します。
/api/vms: VMのリストを返します。名前には、/api/groups URLが返す階層グループパスが含まれます。個々のプールVMは返されません。

クエリパラメータ	説明
group	VMを一覧表示する特定のグループ。指定しない場合、すべてのVMが返されます。
connected	`true`に設定すると、現在接続中のVMのみが返されます。

/api/telemetries: 利用可能なすべてのテレメトリタイプのリストを返します。下記のURLで使用します。
/api/telemetries/{telemetryType}: 指定されたテレメトリデータを返します。{telemetryType}の値は、上記の/api/telemetries URLが返す値のいずれかである必要があります。

クエリパラメータ	説明
interval	テレメトリ間隔。指定可能な値は`10min`、`20min`、`40min`、`80min`、`3h`、`6h`、`12h`、`1d`、`3d`、`6d`、`12d`、`30d`、`60d`、`180d`です
startTime endTime	間隔に加えて、開始時刻または終了時刻を指定できます。時刻の形式については上記を参照してください。省略した場合、現在時刻が終了時刻として使用されます。
vm group	VM名またはグループ名を指定できます。省略した場合、すべてのVMが使用されます。
pretty	`true`に設定すると、JSONとXMLの出力が整形されます
csvSeparator	text/plainが要求された場合、カスタムの区切り文字を指定できます
winLineBreak	`true`に設定され、かつtext/plainが要求された場合、LF改行の代わりにCR+LF改行が書き込まれます。

/api/transactions/callTree: 選択した間隔のコールツリーデータを返します。
/api/transactions/hotSpots: 選択した間隔のホットスポットデータを返します。
/api/transactions/overdue: 選択した間隔の期限超過トランザクションを返します。

クエリパラメータ	説明
interval	トランザクション間隔。指定可能な値は`1min`、`10min`、`1h`、`1d`です
mergePolicies	`true`に設定すると、異なるポリシー違反を持つトランザクションが単一のノードにマージされます。
startTime endTime	間隔に加えて、開始時刻または終了時刻を指定できます。時刻の形式については上記を参照してください。省略した場合、現在時刻が終了時刻として使用されます。
vm group	VM名またはグループ名を指定できます。省略した場合、すべてのVMが使用されます。
pretty	`true`に設定すると、JSONとXMLの出力が整形されます
csvSeparator	text/plainが要求された場合、カスタムの区切り文字を指定できます
winLineBreak	`true`に設定され、かつtext/plainが要求された場合、LF改行の代わりにCR+LF改行が書き込まれます。

/api/triggerBackup: データベースのバックアップをトリガーします。このエンドポイントには管理者が必要で、バックアップディレクトリの絶対ディレクトリパスをプレーンテキストで返します。バックアップファイルは、jvmguardデータディレクトリ内のbackupディレクトリに書き込まれます。このようなバックアップを復元するには、jvmguardサーバーを停止し、dbディレクトリの内容をbackupディレクトリの内容で置き換えて、jvmguardサーバーを再起動します。REST APIの使用が実用的でない場合、またはjvmguardインストールでREST APIを無効にしている場合は、jvmguardデータディレクトリにtrigger_backupという名前のファイルを作成することもできます。バックアップが正常に完了すると、ファイルが削除され、バックアップが実行されます。