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 的 Python 库。

Zabbix 中的用户访问权限，包括配置和历史数据，取决于 用户类型、分配的 用户角色 以及 用户组。

结构

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

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

执行请求

在设置好前端后，您可以使用远程 HTTP 请求来调用 API。 为此，您需要向位于前端目录中的 api_jsonrpc.php 文件发送 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-rpc、application/json 或 application/jsonrequest。

请求对象必须包含以下属性：

  • jsonrpc - API 使用的 JSON-RPC 协议版本（Zabbix API 实现的是 JSON-RPC 2.0 版本）；
  • method - 正在调用的 API 方法；
  • params - 将传递给 API 方法的参数；
  • id - 请求的任意标识符（如果省略，API 会将该请求视为 notification）。

如果请求正确，API 返回的响应应如下所示：

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

响应对象同样包含以下属性：

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

认证

要访问 Zabbix 中的任何数据，您需要：

  • 使用在 Zabbix 前端中创建的现有 API token，位于 Users > API tokens 部分，或者使用 Token API 创建的 API token。
  • 使用通过 user.login 方法获取的认证 token。

例如，如果您希望通过以标准 Admin 用户身份登录来获取新的认证 token，那么 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 返回的响应应包含用户认证 token：

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

授权方法

通过“Authorization”标头

所有 API 请求都需要身份验证信息或 API token。 您可以在请求中使用 Authorization 标头来提供凭据：

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

如果您遇到身份验证问题，请参见Authorization 标头转发。

Zabbix API 以不区分大小写的方式接受标头（例如，authorization、Authorization 和 AUTHORIZATION 会被视为相同）。

Authorization 标头支持跨源请求（CORS）。

一个 "zbx_session" cookie 被用来授权通过 JavaScript（来自模块或自定义控件）执行的来自 Zabbix UI 的 API 请求。

示例工作流

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

获取主机

现在你已经拥有一个有效的用户身份验证令牌（在以下示例中以变量表示），可用于访问 Zabbix 中的数据。
例如，你可以使用 host.get 方法来获取所有已配置 主机 的 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
}

出于性能考虑，始终建议列出你想要检索的对象属性。
这样可以避免检索全部内容。

创建新的监控项

现在，使用你从之前的 host.get 请求中获得的数据，在主机 "Zabbix server" 上创建一个新的 监控项。 这可以通过 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 methods 也可以接受对象数组，并通过一次 API 调用创建多个监控项。

创建多个触发器

因此，如果 create methods 接受数组，你可以添加多个 触发器，例如下面这个：

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 methods 也可以接受对象数组，并通过一次 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.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
}

如果发生了错误，响应对象中将不会包含 result 属性，而是包含 error 属性，其数据如下：

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

错误可能出现在多种情况下，例如使用了错误的输入值、会话超时，或者尝试访问不存在的对象。
你的应用程序应能够优雅地处理这类错误。

API 版本

为了简化 API 版本管理，自 Zabbix 2.0.4 起，API 的版本与 Zabbix 本身的版本保持一致。 您可以使用 apiinfo.version 方法来查看您正在使用的 API 版本。 这对于调整您的应用程序以使用特定版本的功能可能很有帮助。

Zabbix 保证在同一主版本内功能向后兼容。 在主版本之间进行不向后兼容的更改时，Zabbix 通常会在下一个版本中将旧功能标记为已弃用，并仅在再下一个版本中将其移除。 偶尔，Zabbix 也可能在主版本之间移除功能，而不提供任何向后兼容性。 因此，切勿依赖任何已弃用的功能，并应尽快迁移到更新的替代方案。

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

延伸阅读

现在，你已经具备开始使用 Zabbix API 的足够知识，不过不要就此止步。 如需进一步阅读，建议你查看可用 API 列表。