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": "8.0.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、ホスト名、およびインターフェースを取得できます。

Request:

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
}

エラー処理

これまでのところ、試したことはすべて正常に動作していました。
しかし、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

API

概要

構成