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 分组有时被称为 “classes”。

大多数API至少包含四种方法:get,create, updatedelete ,分别是检索,创建,更新和删除数据,但是某些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
  3. {"jsonrpc":"2.0","method":"apiinfo.version","id":1,"auth":null,"params":{}}

请求的 Content-Type 头部必须设置为以下值之一:application/json-rpcapplication/jsonapplication/jsonrequest

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

示例工作流

以下部分将更详细地引导您完成一些用法示例。

认证

在访问 Zabbix 中的任何数据之前,你需要登录并获取身份认证 token。这可以使用 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 - 用户认证 token;因为我们还没有,它被设计为 null

如果你正确提供了凭据,AP I返回的响应将包含用户身份认证 token:

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

响应对象包含以下属性:

  • jsonrpc - JSON-RPC 协议的版本;
  • result - 方法返回的数据;
  • id - 相应请求的标识符。

检索主机

我们现在有一个有效的用户身份认证 token,可以用来访问 Zabbix 中的数据。例如,我们使用 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 方法获得的身份认证 token。

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

  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 方法完成:

  1. {
  2. "jsonrpc": "2.0",
  3. "method": "item.create",
  4. "params": {
  5. "name": "Free disk space on /home/joe/",
  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方法接受数组,我们可以添加多个 [触发器] (/manual/api/reference/trigger/object) ,像这样-:

  1. {
  2. "jsonrpc": "2.0",
  3. "method": "trigger.create",
  4. "params": [
  5. {
  6. "description": "Processor load is too high on {HOST.NAME}",
  7. "expression": "last(/Linux server/system.cpu.load[percpu,avg1])>5",
  8. },
  9. {
  10. "description": "Too many processes on {HOST.NAME}",
  11. "expression": "avg(/Linux server/proc.num[],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. }

The item.update 方法以及其他 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 方法创建另一个主机, 但省略一个必填的 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 方法查找你正在使用的 API 的版本。 这对于调整应用程序以使用特定于版本的功能非常有用。

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

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

进一步阅读

您现在知道了足够的知识,可以开始使用 Zabbix API,但不要停在这里。我们建议你对 可用的 API 列表 做进一步阅读。