技術メモメモ: Zabbix API入門

ZabbixにはZabbix APIと呼ばれるHTTPベースで動くAPIが存在する。こちらを利用すると、リモートからZabbixのホスト一覧取得やホストの登録など、さまざまな操作を行うことができる。

今回、実際にZabbix APIを利用して、ホスト一覧の取得とホスト登録作業を実施してみた。

Zabbix環境

利用する環境は以下の通り。

OS : Cent OS 7.6
Zabbix : MIRACLE ZBX 4.0.2
APIのURL : http://192.168.11.24/zabbix/api_jsonrpc.php

事前準備

Zabbix APIを使うにあたり、curlとjqを利用する。curlはCent OS 7であれば標準でインストールされており、HTTPプロトコルでデータの送受信ができるコマンドとなる(正確にはHTTP以外にもさまざまなプロトコルに対応している)。

jqコマンドは、Zabbix APIやREST APIなどで利用されているJSON形式のデータを整形して出力したり、必要なデータのみ抽出するのに利用するコマンドとなる。jqコマンドはOSに標準ではインストールされていないので、yumでインストールしておく。

# yum install epel-release
# yum install jq

また、Zabbix APIのURLやヘッダ情報などは、毎回同一となることから、あらかじめ変数として利用できるようにしておこう。

# header='Content-Type:application/json-rpc'
# apiurl='http://192.168.11.24/zabbix/api_jsonrpc.php'

なお、JSONでは{"キー(key)": "値(value)"}といったようにデータを表現する。本記事では、データ名称を「キー」、データの値を「値」として表現することにする。

Zabbix APIを実行する際に送信するJSON形式のデータは、以下構文となる。

{
  "jsonrpc": "2.0",
  "method": "メソッド名",
  "params": {
    "パラメータ1 Key": "パラメータ1 Value",
    "パラメータ2 Key": "パラメータ2 Value",
    ...
  },
  "auth": "Zabbix認証トークン",
  "id": 任意の数字
}

以降の手順では、上記構文の送信データを作成したのち、curlコマンドでそのデータを送信してAPIを実行する、という流れとなる。

とりあえずZabbix APIを使ってみよう

apiinfo.versionというメソッドでZabbix APIのバージョンを確認することができるので、まずはそれを実行してZabbix APIの動作を確認してみよう。

送信するデータを変数jsonに以下のように代入する。

# json='{"jsonrpc": "2.0","method": "apiinfo.version","params": [],"id": 1}'

curlコマンドを使いZabbix APIを実行する。必要な定型文はすべて変数にしているので、そこまで複雑なコマンドではない。

# curl -sS -X POST -H "${header}" -d "${json}" ${apiurl} | jq
{
  "jsonrpc": "2.0",
  "result": "4.0.2",
  "id": 1
}

resultキーが4.0.2となっている。Zabbix APIのバージョンは、Zabbixと同様4.0.2となっていることがわかる。

なお、送信するデータは、"${json}"のようにダブルクォートで囲まないとエラーとなるので注意すること。

# curl -sS -X POST -H "${header}" -d ${json} ${apiurl} | jq
curl: (6) Could not resolve host: "2.0","method"; 不明なエラー
curl: (6) Could not resolve host: "apiinfo.version","params"; 不明なエラー
curl: (3) [globbing] illegal character in range specification at pos 2
curl: (3) [globbing] unmatched close brace/bracket at pos 2

認証トークンを取得しよう

Zabbix APIの実行は、認証トークンが必要となる。認証トークンは、user.loginメソッドで取得できる。

Adminユーザーの認証トークンを取得する場合は、以下コマンドとなる。passwordキーにはAdminユーザーのパスワードを入力すること。

# json='{"jsonrpc": "2.0","method": "user.login","params": {"user": "Admin","password": "XXXXXXXX"},"id": 1,"auth": null}'
# echo $json | jq
{
  "jsonrpc": "2.0",
  "method": "user.login",
  "params": {
    "user": "Admin",
    "password": "XXXXXXXX"
  },
  "id": 1,
  "auth": null
}

# curl -sS -X POST -H "${header}" -d "${json}" ${apiurl} | jq
{
  "jsonrpc": "2.0",
  "result": "4c6e0aedc3b0ab857fdab135880b468e",
  "id": 1
}

resultキーの値(上記では4c6e0aedc3b0ab857fdab135880b468e)が認証トークンとなる。

この認証トークンは、この後のZabbix API実行で毎回必要となることから、変数に代入しておこう。

# json='{"jsonrpc": "2.0","method": "user.login","params": {"user": "Admin","password": "XXXXXXXX"},"id": 1,"auth": null}'
# zbxauth=$(curl -sS -X POST -H "${header}" -d "${json}" ${apiurl} | jq -r ".result")
# echo $zbxauth
aadba09641add6a14b7b3e95fa4920e4

ホスト一覧を取得しよう

host.getメソッドを使って、Zabbixに登録されているホスト一覧を取得できる。先ほど取得した認証情報はauthキーの値として指定する。

# json='{"jsonrpc": "2.0","method": "host.get","params": {"output": ["hostid","host"]},"id": 2,"auth": "'$zbxauth'"}'
# echo $json | jq
{
  "jsonrpc": "2.0",
  "method": "host.get",
  "params": {
    "output": [
      "hostid",
      "host"
    ]
  },
  "id": 2,
  "auth": "4c6e0aedc3b0ab857fdab135880b468e"
}

# curl -sS -X POST -H "${header}" -d "${json}" ${apiurl} | jq
{
  "jsonrpc": "2.0",
  "result": [
    {
      "hostid": "10084",
      "host": "Zabbix server"
    },
    {
      "hostid": "10261",
      "host": "t3013qnap"
    },

～(以下略)～

ホスト登録をしてみよう

今度はホストを登録するため、host.createメソッドを使ってZabbix APIを実行してみよう。今回は以下ホストを追加する。なお、以下設定項目はホスト作成時にすべて必須となる項目となる。

設定項目	値	Zabbix APIのパラメータ
ホスト名	Test Server	`"host": "Test Server"`
ホストグループ	Discovered hosts	`"groups": {"groupid": "5"}`
インターフェース種別	エージェント	`"type": 1`
標準インターフェース	Yes	`"main": 1`
接続方法	IPアドレス	`"useip": 1`
IP	192.168.11.120	`"ip": "192.168.11.120"`
DNS名	なし	`"dns": ""`
ポート	10050	`"port": "10050"`

ホストをホストグループに追加する場合は、ホストグループ名ではなくIDが必要となる。そのため、まずはhostgroup.getメソッドを使ってDiscovered hostsグループのIDを調べることにする。

# json='{"jsonrpc": "2.0","method": "hostgroup.get","params": {"output": ["groupid","name"],"filter": {"name": "Discovered hosts"}},"id": 2,"auth": "'$zbxauth'"}'
# echo $json | jq
{
  "jsonrpc": "2.0",
  "method": "hostgroup.get",
  "params": {
    "output": [
      "groupid",
      "name"
    ],
    "filter": {
      "name": "Discovered hosts"
    }
  },
  "id": 2,
  "auth": "4c6e0aedc3b0ab857fdab135880b468e"
}

# curl -sS -X POST -H "${header}" -d "${json}" ${apiurl} | jq
{
  "jsonrpc": "2.0",
  "result": [
    {
      "groupid": "5",
      "name": "Discovered hosts"
    }
  ],
  "id": 2
}

groupidが5であることがわかった。

次に、ホスト登録をhost.createメソッドを使って実施する。

# json='{"jsonrpc": "2.0","method": "host.create","params": {"host": "Test Server","groups": {"groupid": "5"},"interfaces": {"type": 1,"main": 1,"useip": 1,"ip": "192.168.11.120","dns": "","port": "10050"}},"id": 3,"auth": "'$zbxauth'"}'
# echo $json | jq
{
  "jsonrpc": "2.0",
  "method": "host.create",
  "params": {
    "host": "Test Server",
    "groups": {
      "groupid": "5"
    },
    "interfaces": {
      "type": 1,
      "main": 1,
      "useip": 1,
      "ip": "192.168.11.120",
      "dns": "",
      "port": "10050"
    }
  },
  "id": 3,
  "auth": "4c6e0aedc3b0ab857fdab135880b468e"
}

# curl -sS -X POST -H "${header}" -d "${json}" ${apiurl} | jq
{
  "jsonrpc": "2.0",
  "result": {
    "hostids": [
      "10269"
    ]
  },
  "id": 3
}

GUIからも正常にホストが追加されていることが確認できた。

認証トークンを削除しよう

認証トークンは利用が終わったら、きちんとログオフして利用できないようにしておこう。ログオフはuser.logoutメソッドを利用する。

# json='{"jsonrpc": "2.0","method": "user.logout","params": [],"id": 4,"auth": "'$zbxauth'"}'
# echo $json | jq
{
  "jsonrpc": "2.0",
  "method": "user.logout",
  "params": [],
  "id": 4,
  "auth": "4c6e0aedc3b0ab857fdab135880b468e"
}

# curl -sS -X POST -H "${header}" -d "${json}" ${apiurl} | jq
{
  "jsonrpc": "2.0",
  "result": true,
  "id": 4
}

resultキーがtrueとなっていれば正常にログオフできている。これで再度Zabbix APIを実行しても「Session terminated」と表示され、実行できなくなる。

# json='{"jsonrpc": "2.0","method": "host.get","params": {"output": ["hostid","host"]},"id": 2,"auth": "'$zbxauth'"}'
# curl -sS -X POST -H "${header}" -d "${json}" ${apiurl} | jq
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params.",
    "data": "Session terminated, re-login, please."
  },
  "id": 2
}

まとめ

以上でZabbix APIの使い方の説明は終了となる。今回は初歩の内容ではあったが、使いこなせるようになれば、複数台のホスト追加や設定変更作業などが効率よく実施できるようになるだろう。

なお、Zabbix APIは、公式ドキュメントに利用メソッドや利用例などがまとめられている。マニュアルを見ながら、有用な機能をどんどん使えるようにしていきたい。

Zabbix Documentation 4.0 - 19. API

更新履歴

2019/2/13 新規作成
2021/2/14 送信するJSON形式のデータ構文の説明と、各送信データをjqコマンドで整形した結果を追記

技術メモメモ

Zabbix API入門