19 API
概述
Zabbix API 允许您以编程方式检索和修改Zabbix的配置，并提供对历史数据的访问。它主要应用于以下场景：
- 创建与Zabbix协同工作的新应用程序；
- 将Zabbix与第三方软件集成；
- 自动化日常任务。
Zabbix API 是基于网页的API，作为Web前端的一部分提供。它采用JSON-RPC 2.0协议，这意味着：
- API 由一组独立的方法组成；
- 客户端与API之间的请求和响应使用JSON格式编码。
关于该协议和JSON的更多信息，请参阅JSON-RPC 2.0 specification和JSON format homepage。
如需了解如何将Zabbix功能集成到Python应用程序中，请参考zabbix_utils Python库，专为Zabbix API设计。
结构
API由多个方法组成，这些方法名义上被分组到不同的API中。每个方法执行一项特定任务。例如，host.create方法属于主机 API，用于创建新的主机。历史上，API有时被称为"类"。
大多数API至少包含四种方法：get、create、update和delete，分别用于检索、创建、更新和删除数据，但某些API可能提供完全不同的方法集。
执行请求
完成前端配置后，您可通过远程HTTP请求调用API。为此需要向前端目录中的api_jsonrpc.php文件发送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中的任何数据，您需要：
- 使用现有的api-令牌（通过Zabbix前端创建或使用Token API）；
- 使用通过user.login方法获取的身份验证令牌。
例如，如果您想以标准Admin用户身份登录获取新的身份验证令牌，JSON请求将如下所示：
{
"jsonrpc": "2.0",
"method": "user.login",
"params": {
"username": "Admin",
"password": "zabbix"
},
"id": 1,
"auth": null
}让我们仔细查看请求object。它具有以下属性：
jsonrpc- API使用的JSON-RPC协议版本；Zabbix API实现了JSON-RPC版本2.0；method- 调用的API方法；params- 传递给API方法的参数；id- 请求的任意标识符；auth- 用户身份验证令牌；由于我们尚未获取，因此设置为null。
如果提供的凭据正确，API返回的响应将包含用户身份验证令牌：
响应object包含以下属性：
jsonrpc- 再次显示JSON-RPC协议版本；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服务器"上创建一个新的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方法及其他创建方法同样支持传入objects数组，通过单次API调用即可创建多个监控项。
创建多个触发器
因此，如果创建方法接受数组参数，我们可以批量添加多个 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方法以及其他更新方法 也可以接受objects数组，并通过一次API 调用来更新多个监控项。
更新多个触发器
启用多个触发器，即将其状态设置为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参数来创建另一个主机。
{
"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 版本
为简化API版本管理，自Zabbix 2.0.4起，API的版本号将与Zabbix主版本保持一致。您可通过 apiinfo.version方法 查询当前使用的API版本号，这有助于您的应用程序适配特定版本的功能特性。
我们保证主版本号范围内的功能向后兼容性。当进行跨主版本的不兼容变更时，通常会在次版本中保留旧功能作为废弃接口，并在下个版本中移除。极少数情况下，可能会直接移除功能而不提供兼容方案。请务必避免依赖任何废弃功能，并尽快迁移至新方案。
您可通过API changelog跟踪API的所有变更记录。
延伸阅读
现在您已掌握足够知识开始使用Zabbix API，但学习不应止步于此。我们建议您进一步阅读list of available APIs。