オープンソース統合監視ツール Zabbix を使ってみよう（入門編）
第 3 回 Zabbix API 入門
- はじめに
- Zabbix APIの概要
- PhpZabbixApiについて
- PhpZabbixApiのインストール
- Zabbix APIの基本操作
- メソッド名とパラメータについて
- アイテムの一括登録
- グラフとスクリーンの作成
- まとめ
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 の操作手順は以下になります。
- 認証用 API（user.login）を実行してアクセストークンを取得する
- 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 スクリプトと同じ場所に置いてください。
また、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.version→apiinfoVersion()item.getobjects→itemGetObjects()
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 の設定作業を自動化することができ、 作業にかかるコストを大幅に削減することが可能になります。