Zabbix API - api_jsonrpc - 《Zabbix监控 (zabbix)》

概述
结构
执行请求
EXAMPLE WORKFLOW
- AUTHENTICATION
- RETRIEVING HOSTS
创建新项
创建多个触发器
更新一个项目
更新多个触发器
错误处理；差错处理
API版本

原地址

https://www.zabbix.com/documentation/6.0/zh/manual/api

概述

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

创建新的应用程序与Zabbix工作
集成Zabbix与第三方软件
常规任务自动化。

Zabbix API是一个基于web的API，是web前端的一部分。它使用了JSON-RPC 2.0协议，这意味着两件事:

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

关于协议和JSON的更多信息可以在 JSON-RPC 2.0 specification 和 JSON format homepage.

结构

这个API由许多名义上分组在独立API中的方法组成。每个方法执行一个特定的任务。例如，主机。方法属于主机API，用于创建新主机。历史上，api有时被称为“类”。
大多数api至少包含四种方法:: get, create, update 和 delete 用于分别检索、创建、更新和删除数据，但有些api可能提供一组完全不同的方法。

执行请求

一旦你建立了前端，你可以使用远程HTTP请求来调用API。为此，您需要发送HTTP POST请求到 api_jsonrpc.php file located in the frontend directory. For example, if your Zabbix frontend is installed under http://company.com/zabbix, the HTTP request to call the apiinfo.version method may look like this:
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 or application/jsonrequest.
您可以使用任何HTTP客户机或JSON-RPC测试工具手动执行API请求，但对于开发应用程序，我们建议您使用 community maintained libraries.

EXAMPLE WORKFLOW

下一节将更详细地介绍一些用法示例。

AUTHENTICATION

在访问Zabbix内部的任何数据之前，需要登录并获得身份验证令牌。可以使用 [user.login](https://www.zabbix.com/documentation/current/manual/api/reference/user/login) 方法。假设您希望以标准Zabbix管理用户的身份登录。然后您的JSON请求将是这样的:
//

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

让我们仔细看看request对象。它具有以下特性:

jsonrpc - API使用的JSON-RPC协议版本;Zabbix API实现了JSON-RPC 2.0版本;
method - 被调用的API方法;
params - 将传递给API方法的参数;
id - 请求的任意标识符;
auth -用户身份验证令牌;因为我们还没有，所以它被设为 null

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

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

响应对象又包含以下属性:

jsonrpc - 同样，JSON-RPC协议的版本;
result - 该方法返回的数据;
id - 对应请求的标识符。
RETRIEVING HOSTS
我们现在有一个有效的用户身份验证令牌，可以使用它访问Zabbix中的数据。例如，让我们使用 [host.get](https://www.zabbix.com/documentation/current/manual/api/reference/host/get) 方法检索所有配置的id、主机名和接口 hosts:

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

注意，现在auth属性被设置为我们通过调用user.login获得的身份验证令牌。
响应对象将包含请求的关于主机的数据:

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

出于性能原因，我们建议始终列出想要检索的对象属性，并避免检索所有内容。

创建新项

让我们创建一个新的 item 在“Zabbix server”利用我们从前面得到的数据 host.get 请求。可以通过使用 [item.create](https://www.zabbix.com/documentation/current/manual/api/reference/item/create) 方法

{
    "jsonrpc": "2.0",
    "method": "item.create",
    "params": {
        "name": "Free disk space on $1",
        "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 方法以及其他创建方法也可以接受对象数组，并通过一个API调用创建多个项。

创建多个触发器

如果创建方法接受数组，我们可以添加多个触发器，像这样:

{
    "jsonrpc": "2.0",
    "method": "trigger.create",
    "params": [
        {
            "description": "Processor load is too high on {HOST.NAME}",
            "expression": "{Linux server:system.cpu.load[percpu,avg1].last()}>5",
        },
        {
            "description": "Too many processes on {HOST.NAME}",
            "expression": "{Linux server:proc.num[].avg(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
}

这 item.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](https://www.zabbix.com/documentation/current/manual/api/reference/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
}

如果发生错误，响应对象将包含一个错误属性，而不是结果属性，该属性包含以下数据:

code - 一个错误代码;
message - 简短的错误总结;
data - 更详细的错误消息。

错误可能发生在不同的情况下，例如，使用不正确的输入值、会话超时或试图访问不存在的对象。您的应用程序应该能够优雅地处理这类错误。

API版本

为了简化API版本控制，自Zabbix 2.0.4以来，API的版本与Zabbix本身的版本相匹配。你可以使用 [apiinfo.version](https://www.zabbix.com/documentation/current/manual/api/reference/apiinfo/version) 方法查找要使用的API的版本。这对于调整应用程序以使用特定于版本的特性非常有用。
我们保证主要版本的向后兼容性。当在主要版本之间进行向后不兼容的更改时，我们通常会在下一个版本中保留旧的特性，只在之后的版本中删除它们。偶尔，我们可能会在不提供向后兼容性的情况下删除主要版本之间的特性。重要的是，您永远不要依赖任何过时的特性，并尽快迁移到新的替代方案。
方法中对API所做的所有更改 API changelog.

api_jsonrpc

概述

结构