This is a translation of the original English documentation page. Help us make it better.

Sidebar

Zabbix Summit 2022
Register for Zabbix Summit 2022

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://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": "2.0",
           "result": "0424bd59b807674191e7d77572075f33",
           "id": 1
       }

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

  • 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 が含まれます。これは、以降の要求でアイテムを参照するために使用できます。

{
           "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 のリスト を参照することをお勧めします。