[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)遵循类似的模式。
更多示例可在 [zabbix_utils](https://github.com/zabbix/python-zabbix-utils/tree/main/examples) GitHub 仓库中找到。

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

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

要使用 zabbix\_utils 通过 Zabbix API 进行操作，请在您的脚本中导入 `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 的关键字参数语法将其解包：

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

# Token：
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"

# Token：
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 actions go here

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 报错，在 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 请求，或者某些请求耗时较长时，这可以让脚本更高效。

使用异步模式时，与同步模式相比有以下重要区别：

-   导入 Python 的 `asyncio` 模块（您必须先[安装](/devel/python/install)所需的依赖）。
-   导入 `AsyncZabbixAPI`，而不是 `ZabbixAPI`。
-   在 `async` 函数中编写代码。
-   调用 API 方法时使用 `await`，包括 `login()` 和 `logout()`。

::: 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. 定义主 async 函数，所有 API 操作都将在其中运行：
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})