18 API

概述

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

  • 创建与 Zabbix 配合使用的新应用程序；
  • 将 Zabbix 集成到第三方软件中；
  • 自动化日常任务。

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

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

有关该协议和 JSON 的更多信息，请参见 JSON-RPC 2.0 specification 和 JSON format homepage。

有关将 Zabbix 功能集成到您的 Python 应用程序中的更多信息，请参见 Python library for Zabbix。

Zabbix 中的用户访问权限（包括配置和历史数据）取决于 user type、分配的 user role 以及 user groups。

结构

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 会将该请求视为通知）。

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

{
    "jsonrpc": "2.0",
    "result": "8.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 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
}

出于性能原因，始终建议列出您想要获取的对象属性。这样可以避免获取所有内容。

创建新监控项

现在，在主机 "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.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 列表。