[comment]: # translation:outdated

[comment]: # ({92f30379-92f30379})
# 19. API

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

[comment]: # ({4aa2112d-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/) を参照してください。

Zabbix機能をPythonアプリケーションに統合する方法の詳細については、Zabbix APIのPythonライブラリ[zabbix_utils](https://github.com/zabbix/python-zabbix-utils)を参照してください。

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

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

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

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

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

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

フロントエンドを設定したら、リモートHTTPリクエストを使用してAPIを呼び出すことができます。
これを行うには、フロントエンドディレクトリにある`api_jsonrpc.php`ファイルにHTTP POSTリクエストを送信する必要があります。
たとえば、Zabbixフロントエンドが *http://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` - リクエストの任意のID

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

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

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

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

[comment]: # ({/792528a1-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]: # ({3f5d4257-130188f5})
##### "Authorization"ヘッダー

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

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

[comment]: # ({/3f5d4257-130188f5})

[comment]: # ({0fe6c8dc-38cc7fd6})
##### "auth"プロパティ

APIリクエストは、"auth"プロパティによって認証できます。

::: noteimportant
"auth"プロパティは非推奨であることに注意してください。将来のリリースでは削除される予定です。
:::

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

[comment]: # ({/0fe6c8dc-38cc7fd6})

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

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

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

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

これで、Zabbixのデータにアクセスするために使用できる有効なユーザー認証トークンが完成しました。たとえば、[host.get](/manual/api/reference/host/get)メソッドを使用して、構成されているすべての[hosts](/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]: # ({/ff7434d9-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})