使用 Zabbix API

zabbix_utils 让您能够使用 Zabbix API 来管理 Zabbix 对象，包括创建主机、更新监控项、检索事件等。

API 请求可以以同步或异步模式发出：

• 在同步模式下，您的 Python 脚本会发送请求，并在继续执行之前等待响应，这适用于简单、顺序且可预测的操作。
• 在异步模式下，脚本发送请求时不会等待每个响应，从而允许其他操作并行进行；对于响应较慢的请求或大批量数据，这种方式效率更高。

本页中的示例重点介绍同步模式，不过异步模式遵循类似的模式。 更多示例可在 zabbix_utils GitHub 仓库中找到。

导入

要使用 zabbix_utils 通过 Zabbix API 进行操作，请在您的脚本中导入 ZabbixAPI 类：

from zabbix_utils import ZabbixAPI

登录

在发出 API 请求之前，您必须创建一个 ZabbixAPI 实例并登录 Zabbix API。

请选择最适合您管理凭据方式的方法。 您可以使用用户名和密码，或使用 API 令牌。

初始化期间

创建 ZabbixAPI 实例时，您可以一次性提供 Zabbix Web 界面 URL 和您的凭据：

# 用户名和密码：
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)

使用 login()

您可以先仅使用 Zabbix Web 界面 URL 创建一个 ZabbixAPI 实例，然后再使用您的凭据调用 login() 方法：

# 用户名和密码：
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")

使用环境变量

您可以先将凭据存储为环境变量，例如通过终端执行：

# 用户名和密码：
export ZABBIX_USER="Admin"
export ZABBIX_PASSWORD="zabbix"

# Token：
export ZABBIX_TOKEN="your_api_token"

然后，如果您从同一个终端会话启动脚本，脚本中的 ZabbixAPI 实例只需要 Zabbix Web 界面的 URL：

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

您还可以将 URL 存储在环境变量中：

# 用户名和密码：
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 实例将完全不需要任何参数：

api = ZabbixAPI()

注销

如果您使用用户名和密码登录，请在完成 API 操作后调用 logout() 方法：

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()

API 请求

登录后，您可以通过调用 Zabbix API 方法参考中描述的方法发起任何 API 请求。

API 方法使用以下格式调用：

api_instance.zabbix_object.method(parameters)

例如，要使用 host.get 查看主机列表：

# 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()

异步模式

异步模式允许您的脚本发送 API 请求时无需等待每个请求完成。 当脚本需要执行大量 API 请求，或者某些请求耗时较长时，这可以让脚本更高效。

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

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

例如，要在异步模式下使用 host.get 查看主机列表：

# 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())

示例

以下示例展示了使用 zabbix_utils 库执行常见 Zabbix API 任务的方法。

更多示例可在 zabbix_utils GitHub 仓库的 examples 目录中找到。