[comment]: # aside:3

[comment]: # ({d1748010-ebcec779})
# Zabbix APIの使用

[zabbix\_utils](https://github.com/zabbix/python-zabbix-utils/blob/main/README.md)を使用すると、[Zabbix API](/manual/api)を利用して、ホストの作成、アイテムの更新、イベントの取得など、Zabbixオブジェクトを管理できます。

APIリクエストは同期モードまたは非同期モードで実行できます。

-   同期モードでは、Pythonスクリプトがリクエストを送信し、応答を待ってから次に進みます。これは、単純で順次的かつ予測可能な操作に適しています。
-   非同期モードでは、スクリプトは各応答を待たずにリクエストを送信し、他の操作を並行して進めることができます。これは、遅いリクエストや大量のデータを扱う場合により効率的です。

このページの例は同期モードに焦点を当てていますが、[非同期モード](#asynchronous-mode)も同様のパターンに従います。
追加の例は[GitHubのzabbix_utils](https://github.com/zabbix/python-zabbix-utils/tree/main/examples)リポジトリにあります。

[comment]: # ({/d1748010-ebcec779})

[comment]: # ({3d27f26b-8304e91c})
#### インポート

Zabbix APIを操作するためにzabbix\_utilsを使用するには、スクリプト内で`ZabbixAPI`クラスをインポートします:

```python
from zabbix_utils import ZabbixAPI
```

::: noteclassic
すでに[コミュニティのPythonライブラリ](https://www.zabbix.com/integrations/python)を使用している場合は、そのインポートをzabbix\_utilsの`ZabbixAPI`に置き換えることができます。
:::

[comment]: # ({/3d27f26b-8304e91c})

[comment]: # ({55f43c13-2fe24fc5})
#### ログイン

APIリクエストを行う前に、`ZabbixAPI`インスタンスを作成し、Zabbix APIにログインする必要があります。

資格情報の管理方法に最適な方法を選択してください。
ユーザー名とパスワード、または[APIトークン](/manual/web_interface/frontend_sections/users/api_tokens)を使用できます。

[comment]: # ({/55f43c13-2fe24fc5})

[comment]: # ({eecbd507-f5ed9f85})
##### 初期化時

`ZabbixAPI`インスタンスを作成する際に、Zabbix WebインターフェースのURLと認証情報を一度に指定できます。

```python
# ユーザー名とパスワード:
api = ZabbixAPI(url="127.0.0.1/zabbix", user="Admin", password="zabbix")

# APIトークン:
api = ZabbixAPI(url="127.0.0.1/zabbix", token="your_api_token")
```

接続パラメータをまとめて管理したい場合は、Pythonの辞書として渡し、キーワード引数のアンパック構文を使うこともできます。

```python
ZABBIX_AUTH = {
    "url": "127.0.0.1/zabbix",
    "user": "Admin",
    "password": "zabbix"
}

api = ZabbixAPI(**ZABBIX_AUTH)
```

[comment]: # ({/eecbd507-f5ed9f85})

[comment]: # ({5cb46e5e-3bf35a85})
##### `login()`の使用

まず、Zabbix WebインターフェースのURLだけで`ZabbixAPI`インスタンスを作成し、後で認証情報を使って`login()`メソッドを使用できます。

```python
# ユーザー名とパスワード:
api = ZabbixAPI(url="127.0.0.1/zabbix")
api.login(user="Admin", password="zabbix")

# APIトークン:
api = ZabbixAPI(url="127.0.0.1/zabbix")
api.login(token="your_api_token")
```

[comment]: # ({/5cb46e5e-3bf35a85})

[comment]: # ({ff280370-a8fe2b33})
##### 環境変数の使用

まず、認証情報を環境変数として保存できます。例えば、ターミナルを使用して以下のようにします。

```bash
# ユーザー名とパスワード:
export ZABBIX_USER="Admin"
export ZABBIX_PASSWORD="zabbix"

# トークン:
export ZABBIX_TOKEN="your_api_token"
```

その後、同じターミナルセッションからスクリプトを起動すれば、スクリプト内の`ZabbixAPI`インスタンスにはZabbix WebインターフェースのURLだけが必要です。

```python
api = ZabbixAPI(url="127.0.0.1/zabbix")
```

URLも環境変数に保存することができます。

```bash
# ユーザー名とパスワード:
export ZABBIX_USER="Admin"
export ZABBIX_PASSWORD="zabbix"
export ZABBIX_URL="https://127.0.0.1/zabbix"

# トークン:
export ZABBIX_TOKEN="your_api_token"
export ZABBIX_URL="https://127.0.0.1/zabbix"
```

URLと認証情報がすべて環境変数として設定されている場合、スクリプト内の`ZabbixAPI`インスタンスには引数が全く必要ありません。

```python
api = ZabbixAPI()
```

[comment]: # ({/ff280370-a8fe2b33})

[comment]: # ({b539ed93-326ac077})
#### ログアウト

ユーザー名とパスワードでログインした場合、API操作が完了したら`logout()`メソッドを呼び出してください。

```python
from zabbix_utils import ZabbixAPI

api = ZabbixAPI(url="127.0.0.1/zabbix")
api.login(user="Admin", password="zabbix")

# ここにAPIアクションを記述

api.logout()
```

::: noteclassic
APIトークンを使用している場合は、`logout()`メソッドの呼び出しは不要です。
:::

[comment]: # ({/b539ed93-326ac077})

[comment]: # ({a94d5334-e970d222})
#### APIリクエスト

ログイン後、Zabbix APIの[メソッドリファレンス](/manual/api/reference)に記載されているメソッドを呼び出すことで、任意のAPIリクエストを実行できます。

APIメソッドは、以下のフォーマットで呼び出します。

```python
api_instance.zabbix_object.method(parameters)
```

::: noteclassic
一部のZabbix APIメソッドやオブジェクト名には、Pythonの予約語（例：`import`）が使われています。
Pythonでエラーを回避するため、メソッドやオブジェクト名の末尾にアンダースコアを付けてください（例：`api.configuration.import_`）。
:::

例えば、[`host.get`](/manual/api/reference/host/get)でホストの一覧を取得するには、以下のようにします。

```python
# 1. zabbix_utilsからZabbixAPIをインポート
from zabbix_utils import ZabbixAPI

# 2. ZabbixAPIインスタンスを作成し、ログイン
api = ZabbixAPI(url="127.0.0.1/zabbix")
api.login(user="Admin", password="zabbix")

# 3. フィルタに一致するホストを取得
hosts = api.host.get(
    filter={
        "host": [
            "Zabbix server",
            "Linux server"
        ]
    }
)

# 4. 取得したホストをループし、各ホストの詳細を表示
for host in hosts:
    print(host)

# 5. APIからログアウトし、セッションを閉じる
api.logout()
```

[comment]: # ({/a94d5334-e970d222})

[comment]: # ({7b3e3f97-0e327592})
##### 非同期モード

非同期モードでは、スクリプトが各APIリクエストの完了を待たずにAPIリクエストを送信できます。
多くのAPIリクエストを実行する必要がある場合や、一部のリクエストに時間がかかる場合に、スクリプトの効率を向上させることができます。

非同期モードを使用する場合、同期モードと比較して重要な違いがあります。

-   Pythonの`asyncio`モジュールをインポートします（事前に[必要な依存関係](/devel/python/install)をインストールする必要があります）。
-   `ZabbixAPI`の代わりに`AsyncZabbixAPI`をインポートします。
-   コードを`async`関数内に記述します。
-   `login()`や`logout()`を含むAPIメソッドの呼び出し時に`await`を使用します。

::: noteimportant
`AsyncZabbixAPI`インスタンスを作成する際、[初期化時](#during-initialization)にログインすることはできません。
:::

例えば、非同期モードで[`host.get`](/manual/api/reference/host/get)を使用してホストのリストを表示するには、次のようにします。

```python
# 1. 非同期モード用にasyncioと、zabbix_utilsからAsyncZabbixAPIをインポートします:
import asyncio
from zabbix_utils import AsyncZabbixAPI

# 2. すべてのAPI操作を実行するメインのasync関数を定義します:
async def main():

    # 3. AsyncZabbixAPIインスタンスを作成し、ログインします（awaitが必要）:
    api = AsyncZabbixAPI(url="127.0.0.1")
    await api.login(user="User", password="zabbix")

    # 4. フィルターに一致するホストを取得します（awaitが必要）:
    hosts = await api.host.get(
        filter={
            "host": [
                "Zabbix server",
                "Linux server"
            ]
        }
    )

    # 5. 返されたホストを繰り返し処理し、各ホストの詳細を表示します:
    for host in hosts:
        print(host)

    # 6. APIからログアウトしてセッションを閉じます（awaitが必要）:
    await api.logout()

# 7. asyncioのイベントループを使用してasync main()関数を実行します:
asyncio.run(main())
```

[comment]: # ({/7b3e3f97-0e327592})

[comment]: # ({57854c72-5dc3bb95})
#### 例

以下の例は、zabbix\_utilsライブラリを使用した一般的なZabbix APIタスクを示しています。

追加の例は、[zabbix_utils](https://github.com/zabbix/python-zabbix-utils) GitHubリポジトリの`examples`ディレクトリにあります。

[comment]: # ({/57854c72-5dc3bb95})