使用 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 tokens。

在初始化期间

在创建 ZabbixAPI 实例时，您可以一次性提供 Zabbix web 前端 URL 和您的凭据：

# 用户名和密码：
api = ZabbixAPI(url="127.0.0.1/zabbix", user="Admin", password="zabbix")

# API token：
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 前端 URL 创建一个 ZabbixAPI 实例，然后再使用您的凭据调用 login() 方法：

# 用户名和密码：
api = ZabbixAPI(url="127.0.0.1/zabbix")
api.login(user="Admin", password="zabbix")

# API token：
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. Import asyncio for asynchronous mode, and AsyncZabbixAPI from zabbix_utils:
import asyncio
from zabbix_utils import AsyncZabbixAPI

# 2. Define the main async function where all API operations will run:
async def main():

    # 3. Create an AsyncZabbixAPI instance and log in (must await):
    api = AsyncZabbixAPI(url="127.0.0.1")
    await api.login(user="User", password="zabbix")

    # 4. Retrieve hosts matching a filter (must await):
    hosts = await api.host.get(
        filter={
            "host": [
                "Zabbix server",
                "Linux server"
            ]
        }
    )

    # 5. Iterate over returned hosts and print each host's details:
    for host in hosts:
        print(host)

    # 6. Log out from the API to close the session (must await):
    await api.logout()

# 7. Run the async main() function using asyncio's event loop:
asyncio.run(main())

示例

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

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