Zabbix API 允许您以编程方式检索和修改 Zabbix的配置,并提供对历史数据的访问。它被 广泛用于:
Zabbix API 是一个基于Web的API,作为Web 前端的一部分提供。它使用JSON-RPC 2.0协议,这意味着两点:
API 由一组独立的方法组成;
客户端与API之间的请求和响应经过编码
using the JSON format.
有关协议和JSON的更多信息,请参阅JSON-RPC 2.0 specification和JSON format homepage。
有关将Zabbix功能集成到Python应用程序中的更多信息,请参阅用于Zabbix API的zabbix_utils Python库。
API由多个方法组成,这些方法名义上被分组到不同的API中。每个方法执行一个特定任务。例如,host.create
方法属于主机 API,用于create新的主机。历史上,API有时被称为"类"。
大多数API至少包含四种方法:get
、create
、update
和delete
,分别用于检索、创建、更新和删除数据,但某些API可能提供完全不同的方法集。
完成前端配置后,您可通过远程HTTP请求调用API。为此需向位于前端目录的api_jsonrpc.php
file发送HTTP POST请求。例如: 若Zabbix前端安装在http://example.com/zabbix路径下,调用apiinfo.version
方法的HTTP请求示例如下:
POST http://example.com/zabbix/api_jsonrpc.php HTTP/1.1
Content-Type: application/json-rpc
{
"jsonrpc": "2.0",
"method": "apiinfo.version",
"id": 1,
"auth": null,
"params": {}
}
请求头必须包含Content-Type
字段,其值应为以下之一:application/json-rpc
、application/json
或application/jsonrequest
。
以下部分将更详细地介绍一些使用示例。
要访问Zabbix中的任何数据,您需要:
例如,如果您想以标准Admin用户身份登录获取新的身份验证令牌,JSON请求将如下所示:
{
"jsonrpc": "2.0",
"method": "user.login",
"params": {
"username": "Admin",
"password": "zabbix"
},
"id": 1,
"auth": null
}
让我们仔细看看请求object。它具有以下属性:
jsonrpc
- API使用的JSON-RPC协议的version; Zabbix API实现了JSON-RPC version 2.0;
method
- 调用的API方法;
params
- 传递给API方法的参数;
id
- 请求的任意标识符; 如果省略,API会将请求视为notification;
auth
- 用户身份验证令牌;由于我们还没有,
it's set to null
.
null
。
如果您提供了正确的凭据,API返回的响应将包含用户身份验证令牌:
响应object包含以下属性:
jsonrpc
- 再次是JSON-RPC协议的version;result
- 方法返回的数据;id
- 对应请求的标识符。我们现在拥有一个有效的用户认证令牌,可用于访问Zabbix中的数据。例如,让我们使用 host.get方法来获取所有已配置 hosts的ID、 主机名称和接口信息:
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"output": [
"hostid",
"host"
],
"selectInterfaces": [
"interfaceid",
"ip"
]
},
"id": 2,
"auth": "0424bd59b807674191e7d77572075f33"
}
请注意auth
属性现在被设置为我们通过调用 user.login
获得的认证令牌。
响应object将包含所请求的主机数据:
{
"jsonrpc": "2.0",
"result": [
{
"hostid": "10084",
"host": "Zabbix server",
"interfaces": [
{
"interfaceid": "1",
"ip": "127.0.0.1"
}
]
}
],
"id": 2
}
出于性能考虑,我们建议始终列出您需要获取的 object属性,避免获取全部数据。
让我们基于从上一个host.get
请求获取的数据,在"Zabbix服务器"上create一个新的item。这可以通过使用item.create方法实现:
{
"jsonrpc": "2.0",
"method": "item.create",
"params": {
"name": "Free disk space on /home/joe/",
"key_": "vfs.fs.size[/home/joe/,free]",
"hostid": "10084",
"type": 0,
"value_type": 3,
"interfaceid": "1",
"delay": 30
},
"auth": "0424bd59b807674191e7d77572075f33",
"id": 3
}
成功响应将包含新创建的监控项的ID,该ID可用于在后续请求中引用该监控项:
item.create
方法以及其他create方法也可以接受objects数组,并通过一次API调用来create多个监控项。
如果create方法接受数组参数,我们可以像这样批量添加 triggers:
{
"jsonrpc": "2.0",
"method": "trigger.create",
"params": [
{
"description": "Processor load is too high on {HOST.NAME}",
"expression": "last(/Linux server/system.cpu.load[percpu,avg1])>5",
},
{
"description": "Too many processes on {HOST.NAME}",
"expression": "avg(/Linux server/proc.num[],5m)>300",
}
],
"auth": "0424bd59b807674191e7d77572075f33",
"id": 4
}
成功响应将包含新建触发器ID数组:
启用一个监控项,即将其状态设置为"0":
{
"jsonrpc": "2.0",
"method": "item.update",
"params": {
"itemid": "10092",
"status": 0
},
"auth": "0424bd59b807674191e7d77572075f33",
"id": 5
}
成功响应将包含更新后的监控项的ID:
item.update
方法以及其他update方法 也可以接受objects数组,并通过一次API 调用update多个监控项。
启用多个触发器,即将它们的状态设置为0:
{
"jsonrpc": "2.0",
"method": "trigger.update",
"params": [
{
"triggerid": "13938",
"status": 0
},
{
"triggerid": "13939",
"status": 0
}
],
"auth": "0424bd59b807674191e7d77572075f33",
"id": 6
}
成功的响应将包含已更新触发器的ID:
这是推荐的更新方法。某些API 方法如host.massupdate
允许编写更简单的代码,但 不建议使用这些方法,因为它们将在未来版本中被移除。
到目前为止我们尝试的所有操作都运行良好。但如果尝试错误调用API会发生什么?让我们通过调用host.create但省略必需的groups
参数来create另一个主机。
{
"jsonrpc": "2.0",
"method": "host.create",
"params": {
"host": "Linux server",
"interfaces": [
{
"type": 1,
"main": 1,
"useip": 1,
"ip": "192.168.3.1",
"dns": "",
"port": "10050"
}
]
},
"id": 7,
"auth": "0424bd59b807674191e7d77572075f33"
}
响应将包含错误信息:
{
"jsonrpc": "2.0",
"error": {
"code": -32602,
"message": "Invalid params.",
"data": "No groups for host \"Linux server\"."
},
"id": 7
}
如果发生错误,响应object将不再包含result
属性,而是包含带有以下数据的error
属性:
code
- 错误代码;message
- 简短的错误摘要;data
- 更详细的错误信息。错误可能发生在不同场景中,例如使用错误的输入值、会话超时或尝试访问不存在的objects。您的应用程序应能妥善处理这类错误。
为简化API版本管理,自Zabbix 2.0.4起,API的version 与Zabbix自身的version保持一致。您可通过 apiinfo.version方法查询 当前使用的API的version。这有助于调整应用程序以使用 version专属功能。
我们保证在主版本version内的功能向后兼容性。当主版本间存在 不兼容变更时,通常会在下一版本中将旧功能标记为弃用,并在 后续版本中移除。极少数情况下,我们可能不提供兼容层就直接 移除主版本间的功能。请务必避免依赖任何弃用功能,并尽快 迁移至新方案。
您可通过API changelog跟踪 API的所有变更记录。
您现在已掌握足够知识开始使用Zabbix API,但请不要止步于此。建议您进一步阅读list of available APIs以深入学习。