19. API

概览

Zabbix API允许你以编程方式检索和修改Zabbix的配置，并提供对历史数据的访问。它广泛用于：

  • 创建新的应用程序以使用Zabbix；

  • 将Zabbix与第三方软件集成；

  • 自动执行常规任务。

Zabbix API是基于Web的API，作为Web前端的一部分提供。它使用JSON-RPC 2.0协议，这意味着两点：

  • 该API包含一组独立的方法；

  • 客户端和API之间的请求和响应使用JSON格式进行编码。

有关协议和JSON的更多信息可以在 JSON-RPC 2.0 规范 和 JSON 格式主页中找到。

结构

Zabbix API由许多名义上分组的独立API方法组成。每个方法执行一个特定任务。例如，方法 host.create 隶属于 host 这个API分组 ，用于创建新主机。历史上，API分组有时被称为“类”。

大多数API至少包含四种方法： get， create， update 和 delete ，分别是检索，创建，更新和删除数据，但是某些API提供一套完全不同的方法。

执行请求

当完成了前端的安装配置后，你就可以使用远程HTTP请求来调用API。为此，需要向位于前端目录中的 api_jsonrpc.php 文件发送HTTP POST请求。例如，如果你的Zabbix前端安装在 http://company.com/zabbix， 那么用HTTP请求来调用 apiinfo.version 方法就如下面这样：

  1. POST http://company.com/zabbix/api_jsonrpc.php HTTP/1.1
  2. Content-Type: application/json-rpc
  4. {"jsonrpc":"2.0","method":"apiinfo.version","id":1,"auth":null,"params":{}}

请求的 Content-Type 头部必须设置为以下值之一： application/json-rpc, application/json 或 application/jsonrequest。

你可以使用任何HTTP客户端或JSON-RPC测试工具手动执行API请求，但对于开发应用程序，我们建议使用 社区维护的程序库。

示例

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

验证

在访问Zabbix中的任何数据之前，你需要登录并获取身份验证令牌。这可以使用该 [user.login](https://www.zabbix.com/documentation/5.0/5.0/zh/manual/api/reference/user/login "5.0:zh:manual:api:reference:user:login") 方法完成。让我们假设你想要以标准Zabbix Admin用户身份登录。然后，你的JSON请求将如下所示：

  1. {
  2.     "jsonrpc": "2.0",
  3.     "method": "user.login",
  4.     "params": {
  5.         "user": "Admin",
  6.         "password": "zabbix"
  7.     },
  8.     "id": 1,
  9.     "auth": null
  10. }

让我们仔细看看示例请求对象。它具有以下属性：

  • jsonrpc - API使用的JSON-RPC协议的版本; Zabbix API实现的JSON-RPC版本是2.0;

  • method - 被调用的API方法名;

  • params - 将被传递给API方法的参数;

  • id - 请求的任意标识符;

  • auth -用户认证令牌; 如果没有的话可以设置为null。

如果你正确提供了凭据，API返回的响应将包含用户身份验证令牌：

  1. {
  2.     "jsonrpc": "2.0",
  3.     "result": "0424bd59b807674191e7d77572075f33",
  4.     "id": 1
  5. }

响应对象又包含以下属性：

  • jsonrpc - JSON-RPC协议的版本;

  • result - 请求返回的数据;

  • id - 相应请求的id。

检索主机

我们现在有一个有效的用户身份验证令牌，可以用来访问Zabbix中的数据。 例如，让我们使用 [host.get]($0c668ec050007687.md "zh:manual:api:reference:host:get") 方法检索所有已配置主机的ID，主机名和接口 ：

  1. {
  2.     "jsonrpc": "2.0",
  3.     "method": "host.get",
  4.     "params": {
  5.         "output": [
  6.             "hostid",
  7.             "host"
  8.         ],
  9.         "selectInterfaces": [
  10.             "interfaceid",
  11.             "ip"
  12.         ]
  13.     },
  14.     "id": 2,
  15.     "auth": "0424bd59b807674191e7d77572075f33"
  16. }

请注意， auth 属性现在设置为我们通过调用user.login方法获得的身份验证令牌。

响应对象将包含有关主机的请求的数据：

  1. {
  2.     "jsonrpc": "2.0",
  3.     "result": [
  4.         {
  5.             "hostid": "10084",
  6.             "host": "Zabbix server",
  7.             "interfaces": [
  8.                 {
  9.                     "interfaceid": "1",
  10.                     "ip": "127.0.0.1"
  11.                 }
  12.             ]
  13.         }
  14.     ],
  15.     "id": 2
  16. }

出于性能原因，我们建议始终列出要检索的对象属性，并避免检索所有内容。

创建新监控项

让我们使用从上一个请求host.get中获得的数据，在主机 “Zabbix server” 上创建一个新 监控项 。这个可以通过使用方法 [item.create]($2a7c00a5cbc48a4d.md "zh:manual:api:reference:item:create")：

  1. {
  2.     "jsonrpc": "2.0",
  3.     "method": "item.create",
  4.     "params": {
  5.         "name": "Free disk space on $1",
  6.         "key_": "vfs.fs.size[/home/joe/,free]",
  7.         "hostid": "10084",
  8.         "type": 0,
  9.         "value_type": 3,
  10.         "interfaceid": "1",
  11.         "delay": 30
  12.     },
  13.     "auth": "0424bd59b807674191e7d77572075f33",
  14.     "id": 3
  15. }

成功的响应将包含新创建监控项的ID，可用于在以后请求中引用监控项：

  1. {
  2.     "jsonrpc": "2.0",
  3.     "result": {
  4.         "itemids": [
  5.             "24759"
  6.         ]
  7.     },
  8.     "id": 3
  9. }

item.create 方法和其他的创建（create）方法，也可以接受对象数组，并通过一次API调用中创建多个监控项。

创建多个触发器

因此，如果create方法接受数组，我们可以添加多个触发器，像这样^-^：

  1. {
  2.     "jsonrpc": "2.0",
  3.     "method": "trigger.create",
  4.     "params": [
  5.         {
  6.             "description": "Processor load is too high on {HOST.NAME}",
  7.             "expression": "{Linux server:system.cpu.load[percpu,avg1].last()}>5",
  8.         },
  9.         {
  10.             "description": "Too many processes on {HOST.NAME}",
  11.             "expression": "{Linux server:proc.num[].avg(5m)}>300",
  12.         }
  13.     ],
  14.     "auth": "0424bd59b807674191e7d77572075f33",
  15.     "id": 4
  16. }

操作成功的响应将包含新创建的触发器的ID：

  1. {
  2.     "jsonrpc": "2.0",
  3.     "result": {
  4.         "triggerids": [
  5.             "17369",
  6.             "17370"
  7.         ]
  8.     },
  9.     "id": 4
  10. }

更新监控项

启用监控项，即将其状态设置为“0”：

  1. {
  2.     "jsonrpc": "2.0",
  3.     "method": "item.update",
  4.     "params": {
  5.         "itemid": "10092",
  6.         "status": 0
  7.     },
  8.     "auth": "0424bd59b807674191e7d77572075f33",
  9.     "id": 5
  10. }

操作成功的响应将包含被更新的触发器的ID：

  1. {
  2.     "jsonrpc": "2.0",
  3.     "result": {
  4.         "itemids": [
  5.             "10092"
  6.         ]
  7.     },
  8.     "id": 5
  9. }

item.update 方法以及其他更新方法也可以接受对象数组，并通过一次API调用更新多个监控项。

更新多个触发器

启用多个触发器，即将其状态设置为0：

  1. {
  2.     "jsonrpc": "2.0",
  3.     "method": "trigger.update",
  4.     "params": [
  5.         {
  6.             "triggerid": "13938",
  7.             "status": 0
  8.         },
  9.         {
  10.             "triggerid": "13939",
  11.             "status": 0
  12.         }
  13.     ],
  14.     "auth": "0424bd59b807674191e7d77572075f33",
  15.     "id": 6
  16. }

成功的响应将包含被更新的触发器的ID数组：

  1. {
  2.     "jsonrpc": "2.0",
  3.     "result": {
  4.         "triggerids": [
  5.             "13938",
  6.             "13939"
  7.         ]
  8.     },
  9.     "id": 6
  10. }

这是更新的首选方法。一些API方法 host.massupdate 允许编写更简单的代码，但不建议使用这些方法，因为它们将在未来的版本中删除。

错误处理

到目前为止，我们试过的一切工作正常。但是，如果我们尝试对API调用不正确会发生什么？让我们尝试通过调用[host.create]($c524667eb9e750b3.md "zh:manual:api:reference:host:create")创建另一个主机， 但省略一个必填 groups 参数。

  1. {
  2.     "jsonrpc": "2.0",
  3.     "method": "host.create",
  4.     "params": {
  5.         "host": "Linux server",
  6.         "interfaces": [
  7.             {
  8.                 "type": 1,
  9.                 "main": 1,
  10.                 "useip": 1,
  11.                 "ip": "192.168.3.1",
  12.                 "dns": "",
  13.                 "port": "10050"
  14.             }
  15.         ]
  16.     },
  17.     "id": 7,
  18.     "auth": "0424bd59b807674191e7d77572075f33"
  19. }

这个请求的返回会包含一个错误信息：

  1. {
  2.     "jsonrpc": "2.0",
  3.     "error": {
  4.         "code": -32602,
  5.         "message": "Invalid params.",
  6.         "data": "No groups for host \"Linux server\"."
  7.     },
  8.     "id": 7
  9. }

如果发生错误，响应对象将包含error 而不是 result 属性，同时error将具有以下数据的属性：

  • code - 错误代码;

  • message - 一个简短的错误摘要;

  • data - 更详细的错误消息。

错误可能发生在不同的情况下，例如，使用不正确的输入值，会话超时或试图访问不存在的对象。你的应用程序应该能够优雅地处理这些类型的错误。

API版本

为了简化API版本控制，自Zabbix 2.0.4开始，API的版本与Zabbix本身的版本相匹配。 你可以使用 [apiinfo.version]($e040cf73bee07e00.md "zh:manual:api:reference:apiinfo:version") 方法查找你正在使用的API的版本。这对于调整应用程序以使用特定于版本的功能非常有用。

我们保证在主要版本内部具有向后兼容性。当在主要版本之间进行向后不兼容的更改时，我们通常将旧功能在下一个版本中保留为已弃用，并且仅在此后的版本中将其删除。有时，我们可能会删除主要版本之间的功能，而不提供任何向后兼容性。重要的是，你不要依赖任何弃用的功能，并尽快迁移到较新的替代品。

你可以在 API更改日志中跟踪对API所做的所有更改。

进一步阅读

你现在知道了足够开始使用 Zabbix API，但不要停在这里。为了进一步阅读，我们建议你查看 可用的API列表。