フロントエンドをセットアップしたら、リモートHTTPリクエストを使用してAPIを呼び出すことができます。そのためには、フロントエンドディレクトリにあるapi_jsonrpc.phpファイルにHTTP POSTリクエストを送信する必要があります。たとえば、Zabbixフロントエンドがhttps://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 - リクエストの任意の識別子（省略した場合、APIはリクエストを通知として扱います）。

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

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

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

jsonrpc - JSON-RPCプロトコルのバージョン;
result - メソッドによって返されるデータ;
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'

認証に問題がある場合は、Authorizationヘッダーの転送を参照してください。

Zabbix APIはヘッダーを大文字・小文字を区別せずに受け付けます（例: authorization、Authorization、AUTHORIZATIONは同じものとして扱われます）。

Authorizationヘッダーはクロスオリジンリクエスト(CORS)でもサポートされています。

Zabbixクッキー

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

ホストの取得

これで、Zabbixのデータにアクセスするために使用できる有効なユーザー認証トークン（以下の例では変数として表現）が取得できました。たとえば、host.getメソッドを使用して、すべての設定済みホストの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
}

エラーハンドリング

今まで試したメソッドはすべて成功しました。しかし、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のリストを参照することをお勧めします。

What’s next?

メソッドリファレンス

Docs

18 API

概要

構造

リクエストの実行