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.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
}

認証方法

認証ヘッダー

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

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

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

Zabbix 7.0.7以降、認証ヘッダーはクロスオリジンリクエストでサポートされています(CORS)。 Zabbix 7.0.11以降、Zabbix APIはケースに依存しない方法でヘッダーを受け入れます(例えば、authorization、Authorization、およびAUTHORIZATIONは同じように扱われます)。

`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 メソッドを使用すると、設定済みのすべてのホストの 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

概要

構成