19. API

概览

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

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

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

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

有关协议和 JSON 的更多信息,请参见 JSON-RPC 2.0 规范JSON 格式主页

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

结构

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

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

执行请求

一旦您设置了前端,就可以使用远程 HTTP 请求来调用 API。为此,您需要发送 HTTP POST 请求到前端目录中的 api_jsonrpc.php 文件。例如,如果您的 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

请求对象包含以下属性:

  • jsonrpc - API 使用的 JSON-RPC 协议版本(Zabbix API 实现了 JSON-RPC 版本 2.0);
  • method - 正在调用的 API 方法;
  • params - 将传递给 API 方法的参数;
  • id - 请求的任意标识符。

如果请求正确,API 返回的响应应该像这样:

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

返回的响应对象,包含以下属性:

  • jsonrpc - JSON-RPC 协议的版本;
  • 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
       }

授权方法

通过 "Authorization" 头部

所有 API 请求都需要认证或 API 令牌。 您可以使用 "Authorization" 请求头部提供凭据:

curl --request POST \
         --url 'https://example.com/zabbix/api_jsonrpc.php' \
         --header 'Authorization: Bearer 0424bd59b807674191e7d77572075f33'
通过 "auth" 属性

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 被用来授权通过 JavaScript(来自模块或自定义控件)执行的来自 Zabbix UI 的 API 请求。

获取主机

现在您有一个有效的用户认证令牌,可以用来访问 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 查询的文件。您可以在 --data 参数中直接传递查询,而不是使用文件。

data.json

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

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

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

出于性能考虑,始终建议列出您想要检索的对象属性。这样,您将避免检索所有内容。

创建新监控项

现在,在主机 "Zabbix server" 上使用您从上一个 host.get 请求获得的数据创建一个新的 item。这可以通过使用 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 方法以及其他 创建方法 也可以接受对象数组,并用一个 API 调用创建多个监控项。

创建多个触发器

因此,如果 创建方法 接受数组,您可以添加多个 触发器,例如:

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 方法以及其他 更新方法 也可以接受对象数组,并用一个 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 来创建另一个主机,但省略必填的 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
       }

如果发生错误,响应对象将包含 error 属性而不是 result 属性,其中包含以下数据:

  • code - 错误代码;
  • message - 简短的错误摘要;
  • data - 更详细的错误信息。

在各种情况下都可能发生错误,例如,使用错误的输入值、会话超时或尝试访问不存在的对象。您的应用程序应该能够优雅地处理这些类型的错误。

API 版本

为了简化 API 版本管理,自 Zabbix 2.0.4 起,API 的版本与 Zabbix 本身的版本相匹配。您可以使用 apiinfo.version 方法来查看您正在使用的 API 版本。这对于调整您的应用程序以使用特定版本的功能非常有用。

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

您可以在 API 更新日志 中查看对 API 所做的所有更改。

进一步阅读

现在,您已经掌握了足够的知识来开始使用Zabbix API,但请不要就此止步。为了进一步学习,建议您查阅可用 API 列表