Zabbix如何通过API上传XML模板

Zabbix的监控模板是复用监控项、触发器和图形配置的核心载体，社区和官方提供了大量现成的XML模板。如果每次都要登录Web界面，手动点击导入按钮上传XML文件，在管理多套Zabbix环境或者批量分发模板时就非常低效。Zabbix API提供了configuration.import方法，可以把模板导入这件事完全脚本化，实现无人值守的自动化部署。

一、准备工作：获取API访问Token

调用任何Zabbix API方法之前，都需要先通过user.login方法获取认证Token。Zabbix 5.4之后的版本推荐使用API Token功能，可以直接在用户设置页面生成一个长期有效的Token，避免脚本里明文保存密码。无论采用哪种方式，后续所有API请求都需要在auth字段中携带这个凭证。

下面用curl演示登录获取Token的过程，请求地址是Zabbix前端的api_jsonrpc.php入口：

curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "user.login",
    "params": {
      "user": "Admin",
      "password": "zabbix"
    },
    "id": 1
  }' http://192.168.0.1/zabbix/api_jsonrpc.php

返回结果中的result字段就是一个32位的认证Token，注意Token是有有效期的，超时后需要重新登录。如果返回JSON parse error，通常是Content-Type头没有正确设置，或者是请求体中有多余的换行符导致JSON不合法。

二、构造configuration.import请求

configuration.import是模板导入的核心方法，它接收两个关键参数：format指定导入格式，值为xml表示导入XML模板；source则是模板XML文件的完整内容，注意是文件内容本身而不是文件路径，也就是说必须在脚本中先把XML文件读取出来，再作为字符串放进JSON请求体里。

另一个重要参数是rules，它是一个字典，控制各类配置元素的导入策略。例如discoveryRules设置为{"createMissing": true, "updateExisting": true}表示自动发现规则不存在时创建、存在时更新。templates这个规则项必须开启，否则模板本身不会被导入。常用的规则项如下表所示：

一个典型的导入请求示例如下，XML内容较长时建议用脚本拼接，避免手工维护JSON字符串：

{
  "jsonrpc": "2.0",
  "method": "configuration.import",
  "params": {
    "format": "xml",
    "source": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><zabbix_export>...</zabbix_export>",
    "rules": {
      "discoveryRules": {
        "createMissing": true,
        "updateExisting": true
      },
      "graphs": {
        "createMissing": true,
        "updateExisting": true
      },
      "items": {
        "createMissing": true,
        "updateExisting": true
      },
      "templates": {
        "createMissing": true,
        "updateExisting": true
      },
      "triggers": {
        "createMissing": true,
        "updateExisting": true
      }
    }
  },
  "auth": "你的Token",
  "id": 2
}

导入成功时result字段返回true。如果返回错误，常见的情况是XML模板的版本与Zabbix服务端版本不匹配，比如模板是从Zabbix 6.0导出的，而服务端是5.0，这时需要先升级服务端或者使用兼容版本的模板。

三、用Python脚本实现自动化导入

直接拼curl命令维护成本较高，用Python脚本封装会更可靠。Python的json模块会自动处理XML内容中的特殊字符转义，不需要担心引号嵌套问题。下面的脚本读取指定目录下所有XML文件，逐个调用API导入，并输出每个文件的处理结果：

import json
import glob
import requests

ZABBIX_URL = "http://192.168.0.1/zabbix/api_jsonrpc.php"
USER = "Admin"
PASSWORD = "zabbix"

def api_call(method, params, auth=None):
    payload = {
        "jsonrpc": "2.0",
        "method": method,
        "params": params,
        "id": 1
    }
    if auth:
        payload["auth"] = auth
    resp = requests.post(
        ZABBIX_URL,
        data=json.dumps(payload),
        headers={"Content-Type": "application/json-rpc"}
    )
    return resp.json()

# 第一步：登录获取Token
token = api_call("user.login", {"user": USER, "password": PASSWORD})["result"]
print("获取Token成功:", token)

# 导入规则，缺失则创建，已存在则更新
rules = {
    "templates": {"createMissing": True, "updateExisting": True},
    "items": {"createMissing": True, "updateExisting": True},
    "triggers": {"createMissing": True, "updateExisting": True},
    "graphs": {"createMissing": True, "updateExisting": True},
    "templateLinkage": {"createMissing": True},
    "templateDashboards": {"createMissing": True, "updateExisting": True}
}

# 第二步：遍历目录下的所有XML模板并导入
for xml_file in sorted(glob.glob("templates/*.xml")):
    with open(xml_file, "r", encoding="utf-8") as f:
        source = f.read()
    result = api_call("configuration.import", {
        "format": "xml",
        "source": source,
        "rules": rules
    }, auth=token)
    if "error" in result:
        print(f"导入失败 {xml_file}: {result['error']['data']}")
    else:
        print(f"导入成功 {xml_file}")

# 第三步：退出登录释放会话
api_call("user.logout", [], auth=token)

这个脚本可以直接融入Ansible的shell模块或者CI流水线。建议把Zabbix地址和账号改为从环境变量读取，避免敏感信息硬编码在脚本中。如果使用的是Zabbix 6.4及以上版本，user.login的参数名是username而不是user，迁移脚本时需要注意这个差异。

四、常见报错与排查思路

实际使用中configuration.import的报错信息比较隐晦，这里整理几个高频问题。第一类是Cannot read XML tag，这几乎总是因为source字段传入的内容不完整，比如文件读取时编码不对，或者JSON转义破坏了XML结构，用Python的json模块自动序列化可以彻底规避。第二类是Invalid params，通常是rules中写了当前版本不支持的规则项，例如Zabbix 5.0不支持templateDashboards，需要按服务端版本裁剪规则字典。

第三类是权限问题，导入操作要求API用户对主机组、模板等资源有写权限，如果用的是只读账号会返回Permission denied。建议为自动化场景单独创建一个属于Zabbix Administrators用户组的API账号，并配合API Token使用。此外，模板中引用的值映射、宏等依赖对象如果不存在，某些Zabbix版本不会自动创建，导入前要确认模板包里是否包含这些依赖文件，或者先导入基础依赖模板再导入上层模板，注意脚本的导入顺序。

Zabbix APIXML模板导入configuration.import修改时间：2026-08-31 09:54:53