[comment]: # translation:outdated [comment]: # ({92f30379-92f30379}) # 19. API [comment]: # ({/92f30379-92f30379}) [comment]: # ({f3807be5-13405b49}) ### 概要 Zabbix APIを使用すると、Zabbixの設定をプログラムで取得および変更でき、ヒストリデータへのアクセスが可能になります。 次の目的で広く使用されています。 - Zabbixと連携する新しいアプリケーションを作成する - Zabbixをサードパーティソフトウェアと統合する - ルーチンタスクを自動化する Zabbix APIはWebベースのAPIであり、Webフロントエンドの一部として発送されます。JSON-RPC 2.0プロトコルを使用し、次の2つのことを意味します。 - APIは一連の個別メソッドで構成されている - クライアントとAPI間の要求と応答は、JSON形式を使用してエンコードされる プロトコルとJSONの詳細については、[JSON-RPC 2.0 仕様](http://www.jsonrpc.org/specification) と [JSON形式のホームページ](http://json.org/) を参照してください。 Zabbix機能をPythonアプリケーションに統合する方法の詳細については、Zabbix APIのPythonライブラリ[zabbix_utils](https://github.com/zabbix/python-zabbix-utils)を参照してください。 [comment]: # ({/f3807be5-13405b49}) [comment]: # ({9cb56d09-9cb56d09}) ### 構造 APIは、名目上、別々のAPIにグループ化された多数のメソッドから構成されています。それぞれのメソッドはある特定のタスクを実行します。例えば、`host.create`メソッドは*host* APIに属し、新しいホストを作成に使用されます。歴史的には、APIは"クラス"と呼ばれることもあります。 ::: notetip ほとんどのAPIは、少なくとも`get`, `create`, `update`, `delete`という4つのメソッドを持ち、それぞれデータの取得、作成、更新、削除を行います。しかし、一部のAPIでは、全く別のメソッドを提供することもあります。 ::: [comment]: # ({/9cb56d09-9cb56d09}) [comment]: # ({e4e06a45-9cb2f5ca}) ### リクエストの実行 フロントエンドを設定したら、リモートHTTPリクエストを使用してAPIを呼び出すことができます。 これを行うには、フロントエンドディレクトリにある`api_jsonrpc.php`ファイルにHTTP POSTリクエストを送信する必要があります。 たとえば、Zabbixフロントエンドが *http://example.com/zabbix* にインストールされている場合、`apiinfo.version`メソッドを呼び出すHTTPリクエストは次のようになります。 ```yaml 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`のいずれかの値に設定されている必要があります。 [comment]: # ({/e4e06a45-9cb2f5ca}) [comment]: # ({ec5a9f60-ec5a9f60}) ### ワークフローの例 次のセクションでは、いくつかの使用例をより詳細に説明します。 [comment]: # ({/ec5a9f60-ec5a9f60}) [comment]: # ({041d4e6e-ef3f5841}) #### 認証 Zabbixのデータにアクセスするには、次のどちらかを行う必要があります。 - 既存の[APIトークン](/manual/web_interface/frontend_sections/administration/general#api-tokens)を使用(Zabbixフロントエンドまたは[トークンAPI](/manual/api/reference/token)を使用して作成); - [user.login](/manual/api/reference/user/login)メソッドで取得した認証トークンを使用。 たとえば、標準の*Admin*ユーザーとしてログインして新しい認証トークンを取得したい場合、JSON リクエストは次のようになります。 ```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によって返される応答にはユーザー認証トークンが含まれます。 ```json { "jsonrpc": "2.0", "result": "0424bd59b807674191e7d77572075f33", "id": 1 } ``` レスポンスオブジェクトには次のプロパティが含まれます。 - `jsonrpc` - 繰り返しになりますが、JSON-RPCプロトコルのバージョン。 - `result` - メソッドによって返されたデータ。 - `id` - 対応するリクエストのID。 [comment]: # ({/041d4e6e-ef3f5841}) [comment]: # ({61809060-f572ecc2}) #### ホストの取得 Zabbixのデータにアクセスするために使用できる有効なユーザー認証トークンを取得できました。 次に例として、[host.get](/manual/api/reference/host/get)メソッドを使用して、構成されているすべての[ホスト](/manual/api/reference/host/object)のID、ホスト名、およびインターフェースを取得してみましょう。 ```json { "jsonrpc": "2.0", "method": "host.get", "params": { "output": [ "hostid", "host" ], "selectInterfaces": [ "interfaceid", "ip" ] }, "id": 2, "auth": "0424bd59b807674191e7d77572075f33" } ``` ::: noteimportant `auth`プロパティに`user.login`を呼び出して取得した認証トークンを設定するよう注意してください。 ::: レスポンスオブジェクトには、要求されたホストに関するデータが含まれます。 ```json { "jsonrpc": "2.0", "result": [ { "hostid": "10084", "host": "Zabbix server", "interfaces": [ { "interfaceid": "1", "ip": "127.0.0.1" } ] } ], "id": 2 } ``` ::: notetip パフォーマンス上の理由から、取得するオブジェクトプロパティを常にリストアップし、すべてのオブジェクトプロパティを取得しないようにすることをお勧めします。 ::: [comment]: # ({/61809060-f572ecc2}) [comment]: # ({e4c060f4-ee2c324f}) #### 新しいアイテムの作成 先ほどの`host.get`リクエストで取得したデータを使って、"Zabbixサーバー" に新しい[アイテム](/manual/api/reference/item/object)を作成してみましょう。 これは[item.create](/manual/api/reference/item/create)メソッドを使用して実行できます。 ```json { "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が含まれます。これは、以降のリクエストでアイテムを参照するために使用できます。 ```json { "jsonrpc": "2.0", "result": { "itemids": [ "24759" ] }, "id": 3 } ``` ::: notetip なお`item.create`メソッドや他のcreateメソッドも、オブジェクトの配列を受け入れて、1 回のAPI呼び出しで複数のアイテムを作成することもできます。 ::: [comment]: # ({/e4c060f4-ee2c324f}) [comment]: # ({e511a956-5ed44978}) #### 複数のトリガーの作成 したがって、createメソッドが配列を受け入れる場合、次のように複数の[トリガー](/manual/api/reference/trigger/object)を追加することも可能です。 ```json { "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が含まれます。 ```json { "jsonrpc": "2.0", "result": { "triggerids": [ "17369", "17370" ] }, "id": 4 } ``` [comment]: # ({/e511a956-5ed44978}) [comment]: # ({2a515812-aa174634}) #### アイテムの更新 アイテムを有効にします。つまりstatusを"0"に設定します。 ```json { "jsonrpc": "2.0", "method": "item.update", "params": { "itemid": "10092", "status": 0 }, "auth": "0424bd59b807674191e7d77572075f33", "id": 5 } ``` 更新が成功したレスポンスには、更新されたアイテムのIDが含まれます。 ```json { "jsonrpc": "2.0", "result": { "itemids": [ "10092" ] }, "id": 5 } ``` ::: notetip `item.update`メソッドやその他のupdateメソッドは、オブジェクトの配列を受け入れ、1回のAPI呼び出しで複数のアイテムを更新することができます。 ::: [comment]: # ({/2a515812-aa174634}) [comment]: # ({3772c85a-e217b4a2}) #### 複数のトリガーの更新 複数のトリガーを有効にします。つまりstatusを 0 に設定します。 ```json { "jsonrpc": "2.0", "method": "trigger.update", "params": [ { "triggerid": "13938", "status": 0 }, { "triggerid": "13939", "status": 0 } ], "auth": "0424bd59b807674191e7d77572075f33", "id": 6 } ``` 更新が成功した応答には、更新されたトリガーの ID が含まれます。 ```json { "jsonrpc": "2.0", "result": { "triggerids": [ "13938", "13939" ] }, "id": 6 } ``` ::: notetip これは、推奨される更新方法です。`host.massupdate`などの一部の API メソッドを使用すると、より単純なコードを記述できますが、これらのメソッドは将来のリリースで削除される予定のため、使用は推奨されません。 ::: [comment]: # ({/3772c85a-e217b4a2}) [comment]: # ({0ba3cefc-7665e280}) #### エラーハンドリング 今まで試したメソッドはすべて成功しました。しかし、API に対して間違った呼び出しを行おうとするとどうなるでしょうか？[host.create](/manual/api/reference/host/create) を呼び出して別のホストを作成する際に、必須の `groups` パラメータを省略してみましょう。 ```json { "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" } ``` レスポンスにはエラー メッセージが含まれます。 ```json { "jsonrpc": "2.0", "error": { "code": -32602, "message": "Invalid params.", "data": "No groups for host \"Linux server\"." }, "id": 7 } ``` エラーが発生した場合、レスポンスオブジェクトには`result` プロパティの代わりに、次のデータを持つ `error` プロパティが含まれます。 - `code` - エラーコード - `message` - 簡単なエラーの要約 - `data` - より詳細なエラー メッセージ エラーは、誤った入力値の使用、セッション タイムアウト、または存在しないオブジェクトへのアクセス試行など、さまざまなケースで発生する可能性があります。 アプリケーションは、この種のエラーを適切に処理する必要があります。 [comment]: # ({/0ba3cefc-7665e280}) [comment]: # ({db15f318-c1074d48}) ### APIバージョン APIのバージョン管理を簡素化するために、Zabbix 2.0.4以降、APIのバージョンはZabbix自体のバージョンと一致していますが、[apiinfo.version](/manual/api/reference/apiinfo/version) メソッドを使用して、使用している API のバージョンを確認することもできます。 これは、バージョン固有の機能を使用するようにアプリケーションを調整する場合に役立ちます。 メジャー バージョン内では、機能の下位互換性を保証します。 メジャー リリース間で下位互換性のない変更を行う場合、通常は古い機能を次のリリースで非推奨として残し、その後のリリースで削除します。 場合によっては、下位互換性を提供せずにメジャー リリース間で機能を削除することもあります。 非推奨の機能には決して依存せず、できるだけ早く新しい代替機能に移行することが重要です。 ::: notetip [API 変更ログ](/manual/api/changes_5.4_-_6.0) で、API に加えられたすべての変更を追うことができます。 ::: [comment]: # ({/db15f318-c1074d48}) [comment]: # ({dfd7315f-dfd7315f}) ### 参考文献 ここまでで Zabbix API を使い始めるのに十分な知識が得られましたが、これが全てではありません。更に詳しく知りたい場合は、[利用可能な API のリスト](/manual/api/reference) を参照することをお勧めします。 [comment]: # ({/dfd7315f-dfd7315f})