这是原厂英文文档的翻译页面. 欢迎帮助我们 完善文档.

19 API

概述

Zabbix API 允许您以编程方式检索和修改Zabbix的配置,并提供对历史数据的访问。它主要应用于以下场景:

  • 创建与Zabbix协同工作的新应用程序;
  • 将Zabbix与第三方软件集成;
  • 自动化日常任务。

Zabbix API 是基于网页的API,作为Web前端的一部分提供。它采用JSON-RPC 2.0协议,这意味着:

  • API 由一组独立的方法组成;
  • 客户端与API之间的请求和响应使用JSON格式编码。

关于该协议和JSON的更多信息,请参阅JSON-RPC 2.0 specificationJSON format homepage

如需了解如何将Zabbix功能集成到Python应用程序中,请参考zabbix_utils Python库,专为Zabbix API设计。

结构

API由多个方法组成,这些方法名义上被分组到不同的API中。每个方法执行一项特定任务。例如,host.create方法属于主机 API,用于创建新的主机。历史上,API有时被称为"类"。

大多数API至少包含四种方法:getcreateupdatedelete,分别用于检索、创建、更新和删除数据,但某些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-rpcapplication/jsonapplication/jsonrequest

以下部分将更详细地介绍一些使用示例。

认证

要访问Zabbix中的任何数据,您需要:

例如,如果您想以标准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返回的响应将包含用户身份验证令牌:

{
           "jsonrpc": "2.0",
           "result": "0424bd59b807674191e7d77572075f33",
           "id": 1
       }

响应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可用于在后续请求中引用该监控项:

{
           "jsonrpc": "2.0",
           "result": {
               "itemids": [
                   "24759"
               ]
           },
           "id": 3
       }

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列表:

{
           "jsonrpc": "2.0",
           "result": {
               "triggerids": [
                   "17369",
                   "17370"
               ]
           },
           "id": 4
       }

更新 监控项

启用一个监控项,即将其状态设置为"0":

{
           "jsonrpc": "2.0",
           "method": "item.update",
           "params": {
               "itemid": "10092",
               "status": 0
           },
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 5
       }

成功响应将包含更新后的监控项的ID:

{
           "jsonrpc": "2.0",
           "result": {
               "itemids": [
                   "10092"
               ]
           },
           "id": 5
       }

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:

{
           "jsonrpc": "2.0",
           "result": {
               "triggerids": [
                   "13938",
                   "13939"
               ]
           },
           "id": 6
       }

这是推荐的更新方式。某些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