20 API

概述

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

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

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

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

有关协议和 JSON 的更多信息,请参见 JSON-RPC 2.0 specificationJSON format homepage

有关将 Zabbix 功能集成到您的 Python 应用程序中的更多信息,请参见用于 Zabbix API 的 zabbix_utils Python 库。

结构

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

大多数API至少包含四个方法:getcreateupdatedelete,分别用于检索、创建、更新和删除数据,但某些API可能会提供完全不同的方法集合。

执行请求

完成前端配置后,您可通过远程HTTP请求调用API。为此,需要向前端目录中的api_jsonrpc.php file发送HTTP POST请求。例如,若Zabbix前端安装在https://example.com/zabbix路径下,调用apiinfo.version方法的HTTP请求示例如下:

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"jsonrpc":"2.0","method":"apiinfo.version","params":{},"id":1}'

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

请求object需包含以下属性:

  • jsonrpc - API使用的JSON-RPC协议version(Zabbix API实现JSON-RPC version 2.0);
  • method - 所调用的API方法;
  • params - 传递给API方法的参数;
  • id - 任意请求标识符(若省略,API将视该请求为notification)。

若请求正确,API返回的响应格式如下:

{
           "jsonrpc": "2.0",
           "result": "7.0.0",
           "id": 1
       }

响应object包含以下属性:

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

示例工作流

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

认证

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

  • 使用现有的 API token(在 Zabbix 前端创建或使用 Token API 创建);
  • 使用通过 user.login 方法获取的身份验证令牌。

例如,如果您希望以标准 Admin 用户身份登录来获取新的身份验证令牌,则 JSON 请求将如下所示:

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"jsonrpc":"2.0","method":"user.login","params":{"username":"Admin","password":"zabbix"},"id":1}'

如果您提供的凭据正确,API 返回的响应应包含用户身份验证令牌:

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

授权方法

通过授权标头

所有API请求都需要身份验证或API令牌。 可通过在请求中使用Authorization头部提供凭据:

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Authorization: Bearer 0424bd59b807674191e7d77572075f33'

如果遇到身份验证问题问题,请参阅授权头转发

从Zabbix 7.0.7版本开始,跨域请求(CORS)已支持Authorization头部。 自Zabbix 7.0.11版本起,Zabbix API以不区分大小写的方式接受头部(例如authorizationAuthorizationAUTHORIZATION将被视为相同)。

By auth property

一个 API 请求可以通过 auth 属性进行授权。

请注意,auth 属性已被弃用。它将在未来的版本中被移除。

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"jsonrpc":"2.0","method":"host.get","params":{"output":["hostid"]},"auth":"0424bd59b807674191e7d77572075f33","id":1}'

一个 "zbx_session" cookie 被用于授权来自 Zabbix UI 的 API 请求,该请求是通过 JavaScript(来自模块或自定义小部件)执行的。

检索主机

现在你已经拥有一个有效的用户身份验证令牌,可以用来访问Zabbix中的数据。例如,你可以使用 host.get 方法来检索所有已配置的 hosts 的ID、 主机 名称和接口:

请求:

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
         --header 'Content-Type: application/json-rpc' \
         --data @data.json

data.json 是一个包含JSON query 的 file。你可以通过 --data 参数传递该 query,而无需使用文件。

data.json

{
           "jsonrpc": "2.0",
           "method": "host.get",
           "params": {
               "output": [
                   "hostid",
                   "host"
               ],
               "selectInterfaces": [
                   "interfaceid",
                   "ip"
               ]
           },
           "id": 2
       }

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

{
           "jsonrpc": "2.0",
           "result": [
               {
                   "hostid": "10084",
                   "host": "Zabbix server",
                   "interfaces": [
                       {
                           "interfaceid": "1",
                           "ip": "127.0.0.1"
                       }
                   ]
               }
           ],
           "id": 2
       }

出于性能考虑,建议始终列出你希望检索的 object 属性。这样可以避免检索所有数据。

创建新的 监控项

现在,通过create方法在item上基于先前host.get请求获取的数据创建一个新的主机"Zabbix服务器"。这可以通过item.create方法实现:

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"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},"id":3}'

成功响应将包含新建监控项的ID,该ID可用于在后续请求中引用该监控项:

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

item.create方法及其他create方法也可接受objects数组,通过单次API调用即可create多个监控项。

创建多个触发器

因此,如果 create 方法 支持数组,您可以添加多个 triggers,例如,如下这个:

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"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",}],"id":4}'

成功的响应将包含新创建触发器的 ID:

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

更新 监控项

通过将其状态设置为“0”来启用一个监控项:

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"jsonrpc":"2.0","method":"item.update","params":{"itemid":"10092","status":0},"id":5}'

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

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

item.update方法以及其他update方法也可以接受objects和update的数组,以一次API调用处理多个监控项。

更新多个触发器

通过将状态设置为"0"来启用多个触发器:

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"jsonrpc":"2.0","method":"trigger.update","params":[{"triggerid":"13938","status":0},{"triggerid":"13939","status":0}],"id":6}'

成功的响应将包含已更新触发器的ID:

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

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

错误处理

到目前为止,您尝试的一切都运行良好。但如果错误调用API会发生什么情况?尝试通过调用host.create来create另一个主机,但省略必需的groups参数:

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Authorization: Bearer ${AUTHORIZATION_TOKEN}' \
         --header 'Content-Type: application/json-rpc' \
         --data '{"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}'

此时响应将包含错误信息:

{
           "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的version与Zabbix本身的version一致。您可以使用apiinfo.version方法来查看您正在使用的API的version。这对于调整应用程序以使用特定版本的功能非常有用。

Zabbix保证在一个主版本内功能的向后兼容性。当在主版本之间进行不兼容的更改时,Zabbix通常会在下一个版本中将旧功能标记为弃用,并仅在之后的版本中将其移除。有时,Zabbix可能会在主版本之间移除功能而不提供任何向后兼容性。因此,重要的是您永远不要依赖任何已被弃用的功能,并应尽快迁移到更新的替代方案。

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

延伸阅读

现在,您已经掌握了足够的知识,可以开始使用 Zabbix API,但是请不要止步于此。建议您进一步阅读 list of available APIs