Zabbix API を使用すると、Zabbix の設定をプログラムで取得して変更し、ヒストリデータへのアクセスを提供できます。 次の目的で広く使用されています。
Zabbix API は Web ベースの API であり、Web フロントエンドの一部として出荷され、SON-RPC 2.0 プロトコルを使用します。これは、次の 2 つのことを意味します。
プロトコルと JSON の詳細については、JSON-RPC 2.0 仕様 と JSON 形式のホームページ を参照してください。
このAPIは、名目上、別々のAPIにグループ化された多数のメソッドから構成されています。それぞれのメソッドはある特定のタスクを
実行します。例えば、host.create
メソッドは host API に属し、新しいホストを作成するために使用されます。歴史的には、APIは
"classes"と呼ばれることもある。
ほとんどの API は、少なくとも get
, create
, update
, delete
という 4 つのメソッドを持ち、それぞれデータの取得、作成、更新、削除を
行います。しかし、一部の API では、全く別のメソッドを提供することもあります。
Webインターフェースをセットアップしたら、リモートHTTP リクエストを使用してAPIを呼び出すことができます。これを行うには、Webインターフェースのディレクトリにある api_jsonrpc.php
ファイルに HTTP POST リクエストを送信する必要があります。例えば、ZabbixのWebインターフェースが http://company.com/zabbix にインストールされている場合、apiinfo.version
メソッドを呼び出すためのHTTPリクエストは以下のようになります。
POST http://company.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 内のデータにアクセスするには、ログインして認証トークンを取得する必要があります。これは、user.login メソッドを使用して実行できます。標準の管理者ユーザーとしてログインする場合、JSON リクエストは次のようになります。
{
"jsonrpc": "2.0",
"method": "user.login",
"params": {
"user": "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
- 対応するリクエストの識別子。All API requests require an authentication or an API token. You can provide the credentials by using the "Authorization" request header:
curl --request POST \
--url 'https://company.com/zabbix/ui/api_jsonrpc.php' \
--header 'Authorization: Bearer 0424bd59b807674191e7d77572075f33'
An API request can be authorized by the "auth" property.
Note that the "auth" property is deprecated. It will be removed in the future releases.
curl --request POST \
--url 'https://company.com/zabbix/ui/api_jsonrpc.php' \
--header 'Content-Type: application/json-rpc' \
--data '{"jsonrpc":"2.0","method":"host.get","params":{"output":["hostid"]},"auth":"0424bd59b807674191e7d77572075f33","id":1}'
A "zbx_session" cookie is used to authorize an API request from Zabbix UI performed using JavaScript (from a module or a custom widget).
ホストの取得
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のバージョン管理を簡素化するために、Zabbix 2.0.4以降、APIのバージョンはZabbix自体のバージョンと一致していますが、apiinfo.version メソッドを使用して、使用している API のバージョンを確認することもできます。 これは、バージョン固有の機能を使用するようにアプリケーションを調整する場合に役立ちます。
メジャー バージョン内では、機能の下位互換性を保証します。 メジャー リリース間で下位互換性のない変更を行う場合、通常は古い機能を次のリリースで非推奨として残し、その後のリリースで削除します。 場合によっては、下位互換性を提供せずにメジャー リリース間で機能を削除することもあります。 非推奨の機能には決して依存せず、できるだけ早く新しい代替機能に移行することが重要です。
API 変更ログ で、API に加えられたすべての変更を追うことができます。
ここまでで Zabbix API を使い始めるのに十分な知識が得られましたが、これが全てではありません。更に詳しく知りたい場合は、利用可能な API のリスト を参照することをお勧めします。