Documentation
Table of Contents
19. API
概要
Zabbix API を使用すると、Zabbix の設定をプログラムで取得して変更し、ヒストリデータへのアクセスを提供できます。 次の目的で広く使用されています。
- Zabbix と連携する新しいアプリケーションを作成する
- Zabbix をサードパーティ ソフトウェアと統合する
- ルーチン タスクを自動化する
Zabbix API は Web ベースの API であり、Web フロントエンドの一部として出荷され、SON-RPC 2.0 プロトコルを使用します。これは、次の 2 つのことを意味します。
- API は一連の個別メソッドで構成されている
- クライアントと API 間の要求と応答は、JSON 形式を使用してエンコードされる
プロトコルと JSON の詳細については、JSON-RPC 2.0 仕様 と JSON 形式のホームページ を参照してください。
構造
このAPIは、名目上、別々のAPIにグループ化された多数のメソッドから構成されています。それぞれのメソッドはある特定のタスクを
実行します。例えば、host.create メソッドは host API に属し、新しいホストを作成するために使用されます。歴史的には、APIは
"classes"と呼ばれることもある。
ほとんどの API は、少なくとも get, create, update, delete という 4 つのメソッドを持ち、それぞれデータの取得、作成、更新、削除を
行います。しかし、一部の API では、全く別のメソッドを提供することもあります。
リクエストの実行
フロントエンドを設定したら、リモートHTTPリクエストを使用してAPIを呼び出すことができます。 これを行うには、フロントエンド ディレクトリにある api_jsonrpc.php ファイルにHTTP POSTリクエストを送信する必要があります。 たとえば、Zabbix フロントエンドが http://example.com/zabbix にインストールされている場合、apiinfo.version メソッドを呼び出す HTTP リクエストは次のようになります。
Performing requests
Once you've set up the frontend, you can use remote HTTP requests to call the API. To do that you need to send HTTP POST requests to the api_jsonrpc.php file located in the frontend directory. For example, if your Zabbix frontend is installed under http://example.com/zabbix, the HTTP request to call the apiinfo.version method may look like this:
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 - リクエストの任意の識別子。 -auth - ユーザー認証トークン。 まだ持っていないので、「null」に設定されています。
資格情報を正しく提供した場合、応答が返されます。 API にはユーザー認証トークンが含まれます。
レスポンスオブジェクトには次のプロパティが含まれます。
-jsonrpc - 繰り返しになりますが、JSON-RPCプロトコルのバージョン。 -result - メソッドによって返されたデータ。 -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 server" に新しいアイテムを作成してみましょう。 これは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 が含まれます。これは、以降の要求でアイテムを参照するために使用できます。
なお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 が含まれます。
アイテムの更新
アイテムを有効にします。つまりstatusを"0"に設定します。
{
"jsonrpc": "2.0",
"method": "item.update",
"params": {
"itemid": "10092",
"status": 0
},
"auth": "0424bd59b807674191e7d77572075f33",
"id": 5
}更新が成功した応答には、更新されたアイテムの ID が含まれます。
なお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 が含まれます。
これは、推奨される更新方法です。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 のリスト を参照することをお勧めします。