第 3 回 Zabbix API 入門

1.はじめに

前回までの 第 1 回 Zabbix を動かしてみよう第 2 回 Zabbix のさまざまな監視機能を試してみよう では、Zabbix のインストールから監視設定まで、Zabbix の一通りの使い方を紹介しました。

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

2.Zabbix API の概要

Zabbix API を使用すると、管理画面を使用せずに Zabbix に蓄積されている各種データを取得したり、各種設定を行ったりすることができます。
Zabbix API は 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 マニュアルの API を参照してください。

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

 

操作対象 メソッド操作対象 概要
ユーザー user.create
user.delete
user.get
user.login
user.logout
ユーザーを作成する
ユーザを削除する
ユーザーを取得する
APIにログインする
APIからログアウトする
ホスト host.create
host.delete
host.get
host.update
ホストを作成する
ホストを削除する
ホストを取得する
ホストを更新する
アイテム item.create
item.delete
item.get
item.update
アイテムを作成する
アイテムを削除する
アイテムを取得する
アイテムを更新する
トリガー trigger.create
trigger.delete
trigger.get
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 ZIP」からライブラリをダウンロードして、実行する PHP スクリプトから参照できるようにします。
https://github.com/confirm/PhpZabbixApi

本手順では、composer によってライブラリを準備することを前提とします。
(プロキシなどがあれば実行前に設定しておく)

# git clone https://github.com/confirm/PhpZabbixApi.git
# cd PhpZabbixApi
# composer update

また、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_once __DIR__.'/vendor/autoload.php';

use Confirm\ZabbixApi\Exception;
use Confirm\ZabbixApi\ZabbixApi;

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(6) "5.0.17"

 

 

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": "10364"
            },
            {
                "hostid": "10365"
            }
        ]
    },
    "auth": "038e1d7b1735c6a5436ee9eae095879e",
    "id": 1
}

PHPZabbixAPI の場合:

$res = $api->templateCreate( array(
                                'host' => 'Test template',
                                'groups' => array(
                                    'groupid' => 1
                                ),
                                'hosts' => array(
                                    array('hostid' => '10364'),
                                    array('hostid' => '10365')
                                )
                            ) );

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

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

以下の例では、新しく「Test template」を作成し、ホストを割り当てています。

<?php

require_once __DIR__.'/vendor/autoload.php';

use Confirm\ZabbixApi\Exception;
use Confirm\ZabbixApi\ZabbixApi;

try {
    $api = new ZabbixApi('http://localhost/zabbix/api_jsonrpc.php', 'Admin', 'zabbix');
    $res = $api->templateCreate( array(
                                    'host' => 'Test template',
                                    'groups' => array(
                                                'groupid' => 1
                                                ),
                                    'hosts' => array(
                                                array('hostid' => '10364'),
                                                array('hostid' => '10365')
                                                )
                                    ) );
    var_dump($res);
} catch (Exception $e) {
    echo $e->getMessage() . "\n";
}

?>

スクリプトを実行します。

$ php templateCreate.php
array(1) {
  ["templateids"]=>
  array(1) {
    [0]=>
    string(5) "10441"
  }
}

 

次に、Web ブラウザで Zabbix の管理画面にログインし、[設定] → [テンプレート] より、「Test template」が作成されており、追加したホストが割り当てられていることを確認します。
(例では、「Test template」でフィルタリングしています)

 

 

7.アイテムの一括登録

実際に Zabbix API を使用して設定を行い、それが管理画面に反映されているかを見てみましょう。
以下のスクリプトは、テンプレート名からテンプレートの templateid を取得し、テンプレートに対して複数のアイテムをまとめて登録します。
すでに同名のアイテムがあるとエラーになるので注意してください。

<?php

require_once __DIR__.'/vendor/autoload.php';

use Confirm\ZabbixApi\Exception;
use Confirm\ZabbixApi\ZabbixApi;

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

    // Test templateテンプレートの templateid を取得
    $tmpls = $api->templateGet( array('output' => 'extend',
                                        'filter' => array('host' => 'Test template') ) );

    // テンプレート情報が配列で返ってくるので、templateid を取り出す
    foreach ($tmpls as $tmpl) {
        $hostid = $tmpl["templateid"];
    }

    // 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
array(1) {
  ["itemids"]=>
  array(1) {
    [0]=>
    string(5) "36633"
  }
}
array(1) {
  ["itemids"]=>
  array(1) {
    [0]=>
    string(5) "36636"
  }
}
array(1) {
  ["itemids"]=>
  array(1) {
    [0]=>
    string(5) "36639"
  }
}
array(1) {
  ["itemids"]=>
  array(1) {
    [0]=>
    string(5) "36642"
  }
}
array(1) {
  ["itemids"]=>
  array(1) {
    [0]=>
    string(5) "36645"
  }
}

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

 

 

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

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

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

<?php

require_once __DIR__.'/vendor/autoload.php';

use Confirm\ZabbixApi\Exception;
use Confirm\ZabbixApi\ZabbixApi;

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

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

    $items = $api->itemGet( array('host' => 'Test template',
                                'filter' => array('name' => 'Load average (API)') ) );
    foreach ($items as $item) {
        $itemload = $item['itemid'];
    }

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

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

?>

スクリプトを実行します。

$ php graphCreate.php
array(1) {
  ["graphids"]=>
  array(1) {
    [0]=>
    string(4) "1849"
  }
}

今回の例では2行1列のスクリーンを作成するため、手動でも、任意のグラフを作成しておきます。

 

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

<?php

require_once __DIR__.'/vendor/autoload.php';

use Confirm\ZabbixApi\Exception;
use Confirm\ZabbixApi\ZabbixApi;

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

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

    $graphs = $api->graphGet( array('hostids' => '10364') );
    foreach ($graphs as $graph) {
        print $graph["graphid"] ." ";
        print $graph["name"] ."\n";

        // resourcetype: 0: グラフ, (x, y): スクリーン上の位置
        $screenitems[] = array( 'resourcetype' => 0,
                                'resourceid' => $graph["graphid"],
                                'rowspan' => 1,
                                'colspan' => 1,
                                '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
1853  CPU usage
1850  CPU load/usage (API)
array(2) {
  [0]=>
  array(6) {
    ["resourcetype"]=>
    int(0)
    ["resourceid"]=>
    string(4) "1853"
    ["rowspan"]=>
    int(1)
    ["colspan"]=>
    int(1)
    ["x"]=>
    int(0)
    ["y"]=>
    int(0)
  }
  [1]=>
  array(6) {
    ["resourcetype"]=>
    int(0)
    ["resourceid"]=>
    string(4) "1850"
    ["rowspan"]=>
    int(1)
    ["colspan"]=>
    int(1)
    ["x"]=>
    int(0)
    ["y"]=>
    int(1)
  }
}
array(1) {
  ["screenids"]=>
  array(1) {
    [0]=>
    string(2) "85"
  }
}

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

 

 

9.まとめ

今回は、Zabbix の管理画面上で行う各種操作を管理画面を使用せずに行える Zabbix API について解説しました。

Zabbix API を活用することで、さまざまな Zabbix の設定作業を自動化することができ、作業にかかるコストを大幅に削減することが可能になります。