Zabbix API で最速でアラート情報にたどり着く！ そして自動化へ

こんにちは。
開発チームのワイルド担当、まんだいです。

今回は Zabbix の API について書いてみようと思います。

いきなりですが、 API って面倒だと思いますか？

私は正直言ってその逆で、圧倒的に API の方がお手軽。
Zabbix の管理画面は情報量が多いので、私くらいの利用頻度だと、どこに何があるのか忘れてしまうこともしばしば。

アラート情報はダッシュボードに出てくるので、さすがに迷いませんが、それでも API の方が速いだろう！ということで、 API からアラート情報を最速で取得する方法を調査しました。

API の実行環境

今回、 API を実行するために、 Postman というソフトウェアを使用しました。
元々は、 Chrome や Firefox の拡張機能としてリリースされていたものですが、スタンドアロン版もいつからかリリースされているので、こちらを使っていきます。

Postman | API Development Environment

今回の記事の内容を実行する分には、お試し版の範囲で問題ないと思います。
API 開発などで利用するのも便利ですので、気に入ったら有料プランに切り替えてみてください。
チームで開発する場合に、 URL の共有などができるので便利です！

 

Zabbix API のバージョンを確認する

まずは、一番簡単な API から実行してみましょう。
Zabbix が提供する API エンドポイントは1つしかないので、全ての API は以下の URL から実行します。

http[s]://[your domain]/api_jsonrpc.php

 

ログインアカウントなどの情報も送信するため、必ず POST で送信します。

またコンテンツタイプは application/json-rpc を指定しています。

まずは、 Zabbix の情報を取得してみます。

// request body
{
    "jsonrpc": "2.0",
    "method": "apiinfo.version",
    "id": 1,
    "auth": null,
    "params": {}
}

// response
{
    "jsonrpc": "2.0",
    "result": "3.4.14",
    "id": 1
}

 

こんな感じでバージョンが帰ってくれば、正しくリクエストできています。

エラーが出てしまう場合は、以下の HTTP リクエストの情報を見ながら、おかしな箇所を確認してください。

POST /api_jsonrpc.php HTTP/1.1
Host: [your domain]
Content-Type: application/json-rpc
{"jsonrpc":"2.0","method":"apiinfo.version","id":1,"auth":null,"params":{}}

 

リクエスト JSON は、body に raw データとして格納するとうまく行くようです。
それ以外では URL のずれなどが考えられるため正しい URL を確認しましょう。

手順としては、

• ブラウザから Zabbix の管理画面へログインする
• トップページの URL を確認する （今回は、https://[your domain]/zabbix.php?action=dashboard.view とします）
• api_jsonrpc.php は zabbix.php と同階層にそんざいするので、 zabbix.php?action=dashboard.view を api_jsonrpc.php に置換

これで正しい API への URL が取得できると思います。

 

ログインする

// request body
{
    "jsonrpc": "2.0",
    "method": "user.login",
    "params": {
        "user": "[ユーザー名]",
        "password": "[パスワード]"
    },
    "id": 1,
    "auth": null
}

// response
{
    "jsonrpc": "2.0",
    "result": "[32桁のハッシュ値]",
    "id": 1
}

 

レスポンスで取得したハッシュ値をトークンとして各リクエストの auth キーに入れることで、詳しい情報の取得ができるようになっています。

 

ホストの情報を取得する

ホストの一覧を取得するのは、非常に簡単です。
method に host.get を指定し、必要な情報を params に指定するだけです。

Zabbix はサーバーから取得しているデータ量が多いので、どちらかというとパラメータを覚える方が大変でしょう。

// request body
{
    "jsonrpc": "2.0",
    "method": "host.get",
    "params": {
        "output": [
            "hostid",
            "host"
        ],
        "selectInterfaces": [
            "interfaceid",
            "ip"
        ]
    },
    "id": 2,
    "auth": "[32桁のハッシュ値]"
}

// response
{
    "jsonrpc": "2.0",
    "result": [
        {
            "hostid": "1",
            "host": "Zabbix server",
            "interfaces": [
                {
                    "interfaceid": "1",
                    "ip": "127.0.0.1"
                }
            ]
        },
        ...
    ],
    "id": 2
}

 

user.login API で取得したログインハッシュを auth の部分に埋める必要があるところ以外は、コピペで情報が取得できるかと思います。
監視しているサーバー数が多いと、とんでもない量の JSON データが帰ってくるので注意しましょう。

件数が多い場合は limit キーを使って、データの件数を絞ることができます。

 

アラートを取得する

さて、本題のアラートの取得ですが、ホストの情報を取得する時とほとんど変わりはありません。

// request json
// 最新のアラートを 3 件取得する
{
    "jsonrpc": "2.0",
    "method": "alert.get",
    "params": {
        "output": "extend",
        "limit": "3",
        "sortfield": "alertid",
        "sortorder": "DESC"
    },
    "auth": "xxxxxxxxxxxxxxxxxxxxxx",
    "id": 1
}

// response
{
    "jsonrpc": "2.0",
    "result": [
        {
            "alertid": "21496022",
            "actionid": "13",
            "eventid": "72481",
            "userid": "xxx",
            "clock": "1557795687",
            "mediatypeid": "7",
            "sendto": "...",
            "subject": "...",
            "message": "...",
            "status": "1",
            "retries": "0",
            "error": "",
            "esc_step": "1",
            "alerttype": "0",
            "p_eventid": "xxxxx",
            "acknowledgeid": "0"
        },
        {
            "alertid": "21496021",
            "actionid": "13",
            "eventid": "72481",
            "userid": "xxx",
            "clock": "1557795687",
            "mediatypeid": "1",
            "sendto": "...",
            "subject": "...",
            "message": "...",
            "status": "1",
            "retries": "0",
            "error": "",
            "esc_step": "1",
            "alerttype": "0",
            "p_eventid": "xxxxx",
            "acknowledgeid": "0"
        },
        {
            "alertid": "21496020",
            "actionid": "11",
            "eventid": "72481",
            "userid": "xxx",
            "clock": "1557795687",
            "mediatypeid": "1",
            "sendto": "...",
            "subject": "...",
            "message": "...",
            "status": "1",
            "retries": "0",
            "error": "",
            "esc_step": "1",
            "alerttype": "0",
            "p_eventid": "xxxxx",
            "acknowledgeid": "0"
        }
    ],
    "id": 1
}

 

詳細な情報は消してしまっておりますが、取得できる項目は上記の通りです。
アラート発生時、解消時ともにこの API で取得できます。

ポイントらしいポイントもないんですが、強いて言うなら alertid を降順でソートするところでしょうか。
sortfield でソートしたいデータを指定し、 sortorder でソート順を指定します。

sortorder は ASC | DESC のいずれかで指定し、大文字である必要があります。
これには少し詰まりました。

 

結論

結局のところ、 API からアラート情報を取得するには、2つの API を実行する必要があることがわかりました。

1. user.login API で ログイントークンを取得
2. alert.get API でアラート情報を取得

1 のレスポンスをちょちょいとパースしてトークンを取り出せば、 2 の API も実行可能ですので、プログラムに明るくない方でも、割と簡単に作れるんじゃないでしょうか。

 

id とはなんぞや？

id は任意の整数で、レスポンスの識別のためにユーザーが指定可能です。
ただし null や整数以外の値、もしくは存在しないなどの場合は、正しく API の戻り値が受け取れなくなるので注意してください。

 

まとめ

Zabbix API から監視の追加や変更ができるため、大抵のことは API からできてしまいます。

また、直接 API を実行するわけではないですが、 ansible や terraform からホストの登録などができるようにするプラグインもそれぞれ開発されている（設定の反映にソフトウェアが API を利用している）ため、構築から監視まで、一通り自動化できる環境が整っています。

AWS Lambda や Cloud Functions から定期的に叩くもよし、 cron から定期実行するもよし、定期的なホストのヘルスチェックの自動化や設定変更にどんどん使いたいところです。

最新バージョンの Zabbix API のドキュメントは、こちらから確認できますが、英語しか存在しないのと、あまり親切ではない印象なので最初のうちはある程度のトライアンドエラーは必要だと思います。
その際はテスト用の Zabbix サーバーを立てて、実行確認をした方が無難でしょう。

以上です。