[comment]: # ({7cef99ec-92f30379})
# 20 API

[comment]: # ({/7cef99ec-92f30379})

[comment]: # ({d9e959c3-13405b49})
### 概要

Zabbix APIを使用すると、Zabbixの設定をプログラムで取得・変更したり、履歴データにアクセスしたりできます。
主に以下の用途で広く利用されています。

-   Zabbixと連携する新しいアプリケーションの作成
-   サードパーティ製ソフトウェアへのZabbixの統合
-   定型作業の自動化

Zabbix APIはHTTPベースのAPIであり、Webインターフェースの一部として提供されています。
JSON-RPC 2.0プロトコルを使用しており、これは以下の2点を意味します。

-   APIは個別のメソッドの集合で構成されている
-   クライアントとAPI間のリクエストおよびレスポンスはJSON形式でエンコードされる

プロトコルやJSONの詳細については、[JSON-RPC 2.0仕様](http://www.jsonrpc.org/specification)および[JSONフォーマットのホームページ](http://json.org/)を参照してください。

PythonアプリケーションにZabbixの機能を統合する方法については、[Zabbix用Pythonライブラリ](/devel/python)を参照してください。

::: noteclassic
Zabbixにおけるユーザーのアクセス権（設定・履歴データの両方）は、[ユーザータイプ](/manual/config/users_and_usergroups/permissions#user-types)、割り当てられた[ユーザーロール](/manual/config/users_and_usergroups/permissions#user-roles)、および[ユーザーグループ](/manual/config/users_and_usergroups/usergroup)によって決まります。
:::

[comment]: # ({/d9e959c3-13405b49})

[comment]: # ({76e2a1dd-9cb56d09})
### 構造

APIは、名目上、別々のAPIにグループ化された多数のメソッドから構成されています。それぞれのメソッドはある特定のタスクを実行します。例えば、`host.create`メソッドは*host* APIに属し、新しいホストを作成に使用されます。歴史的には、APIは"クラス"と呼ばれることもあります。

::: notetip
ほとんどのAPIは、少なくとも`get`, `create`, `update`, `delete`という4つのメソッドを持ち、それぞれデータの取得、作成、更新、削除を行います。しかし、一部のAPIでは、全く別のメソッドを提供することもあります。
:::

[comment]: # ({/76e2a1dd-9cb56d09})

[comment]: # ({d3a7ab69-9cb2f5ca})
### リクエストの実行

Webインターフェースをセットアップしたら、リモート HTTP リクエストを使用して API を呼び出せます。そのためには、Webインターフェースディレクトリ内にある `api_jsonrpc.php` ファイルへ HTTP POST リクエストを送信する必要があります。たとえば、Zabbix の Webインターフェースが `https://example.com/zabbix` にインストールされている場合、`apiinfo.version` メソッドを呼び出す HTTP リクエストは次のようになります。

```bash
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](https://www.jsonrpc.org/specification#notification) として扱います）。

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

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

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

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

[comment]: # ({/d3a7ab69-9cb2f5ca})

[comment]: # ({c36376e5-ec5a9f60})
### ワークフローの例

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

[comment]: # ({/c36376e5-ec5a9f60})

[comment]: # ({17ec6118-ef3f5841})
#### 認証

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

-   既存の[APIトークン](/manual/web_interface/frontend_sections/users/api_tokens)を使用(Zabbixフロントエンドまたは[トークンAPI](/manual/api/reference/token)を使用して作成)
-   [user.login](/manual/api/reference/user/login)メソッドで取得した認証トークンを使用。

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

```bash
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 から返されるレスポンスにはユーザー認証トークンが含まれているはずです。

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

[comment]: # ({/17ec6118-ef3f5841})

[comment]: # ({d920bab8-37011a71})
#### 認証方法

[comment]: # ({/d920bab8-37011a71})

[comment]: # ({78bcb6bc-130188f5})
##### "Authorization" ヘッダーによる認証

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

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

::: noteimportant
認証に問題がある場合は、[Authorizationヘッダーの転送](/manual/installation/known_issues#authorization-header-forwarding)を参照してください。
:::

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

Authorizationヘッダーはクロスオリジンリクエスト([CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS))でもサポートされています。

[comment]: # ({/78bcb6bc-130188f5})

[comment]: # ({8a583b03-8950965e})
##### Zabbixクッキー

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

[comment]: # ({/8a583b03-8950965e})

[comment]: # ({7f924528-f572ecc2})
#### ホストの取得

これで、Zabbixのデータにアクセスするために使用できる有効なユーザー認証トークン（以下の例では変数として表現）が取得できました。たとえば、[host.get](/manual/api/reference/host/get)メソッドを使用して、すべての設定済み[ホスト](/manual/api/reference/host/object)のID、ホスト名、インターフェースを取得できます。

リクエスト:

```bash
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
```

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

data.json

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

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

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

::: notetip
パフォーマンス上の理由から、取得したいオブジェクトプロパティを常にリストアップすることを推奨します。これにより、すべてを取得することを避けられます。
:::

[comment]: # ({/7f924528-f572ecc2})

[comment]: # ({c9fda4ae-ee2c324f})
#### 新しいアイテムの作成

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

```bash
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が含まれます。これは、以降のリクエストでアイテムを参照するために使用できます。

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

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

[comment]: # ({/c9fda4ae-ee2c324f})

[comment]: # ({49a2cbe1-5ed44978})
#### Creating multiple triggers

したがって、*createメソッド*が配列を受け入れる場合、次のように複数の[トリガー](/manual/api/reference/trigger/object)を追加することも可能です。


```bash
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が含まれます。

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

[comment]: # ({/49a2cbe1-5ed44978})

[comment]: # ({07f914b6-aa174634})
#### アイテムの更新

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

```bash
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が含まれます。

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

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

[comment]: # ({/07f914b6-aa174634})

[comment]: # ({bfbd84bd-e217b4a2})
#### 複数のトリガーの更新

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

```bash
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が含まれます:

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

::: notetip
これは、更新の推奨方法です。`host.massupdate` などの一部のAPIメソッドを使用すると、より簡潔なコードを記述できます。
ただし、これらのメソッドは将来のリリースで削除されるため、使用は推奨されません。
:::

[comment]: # ({/bfbd84bd-e217b4a2})

[comment]: # ({a9952ff9-7665e280})
#### エラーハンドリング

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

```bash
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}'
```

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

```json
{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "Invalid params.",
        "data": "No groups for host \"Linux server\"."
    },
    "id": 7
}
```

エラーが発生した場合、レスポンスオブジェクトには`result`プロパティの代わりに、次のデータを持つ`error`プロパティが含まれます。

-   `code` - エラーコード
-   `message` - エラーの概要
-   `data` - 詳細なエラーメッセージ

エラーは、不正な入力値の使用、セッションタイムアウト、存在しないオブジェクトへのアクセスの試行など、さまざまなケースで発生する可能性があります。アプリケーションは、この種のエラーを適切に処理できる必要があります。

[comment]: # ({/a9952ff9-7665e280})

[comment]: # ({0de672ce-c1074d48})
### APIバージョン

APIのバージョン管理を簡素化するために、Zabbix 2.0.4以降、APIのバージョンはZabbix自体のバージョンと一致していますが、[apiinfo.version](/manual/api/reference/apiinfo/version)メソッドを使用して、使用しているAPIのバージョンを確認することもできます。 これは、バージョン固有の機能を使用するようにアプリケーションを調整する場合に役立ちます。

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

::: notetip
[API変更ログ](/manual/api/changes) で、APIに加えられたすべての変更を追うことができます。
:::

[comment]: # ({/0de672ce-c1074d48})

[comment]: # ({77690bd2-dfd7315f})
### 参考文献

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

[comment]: # ({/77690bd2-dfd7315f})