APIは、名目上は個別のAPIにグループ化された多数のメソッドで構成されています。
各メソッドは、1つの特定のタスクを実行します。
たとえば、host.create メソッドは host API に属し、新しいホストを作成するために使用されます。
歴史的に、APIは「クラス」と呼ばれることもあります。

ほとんどのAPIには少なくとも4つのメソッドがあります。get、create、update、delete で、それぞれデータの取得、作成、更新、削除を行いますが、APIによってはまったく異なるメソッドセットを提供する場合もあります。

リクエストの実行

Webインターフェースをセットアップしたら、リモート HTTP リクエストを使用して API を呼び出せます。そのためには、Webインターフェースディレクトリにある api_jsonrpc.php ファイルに HTTP POST リクエストを送信する必要があります。
たとえば、Zabbix の Webインターフェースが 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 はこのリクエストを notification として扱います）。

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

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

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

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

認証

Zabbix のデータにアクセスするには、次のいずれかを使用する必要があります。

Zabbix Webインターフェースの Users > API tokens セクションで作成された既存の API トークン、または Token API を使用して作成された 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 server" に新しいアイテムを作成します。
これは、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 が含まれます。この ID は、以降のリクエストでアイテムを参照するために使用できます。

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

item.create メソッドは、他の create methods と同様に、オブジェクトの配列も受け付け、1 回の API 呼び出しで複数のアイテムを作成できます。

複数のトリガーの作成

したがって、create methods が配列を受け入れる場合、複数のトリガーを追加できます。たとえば、次のようにします。

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 メソッドは、他の 更新メソッド と同様に、オブジェクトの配列も受け入れることができ、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は、メジャーバージョン内での機能の後方互換性を保証します。メジャーリリース間で後方互換性のない変更を行う場合、Zabbixは通常、次のリリースで古い機能を非推奨として残し、その次のリリースでのみ削除します。場合によっては、Zabbixがメジャーバージョン間で後方互換性を提供せずに機能を削除することもあります。非推奨の機能には依存せず、できるだけ早く新しい代替手段へ移行することが重要です。

API changelog で、APIに加えられたすべての変更を確認できます。

参考資料

これで、Zabbix API の利用を始めるのに十分な知識が身につきましたが、ここで終わりではありません。
さらに学習を進めるには、利用可能な API の一覧をご覧ください。

What’s next?

メソッドリファレンス

Docs

20 API

概要

構成