Table of Contents

19. API

19. API

概要

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

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

Zabbix APIはHTTPベースの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リクエストは次のようになります。

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"jsonrpc":"2.0","method":"apiinfo.version","params":{},"id":1}'

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

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

jsonrpc - APIで使用されるJSON-RPCプロトコルのバージョン (Zabbix APIはJSON-RPCのバージョン2.0を実装しています)
method - 呼び出されるAPIメソッド
params - APIメソッドに渡されるパラメーター
id - リクエストの任意のID

リクエストが正しい場合、APIから返されるレスポンスは次のようになります。

{
           "jsonrpc": "2.0",
           "result": "6.4.0",
           "id": 1
       }

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

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

ワークフローの例

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

認証

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

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

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

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"jsonrpc":"2.0","method":"user.login","params":{"username":"Admin","password":"zabbix"},"id":1}'

資格情報を正しく指定した場合、API から返されるレスポンスにはユーザー認証トークンが含まれているはずです。

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

認証方法

"Authorization"ヘッダー

すべてのAPIリクエストには認証またはAPIトークンが必要です。 "Authorization"リクエストヘッダーを使用して資格情報を指定できます。

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Authorization: Bearer 0424bd59b807674191e7d77572075f33'

"auth"プロパティ

APIリクエストは、"auth"プロパティによって認証できます。

"auth"プロパティは非推奨であることに注意してください。将来のリリースでは削除される予定です。

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"jsonrpc":"2.0","method":"host.get","params":{"output":["hostid"]},"auth":"0424bd59b807674191e7d77572075f33","id":1}'

Zabbixクッキー

"zbx_session"クッキーは、(モジュールまたはカスタムウィジェットから) JavaScript を使用して実行される Zabbix UIからのAPIリクエストを承認するために使用されます。

ホストの取得

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

リクエスト :

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
         --header 'Content-Type: application/json-rpc' \
         --data @data.json

data.jsonは、JSONクエリを含むファイルです。ファイルの代わりにクエリを--data引数で渡すことができます。

data.json

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

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

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

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

新しいアイテムの作成

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

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"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},"id":3}'

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

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

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

Creating multiple triggers

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

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"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",}],"id":4}'

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

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

アイテムの更新

アイテムのステータスを"0"に設定することで、アイテムを有効にします。

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"jsonrpc":"2.0","method":"item.update","params":{"itemid":"10092","status":0},"id":5}'

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

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

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

複数のトリガーの更新

ステータスを"0"に設定して、複数のトリガーを有効にします。

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"jsonrpc":"2.0","method":"trigger.update","params":[{"triggerid":"13938","status":0},{"triggerid":"13939","status":0}],"id":6}'

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

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

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

エラーハンドリング

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

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"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}'

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

{
           "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のバージョンを確認することもできます。これは、バージョン固有の機能を使用するようにアプリケーションを調整する場合に役立ちます。

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

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

参考文献

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

Documentation