オープンソース統合監視ツール Zabbix を使ってみよう(入門編)

第 3 回 Zabbix API 入門

  1. はじめに
  2. Zabbix APIの概要
  3. PhpZabbixApiについて
  4. PhpZabbixApiのインストール
  5. Zabbix APIの基本操作
  6. メソッド名とパラメータについて
  7. アイテムの一括登録
  8. グラフとスクリーンの作成
  9. まとめ

1. はじめに

前回までで、Zabbix のインストールから監視設定まで、Zabbix の一通りの使い方を紹介しました。

今回は、Zabbix の Web 管理画面で行ったさまざまな操作を管理画面を使用せずに行える Zabbix API について解説します。 また、PhpZabbixApi を用いた PHP 言語による Zabbix API の使用方法について解説します。

2. Zabbix APIの概要

Zabbix API を使用すると、管理画面を使用せずに Zabbix に蓄積されている各種データを取得したり、 各種設定を行ったりすることができます。 Zabbix API は Zabbix 1.8 ではベータ版の扱いでしたが、Zabbix 2.0 から正式な機能として提供されています。

Zabbix API は JSON-RPC というプロトコルを用いて HTTP で Zabbix フロントエンドにアクセスして、 Zabbix を操作することができます。 API 用の URL に対して、JSON 形式のデータを送ることで、JSON 形式のレスポンスが返ります。 API はメソッド名とパラメータから構成されます。

Zabbix API の操作手順は以下になります。

  1. 認証用 API(user.login)を実行してアクセストークンを取得する
  2. 1. のアクセストークンを用いて API にアクセスする

Zabbix API のリファレンスは Zabbix マニュアルの以下の章を参照してください。

https://www.zabbix.com/documentation/2.0/manual/appendix/api/api

代表的な Zabbix API の例を以下に挙げます。

操作対象 メソッド 概要
ユーザー user.create
user.get
user.login
user.logout
ユーザーを作成する
ユーザーを取得する
APIにログインする
APIからログアウトする
ホスト host.create
host.get
host.update
ホストを作成する
ホストを取得する
ホストを更新する
アイテム item.create
item.get
item.getobjects
item.update
アイテムを作成する
アイテムを取得する
フィルタ条件によりアイテムを取得する
アイテムを更新する
トリガー trigger.create
trigger.get
trigger.getobjects
trigger.update
トリガーを作成する
トリガーを取得する
フィルタ条件によりトリガーを取得する
トリガーを更新する

3. PhpZabbixApiについて

Zabbix API は cURL などの汎用の HTTP クライアントツールや、 HTTP や JSON に対応した言語を用いることで使用できますが、 認証や JSON データの作成を自前で行うのは煩雑になります。

そこで、各種言語に提供されている Zabbix API 用のライブラリを用いることで、 Zabbix API を容易に扱うことができるようになります。

本記事では、PhpZabbixApi を用いて Zabbix API を使用します。 PhpZabbixApi は PHP 用の Zabbix API ライブラリです。

4. PhpZabbixApiのインストール

PhpZabbixApi ライブラリのインストール自体は非常に簡単です。

以下のサイトの「Download PhpZabbixApi Library」からライブラリをダウンロードします。 アーカイブに含まれる ZabbixApi.class.php と ZabbixApiAbstract.class.php を 実行する PHP スクリプトと同じ場所に置いてください。

http://zabbixapi.confirm.ch/

また、PHP スクリプトをコマンドラインから実行できるように、 コマンドライン版の PHP をインストールしておいてください。

5. Zabbix API の基本操作

1. アクセス URL

Zabbix API にアクセスするためのURLは以下になります。

(Zabbix フロントエンドのトップ URL)/api_jsonrpc.php

例えば、Zabbix の管理画面URLのトップが http://www.example.com/zabbix/ の場合、 http://www.example.com/zabbix/api_jsonrpc.php になります。 Zabbix フロントエンドと同じホスト上であれば http://localhost/zabbix/api_jsonrpc.php になります。

2. 認証と API の呼び出し

実際に PhpZabbixApi を使って Zabbix フロントエンドにアクセスし、API を呼び出してみましょう。 ここでは、「apiinfo.version」という、Zabbix API のバージョンを取得するメソッドを呼び出します。

<?php

require 'ZabbixApi.class.php';

try {
    $api = new ZabbixApi('http://localhost/zabbix/api_jsonrpc.php', 'Admin', 'zabbix');
    $res = $api->apiinfoVersion();
    var_dump($res);
} catch (Exception $e) {
    echo $e->getMessage() . "\n";
}

?>

上記の内容を apiinfoVersion.php というファイルに保存し、コマンドライン版 PHP で実行します。 実行に成功すると、以下のような結果が出力されます。

$ php apiinfoVersion.php
string(5) "2.0.5"

6. メソッド名とパラメータについて

Zabbix API のリファレンスを PhpZabbixApi に読み替えるには、以下のルールを使用します。

1. メソッド名

以下のように、ピリオドの後の単語の 1 文字目を大文字にして結合します。

  • apiinfo.versionapiinfoVersion()
  • item.getobjectsitemGetObjects()

2. パラメータ

JSON のオブジェクト({ } の部分)は PHP の配列でキーと値を使用し、 JSON の配列([ ] の部分)は PHP の数値添字配列で表します。 JSON の文字列、数値はそのまま PHP の文字列、数値を使用します。 誤った型を使用するとサーバからエラーが返ります。

  • { "host": "server1" }array( 'host' => 'server1' )
  • { "applications": [ "609", "610" ] }array( 'applications' => array( '609', '610' ) )

PHP プログラムでは params の内容を引数に渡します。 params 以外の項目は PhpZabbixApi により自動的に生成されるため不要です。

JSON 形式で記述された以下のリクエストを PhpZabbixApi で送る場合は、 以下のようにします(以下はテンプレートを作成する例です)。

  • JSON 形式:
    {
        "jsonrpc": "2.0",
        "method": "template.create",
        "params": {
            "host": "Test template",
            "groups": {
                "groupid": 1
            },
            "hosts": [
                {
                    "hostid": "10084"
                },
                {
                    "hostid": "10090"
                }
            ]
        },
        "auth": "038e1d7b1735c6a5436ee9eae095879e",
        "id": 1
    }
    
  • PHPZabbixAPI の場合:
    $res = $api->templateCreate( array(
                                      'host' => 'Test template',
                                      'groups' => array(
                                                   'groupid' => 1
                                                 ),
                                      'hosts' => array(
                                                    array('hostid' => '10084'),
                                                    array('hostid' => '10090')
                                               )
                                   ) );
    

Zabbix API で指定する各パラメータの詳細については、Zabbix API リファレンスを参照してください。

具体的に指定する値については、あらかじめ管理画面で登録しておいた設定項目の情報を API で取得し、その内容を参照すると分かりやすいです。

7. アイテムの一括登録

実際に Zabbix API を使用して設定を行い、それが管理画面に反映されているかを見てみましょう。

以下のスクリプトは、テンプレート名からテンプレートの hostid を取得し、 テンプレートに対して複数のアイテムをまとめて登録します。 すでに同名のアイテムがあるとエラーになるので注意してください。

<?php

require 'ZabbixApi.class.php';

try {
    $api = new ZabbixApi('http://localhost/zabbix/api_jsonrpc.php', 'Admin', 'zabbix');

    // Test templateテンプレートの hostid を取得
    $tmpls = $api->templateGet( array('output' => 'extend',
                                         'filter' => array('host' => 'Test template') ) );
    // テンプレート情報が配列で返ってくるので、hostid を取り出す
    foreach ($tmpls as $tmpl) {
        $hostid = $tmpl->hostid;
    }

    // CPU usage アイテムを作成
    $res = $api->itemCreate( array( 'name' => 'CPU usage (API)',
                                    'key_' => 'system.cpu.util[,user,avg1]',
                                    'hostid' => $hostid,
                                    // type 0: Zabbix エージェント
                                    'type' => 0,
                                    // value_type 0: 浮動小数
                                    'value_type' => 0,
                                    'delay' => 30,
                                  ) );
    var_dump($res);

    // Load average アイテムを作成
    $res = $api->itemCreate( array( 'name' => 'Load average (API)',
                                    'key_' => 'system.cpu.load[]',
                                    'hostid' => $hostid,
                                    'type' => 0,
                                    'value_type' => 0,
                                    'delay' => 30,
                                  ) );
    var_dump($res);

    // Disk free アイテムを作成
    $res = $api->itemCreate( array( 'name' => 'Disk free (API)',
                                    'key_' => 'vfs.fs.size[/,free]',
                                    'hostid' => $hostid,
                                    'type' => 0,
                                    // value_type 3: 符号なし整数
                                    'value_type' => 3,
                                    'delay' => 60,
                                    'units' => 'B'
                                  ) );
    var_dump($res);

    // Disk usage アイテムを作成
    $res = $api->itemCreate( array( 'name' => 'Disk usage (API)',
                                    'key_' => 'vfs.fs.size[/,used]',
                                    'hostid' => $hostid,
                                    'type' => 0,
                                    'value_type' => 3,
                                    'delay' => 60,
                                    'units' => 'B'
                                  ) );
    var_dump($res);

    // Log (messages)アイテムを作成
    $res = $api->itemCreate( array( 'name' => 'Log (messages) (API)',
                                    'key_' => 'log[/var/log/messages,"warning|error",,100]',
                                    'hostid' => $hostid,
                                    // type 7: Zabbixエージェント(アクティブ)
                                    'type' => 7,
                                    // value_type 2: ログ
                                    'value_type' => 2,
                                    'delay' => 60,
                                  ) );
    var_dump($res);

} catch (Exception $e) {
    // 例外が発生した場合、メッセージを表示する
    echo $e->getMessage() . "\n";
}

?>

スクリプトを実行し、アイテムの作成に成功すると以下のような結果が出力されます (id の値は毎回変わります)。

$ php itemCreate.php
object(stdClass)#5 (1) {
  ["itemids"]=>
  array(1) {
    [0]=>
    string(5) "23334"
  }
}
object(stdClass)#6 (1) {
  ["itemids"]=>
  array(1) {
    [0]=>
    string(5) "23336"
  }
}
object(stdClass)#2 (1) {
  ["itemids"]=>
  array(1) {
    [0]=>
    string(5) "23338"
  }
}
object(stdClass)#3 (1) {
  ["itemids"]=>
  array(1) {
    [0]=>
    string(5) "23340"
  }
}
object(stdClass)#5 (1) {
  ["itemids"]=>
  array(1) {
    [0]=>
    string(5) "23342"
  }
}

次に、Web ブラウザで Zabbix の管理画面にログインし、設定 (Configuration)テンプレート (Templates) の 「テストテンプレート」の「アイテム (n)」(「Items (n)」)をクリックし、 アイテムが登録されていることを確認します。

8. グラフとスクリーンの作成

次に、グラフとスクリーンを Zabbix API を使用して作成してみましょう。

まず、以下のスクリプトでグラフを作成します。

<?php

require 'ZabbixApi.class.php';

try {
    $api = new ZabbixApi('http://localhost/zabbix/api_jsonrpc.php', 'Admin', 'zabbix');

    // 各アイテムの情報を取得
    $items = $api->itemGetObjects( array('host' => 'Test template',
                                         'name' => 'CPU usage (API)') );
    foreach ($items as $item) {
        $itemcpu = $item;
    }
    $items = $api->itemGetObjects( array('host' => 'Test template',
                                         'name' => 'Load average (API)') );
    foreach ($items as $item) {
        $itemload = $item;
    }

    // CPU load 折れ線グラフを作成(CPU 使用率 + ロードアベレージ)
    $res = $api->graphCreate( array('name' => 'CPU load/usage (API)',
                                    'width' => 900,
                                    'height' => 200,
                                    'gitems' => array(
                                            array(
                                                    'itemid' => $itemcpu->itemid,
                                                    'color' => 'C80000',
                                                    'yaxisside' => 0
                                            ),
                                            array(
                                                    'itemid' => $itemload->itemid,
                                                    'color' => '00C800',
                                                    'sortorder' => 1,
                                                    'yaxisside' => 1
                                            )
                                    )
                                   ) );
    var_dump($res);

} catch (Exception $e) {
    echo $e->getMessage() . "\n";
}

?>
$ php graphCreate.php
object(stdClass)#6 (1) {
  ["graphids"]=>
  array(1) {
    [0]=>
    string(3) "533"
  }
}

次に、以下のスクリプトでスクリーンを作成します。

<?php

require 'ZabbixApi.class.php';

try {
    $api = new ZabbixApi('http://localhost/zabbix/api_jsonrpc.php', 'Admin', 'zabbix');

    // zabbix-agentに属するグラフからscreenitems情報を作成
    $screenitems = array();
    $y = 0;

    $graphs = $api->graphGetObjects( array('host' => 'zabbix-agent') );
    foreach ($graphs as $graph) {
        echo "graphid: $graph->graphid, name: $graph->name\n";

        // resourcetype: 0: グラフ, (x, y): スクリーン上の位置
        $screenitems[] = array( 'resourcetype' => 0,
                                'resourceid' => $graph->graphid,
                                'rowspan' => 0,
                                'colspan' => 0,
                                'x' => 0,
                                'y' => $y++ );
    }
    var_dump($screenitems);

    // スクリーンを作成し(2 行 1 列)、グラフを追加
    $res = $api->screenCreate( array('name' => 'New screen (API)',
                                     'hsize' => 1,
                                     'vsize' => 2,
                                     'screenitems' => $screenitems
                                    ) );
    var_dump($res);

} catch (Exception $e) {
    echo $e->getMessage() . "\n";
}

?>
$ php screenCreate.php
graphid: 530, name: CPU load/usage
graphid: 534, name: CPU load/usage (API)
(中略)
object(stdClass)#6 (1) {
  ["screenids"]=>
  array(1) {
    [0]=>
    string(2) "21"
  }
}

管理画面で、監視データ (Monitoring)スクリーン (Screens) を開き、「スクリーン」で「New screen (API)」を選択して、スクリーンが作成されていることを確認します。

9. まとめ

今回は、Zabbix の管理画面上で行う各種操作を管理画面を使用せずに行える Zabbix API について解説しました。 Zabbix API を活用することで、さまざまな Zabbix の設定作業を自動化することができ、 作業にかかるコストを大幅に削減することが可能になります。