zabbix api 的使用

发表于 2022-12-11 分类于应用，运维监控

概览

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, update 和 delete ，分别是检索，创建，更新和删除数据，但是某些API提供一套完全不同的方法。

执行请求

当完成了前端的安装配置后，你就可以使用远程HTTP请求来调用API。为此，需要向位于前端目录中的 api_jsonrpc.php 文件发送 HTTP POST 请求。例如，如果你的 Zabbix 前端安装在 *http://company.com/zabbix*，那么用HTTP请求来调用 apiinfo.version 方法就如下面这样：

POST http://company.com/zabbix/api_jsonrpc.php HTTP/1.1
       Content-Type: application/json-rpc

       {"jsonrpc":"2.0","method":"apiinfo.version","id":1,"auth":null,"params":{}}

请求的 Content-Type 头部必须设置为以下值之一：application/json-rpc，application/json 或 application/jsonrequest。

示例工作流

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

认证

在访问 Zabbix 中的任何数据之前，你需要登录并获取身份认证 token。这可以使用 user.login 方法完成。我们假设你想要以标准 Zabbix Admin 用户身份登录。那么，你的 JSON 请求将如下所示：

{
    "jsonrpc": "2.0",
    "method": "user.login",
    "params": {
        "user": "Admin",
        "password": "zabbix"
    },
    "id": 1,
    "auth": null
}

让我们仔细看看示例请求对象。它具有以下属性：

jsonrpc - API 使用的 JSON-RPC 协议的版本; Zabbix API 实现的 JSON-RPC 版本是2.0；
method - 被调用的 API 方法；
params - 将被传递给API方法的参数；
id - 请求的任意标识符；
auth - 用户认证 token；因为我们还没有，它被设置为 null。

如果你正确提供了凭据，API 返回的响应将包含用户身份认证 token：

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

响应对象包含以下属性：

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

检索主机

我们现在有一个有效的用户身份认证 token，可以用来访问 Zabbix 中的数据。例如，我们使用 host.get 方法检索所有已配置主机的ID，主机名和接口：

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

请注意 auth属性现在设置为我们通过调用 user.login 方法获得的身份认证 token。

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

{
    "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 方法完成：

{
           "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
           },
           "auth": "0424bd59b807674191e7d77572075f33",
           "id": 3
       }

成功的响应将包含新创建监控项的ID，可用于在以后请求中引用该监控项：

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

item.create方法和其他的 create 方法也可以接受对象数组并通过一次 API 调用创建多个监控项。

创建多个触发器

因此，如果create方法接受数组，我们可以添加多个 [触发器] (/manual/api/reference/trigger/object) ，像这样：

{
    "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",
        }
    ],
    "auth": "0424bd59b807674191e7d77572075f33",
    "id": 4
}

操作成功的响应将包含新创建触发器的 ID 数组：

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

更新监控项

启用监控项，即将其状态设置为“0”：

{
    "jsonrpc": "2.0",
    "method": "item.update",
    "params": {
        "itemid": "10092",
        "status": 0
    },
    "auth": "0424bd59b807674191e7d77572075f33",
    "id": 5
}

操作成功的响应将包含被更新监控项的 ID：

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

The item.update 方法以及其他 update 方法也可以接受对象数组并通过一次 API 调用更新多个监控项。

更新多个触发器

启用多个触发器，即将其状态设置为0：

{
    "jsonrpc": "2.0",
    "method": "trigger.update",
    "params": [
        {
            "triggerid": "13938",
            "status": 0
        },
        {
            "triggerid": "13939",
            "status": 0
        }
    ],
    "auth": "0424bd59b807674191e7d77572075f33",
    "id": 6
}

成功的响应将包含被更新触发器的 ID数组：

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

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

错误处理

到目前为止，我们尝试过的一切都运行良好。但是，如果我们尝试对 API 进行不正确的调用，会发生什么情况？让我们尝试通过调用 host.create 方法创建另一个主机，但省略一个必填的 groups 参数。

{
    "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,
    "auth": "0424bd59b807674191e7d77572075f33"
}

这个请求的返回会包含一个错误信息：

{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "Invalid params.",
        "data": "No groups for host \"Linux server\"."
    },
    "id": 7
}