Table of Contents

19. API

19. API

概要

Zabbix APIを使用すると、Zabbixの設定をプログラムで取得および変更でき、ヒストリデータへのアクセスが可能になります。次の目的で広く使用されています。

Zabbixと連携する新しいアプリケーションを作成する
Zabbixをサードパーティソフトウェアと統合する
ルーチンタスクを自動化する

Zabbix APIはWebベースのAPIであり、Webフロントエンドの一部として発送されます。JSON-RPC 2.0プロトコルを使用し、次の2つのことを意味します。

APIは一連の個別メソッドで構成されている
クライアントとAPI間の要求と応答は、JSON形式を使用してエンコードされる

プロトコルとJSONの詳細については、JSON-RPC 2.0 仕様と JSON形式のホームページを参照してください。

Zabbix機能をPythonアプリケーションに統合する方法の詳細については、Zabbix APIのPythonライブラリzabbix_utilsを参照してください。

構造

APIは、名目上、別々のAPIにグループ化された多数のメソッドから構成されています。それぞれのメソッドはある特定のタスクを実行します。例えば、host.createメソッドはhost APIに属し、新しいホストを作成に使用されます。歴史的には、APIは"クラス"と呼ばれることもあります。

ほとんどのAPIは、少なくともget, create, update, deleteという4つのメソッドを持ち、それぞれデータの取得、作成、更新、削除を行います。しかし、一部のAPIでは、全く別のメソッドを提供することもあります。

リクエストの実行

フロントエンドを設定したら、リモートHTTPリクエストを使用してAPIを呼び出すことができます。これを行うには、フロントエンドディレクトリにあるapi_jsonrpc.phpファイルにHTTP POSTリクエストを送信する必要があります。たとえば、Zabbixフロントエンドが http://example.com/zabbix にインストールされている場合、apiinfo.versionメソッドを呼び出すHTTPリクエストは次のようになります。

POST http://example.com/zabbix/api_jsonrpc.php HTTP/1.1
       Content-Type: application/json-rpc
       
       {
       "jsonrpc": "2.0",
       "method": "apiinfo.version",
       "id": 1,
       "auth": null,
       "params": {}
       }

リクエストのContent-Typeヘッダーは、application/json-rpc、application/jsonまたはapplication/jsonrequestのいずれかの値に設定されている必要があります。

ワークフローの例

次のセクションでは、いくつかの使用例をより詳細に説明します。

認証

Zabbixのデータにアクセスするには、次のどちらかを行う必要があります。

既存のAPIトークンを使用(ZabbixフロントエンドまたはトークンAPIを使用して作成);
user.loginメソッドで取得した認証トークンを使用。

たとえば、標準のAdminユーザーとしてログインして新しい認証トークンを取得したい場合、JSON リクエストは次のようになります。

{
           "jsonrpc": "2.0",
           "method": "user.login",
           "params": {
               "username": "Admin",
               "password": "zabbix"
           },
           "id": 1,
           "auth": null
       }

リクエストオブジェクトを詳しく見てみましょう。プロパティは次のとおりです。

jsonrpc - APIで使用される JSON-RPC プロトコルのバージョン。Zabbix APIはJSON-RPCバージョン2.0を実装します。
method - 呼び出されるAPIメソッド。
params - APIメソッドに渡されるパラメータ。
id - リクエストの任意のID。
auth - ユーザー認証トークン。まだ持っていないので、nullに設定されています。

資格情報を正しく指定した場合、APIによって返される応答にはユーザー認証トークンが含まれます。

{
           "jsonrpc": "2.0",
           "result": "0424bd59b807674191e7d77572075f33",
           "id": 1
       }

レスポンスオブジェクトには次のプロパティが含まれます。

jsonrpc - 繰り返しになりますが、JSON-RPCプロトコルのバージョン。
result - メソッドによって返されたデータ。
id - 対応するリクエストのID。

ホストの取得

Zabbixのデータにアクセスするために使用できる有効なユーザー認証トークンを取得できました。次に例として、host.getメソッドを使用して、構成されているすべてのホストのID、ホスト名、およびインターフェースを取得してみましょう。

{
           "jsonrpc": "2.0",
           "method": "host.get",
           "params": {
               "output": [
                   "hostid",
                   "host"
               ],
               "selectInterfaces": [
                   "interfaceid",
                   "ip"
               ]
           },
           "id": 2,
           "auth": "0424bd59b807674191e7d77572075f33"
       }

authプロパティにuser.loginを呼び出して取得した認証トークンを設定するよう注意してください。

レスポンスオブジェクトには、要求されたホストに関するデータが含まれます。

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

パフォーマンス上の理由から、取得するオブジェクトプロパティを常にリストアップし、すべてのオブジェクトプロパティを取得しないようにすることをお勧めします。

新しいアイテムの作成

先ほどのhost.getリクエストで取得したデータを使って、"Zabbixサーバー" に新しいアイテムを作成してみましょう。これはitem.createメソッドを使用して実行できます。

{
           "jsonrpc": "2.0",
           "method": "item.create",
           "params": {
               "name": "Free disk space on /home/joe/",
               "key_": "vfs.fs.size[/home/joe/,free]",
               "hostid": "10084",
               "type": 0,
               "value_type": 3,
               "interfaceid": "1",
               "delay": 30
           },
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 3
       }

作成が成功した場合のレスポンスには、新しく作成されたアイテムのIDが含まれます。これは、以降のリクエストでアイテムを参照するために使用できます。

{
           "jsonrpc": "2.0",
           "result": {
               "itemids": [
                   "24759"
               ]
           },
           "id": 3
       }

なおitem.createメソッドや他のcreateメソッドも、オブジェクトの配列を受け入れて、1 回のAPI呼び出しで複数のアイテムを作成することもできます。

複数のトリガーの作成

したがって、createメソッドが配列を受け入れる場合、次のように複数のトリガーを追加することも可能です。

{
           "jsonrpc": "2.0",
           "method": "trigger.create",
           "params": [
               {
                   "description": "Processor load is too high on {HOST.NAME}",
                   "expression": "last(/Linux server/system.cpu.load[percpu,avg1])>5",
               },
               {
                   "description": "Too many processes on {HOST.NAME}",
                   "expression": "avg(/Linux server/proc.num[],5m)>300",
               }
           ],
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 4
       }

作成が成功した場合のレスポンスには、新しく作成したトリガーのIDが含まれます。

{
           "jsonrpc": "2.0",
           "result": {
               "triggerids": [
                   "17369",
                   "17370"
               ]
           },
           "id": 4
       }

アイテムの更新

アイテムを有効にします。つまりstatusを"0"に設定します。

{
           "jsonrpc": "2.0",
           "method": "item.update",
           "params": {
               "itemid": "10092",
               "status": 0
           },
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 5
       }

更新が成功したレスポンスには、更新されたアイテムのIDが含まれます。

{
           "jsonrpc": "2.0",
           "result": {
               "itemids": [
                   "10092"
               ]
           },
           "id": 5
       }

item.updateメソッドやその他のupdateメソッドは、オブジェクトの配列を受け入れ、1回のAPI呼び出しで複数のアイテムを更新することができます。

複数のトリガーの更新

複数のトリガーを有効にします。つまりstatusを 0 に設定します。

{
           "jsonrpc": "2.0",
           "method": "trigger.update",
           "params": [
               {
                   "triggerid": "13938",
                   "status": 0
               },
               {
                   "triggerid": "13939",
                   "status": 0
               }
           ],
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 6
       }

更新が成功した応答には、更新されたトリガーの ID が含まれます。

{
           "jsonrpc": "2.0",
           "result": {
               "triggerids": [
                   "13938",
                   "13939"
               ]
           },
           "id": 6
       }

これは、推奨される更新方法です。host.massupdateなどの一部の API メソッドを使用すると、より単純なコードを記述できますが、これらのメソッドは将来のリリースで削除される予定のため、使用は推奨されません。

エラーハンドリング

今まで試したメソッドはすべて成功しました。しかし、API に対して間違った呼び出しを行おうとするとどうなるでしょうか？host.create を呼び出して別のホストを作成する際に、必須の groups パラメータを省略してみましょう。

{
           "jsonrpc": "2.0",
           "method": "host.create",
           "params": {
               "host": "Linux server",
               "interfaces": [
                   {
                       "type": 1,
                       "main": 1,
                       "useip": 1,
                       "ip": "192.168.3.1",
                       "dns": "",
                       "port": "10050"
                   }
               ]
           },
           "id": 7,
           "auth": "0424bd59b807674191e7d77572075f33"
       }

レスポンスにはエラーメッセージが含まれます。

{
           "jsonrpc": "2.0",
           "error": {
               "code": -32602,
               "message": "Invalid params.",
               "data": "No groups for host \"Linux server\"."
           },
           "id": 7
       }

エラーが発生した場合、レスポンスオブジェクトにはresult プロパティの代わりに、次のデータを持つ error プロパティが含まれます。

code - エラーコード
message - 簡単なエラーの要約
data - より詳細なエラーメッセージ

エラーは、誤った入力値の使用、セッションタイムアウト、または存在しないオブジェクトへのアクセス試行など、さまざまなケースで発生する可能性があります。アプリケーションは、この種のエラーを適切に処理する必要があります。

APIバージョン

APIのバージョン管理を簡素化するために、Zabbix 2.0.4以降、APIのバージョンはZabbix自体のバージョンと一致していますが、apiinfo.version メソッドを使用して、使用している API のバージョンを確認することもできます。これは、バージョン固有の機能を使用するようにアプリケーションを調整する場合に役立ちます。

メジャーバージョン内では、機能の下位互換性を保証します。メジャーリリース間で下位互換性のない変更を行う場合、通常は古い機能を次のリリースで非推奨として残し、その後のリリースで削除します。場合によっては、下位互換性を提供せずにメジャーリリース間で機能を削除することもあります。非推奨の機能には決して依存せず、できるだけ早く新しい代替機能に移行することが重要です。

API 変更ログで、API に加えられたすべての変更を追うことができます。

参考文献

ここまでで Zabbix API を使い始めるのに十分な知識が得られましたが、これが全てではありません。更に詳しく知りたい場合は、利用可能な API のリストを参照することをお勧めします。

Documentation