Kompira Enterprise REST API を利用して外部からオブジェクト情報を取得する

「Kompira Enterprise REST API を利用して外部からジョブフローを実行する」では、指定のジョブフローを外部から操作する方法を紹介しました。
今回は Kompira Enterprise の REST API の別の利用方法として、外部から Kompira Enterprise のオブジェクト情報を取得してみます。さらに応用例として、フィルタ条件付きのデータ取得と、取得したデータを CSV 形式のデータに変換する方法をご紹介します。

※ 本稿は Kompira Enterprise 1.6系に準拠した画像を用いています。

動作確認環境

本稿は、以下の環境で検証しています。

または

または

事前準備

APIトークンの取得

APIの利用に必要な「REST APIトークン」を、「Kompira Enterprise REST API を利用して外部からジョブフローを実行する」に記載されている手順で取得してください。

オブジェクトの作成

外部から取得するオブジェクトを Kompira Enterprise 上に作成します。
ここでは、以下のようなノード情報を格納したテーブルオブジェクトを作成します。

※以下の画像は Kompira Enterprise バージョン 1.6.8 時点のものです。他のバージョンでは項目が異なることがあります。

基本の取得方法

実際に API リクエストを使ってオブジェクトの情報を取得してみましょう。
オブジェクト取得時のリクエスト URL は以下になります。

GET <オブジェクトパス>

ここでは、curl コマンドを利用して HTTP リクエストを送信します。

$ curl -XGET \
  -H "Accept: application/json" \
  -H "Authorization: Token <トークン鍵>" \
  "https://<Kompira Enterprise サーバー URL>/root/サーバーリスト/server1" --insecure

すると下記のような JSON 形式の辞書データが返却されます。

※以下の結果は Kompira Enterprise バージョン 1.6.8 時点のものです。他のバージョンでは出力が異なることがあります。

{
  "id": 117,
  "abspath": "/root/サーバーリスト/server1",
  "owner": "root",
  "fields": {
    "nodetype": "/system/nodetypes/Servers/SSH",
    "conntype": "ssh",
    "hostname": "server1",
    "ipaddr": "192.168.1.10",
    "port": null,
    "shell": "",
    "use_shell": false,
    "proxy": null,
    "account": null
  },
  "extra_properties": {},
  "user_permissions": {},
  "group_permissions": {
    "other": {
        "readable": true,
        "writable": false,
        "executable": false,
        "priority": 0
    }
  },
  "created": "2023-06-28T08:34:34.295013+09:00",
  "updated": "2023-06-28T08:34:34.384860+09:00",
  "display_name": "server1",
  "description": "",
  "type_object": "/system/types/NodeInfo",
  "parent_object": "/root/サーバーリスト"
}

レスポンスデータの説明は下表を参照してください。

オブジェクト一覧の取得

GET リクエストのエンドポイントにディレクトリもしくはテーブルオブジェクトを指定することで、その配下に存在するオブジェクトを一括で取得することができます。

この場合のリクエスト URL は以下の２通りになります。

GET <ディレクトリもしくはテーブルのパス>.children   # 子オブジェクト一覧
GET <ディレクトリもしくはテーブルのパス>.descendant # 子孫オブジェクト一覧

コマンドでの実行は以下のようになります。

$ curl -XGET \
  -H "Accept: application/json" \
  -H "Authorization: Token <トークン鍵>" \
  "https://<Kompira Enterprise サーバー URL>/root/サーバーリスト.children" --insecure

このときのレスポンスデータは以下です。
“results” の中に、先ほどのレスポンスデータがリストとして格納されています。

{
  "count": 3,
  "next": null,
  "previous": null,
  "results": [
    { "id": 117, "abspath": "/root/サーバーリスト/server1", ... },
    { "id": 118, "abspath": "/root/サーバーリスト/server2", ... },
    { "id": 119, "abspath": "/root/サーバーリスト/server3", ... }
  ]
}

一覧取得時のレスポンスデータの説明は下表を参照してください。

応用例1 (フィルタ条件付きの一覧取得)

一覧取得のリクエスト時にクエリパラメータを指定することで、レスポンスに含まれるデータを絞り込むことができます。

例えば、以下の条件でのフィルタを行います。

1. “/root” の子孫
2. ノード情報オブジェクト
3. 本日の00:00:00以降に更新されたオブジェクト

このときに指定するクエリは下表のようになります。

コマンドでの実行は以下のようになります。

$ curl -XGET \
  -H "Accept: application/json" \
  -H "Authorization: Token <トークン鍵>" \
  "https://<Kompira Enterprise サーバー URL>/root.descendant?type_object=/system/types/NodeInfo&updated__gte=$(date '+%Y-%m-%dT00:00:00')" --insecure

応用例2 (CSV ファイルへの変換)

REST API 経由で取得したデータを活用する方法について一例を説明します。
先述の「オブジェクト一覧」で取得したノードオブジェクトの情報を CSV 形式のファイルへ変換します。
ここでは整形用のコマンドとして、 jq コマンドを用います。

$ curl -XGET \
  -H "Accept: application/json" \
  -H "Authorization: Token <トークン鍵>" \
  "https://<Kompira Enterprise サーバー URL>/root/サーバーリスト.children" --insecure | jq -r '.results[].fields | [.hostname, .ipaddr, .conntype] | @csv' \
  > server_list.csv

変換後のデータは以下のようになります。

※ Kompira Enterprise 1.5系と1.6系では、原則 https による HTTP リクエストしか認めていません。今回は簡単にするために、 --insecure オプションをつけることで、SSL 証明書がなくても HTTP リクエストを送れるようにしています。