Documentation
Table of Contents
19. API
概览
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://example.com/zabbix， 那么用HTTP请求来调用 apiinfo.version 方法就如下面这样：
POST http://example.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- JSON-RPC 协议的版本；result- 方法返回的数据；id- 对应请求的标识符。
Authorization methods
By "Authorization" header
All API requests require an authentication or an API token. You can provide the credentials by using the "Authorization" request header:
curl --request POST \
--url 'https://company.com/zabbix/ui/api_jsonrpc.php' \
--header 'Authorization: Bearer 0424bd59b807674191e7d77572075f33'By "auth" property
An API request can be authorized by the "auth" property.
Note that the "auth" property is deprecated. It will be removed in the future releases.
curl --request POST \
--url 'https://company.com/zabbix/ui/api_jsonrpc.php' \
--header 'Content-Type: application/json-rpc' \
--data '{"jsonrpc":"2.0","method":"host.get","params":{"output":["hostid"]},"auth":"0424bd59b807674191e7d77572075f33","id":1}'By Zabbix cookie
A "zbx_session" cookie is used to authorize an API request from Zabbix UI performed using JavaScript (from a module or a custom widget).
检索主机
我们现在有一个有效的用户身份认证 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，可用于在以后请求中引用该监控项：
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 数组：
更新监控项
启用监控项，即将其状态设置为“0”：
{
"jsonrpc": "2.0",
"method": "item.update",
"params": {
"itemid": "10092",
"status": 0
},
"auth": "0424bd59b807674191e7d77572075f33",
"id": 5
}操作成功的响应将包含被更新监控项的 ID：
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数组：
这是更新的首选方法。有些 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
}如果发生错误，响应对象将包含 error 属性而不是 result 属性，同时 error 包含以下数据：
code- 错误代码；message- 一个简短的错误摘要；data- 更详细的错误消息。
错误可能发生在不同的情况下，例如，使用不正确的输入值，会话超时或试图访问不存在的对象。你的应用程序应该能够优雅地处理这些类型的错误。
API 版本
为了简化API版本控制，自 Zabbix 2.0.4 开始，API 的版本与 Zabbix 本身的版本相匹配。你可以使用 apiinfo.version 方法查找你正在使用的 API 的版本。 这对于调整应用程序以使用特定于版本的功能非常有用。
我们保证在主要版本内部具有向后兼容性。在主要版本之间进行向后不兼容的更改时，通常会在下一个版本中保留旧功能，并在之后的版本中将其删除。有时，我们可能会在不提供任何向后兼容性的情况下删除主要版本之间的功能。重要的是，永远不要依赖任何已弃用的功能，并尽快迁移到较新的替代项。
你可以在 API changelog 中跟踪对API所做的所有更改。
进一步阅读
您现在知道了足够的知识，可以开始使用 Zabbix API，但不要停在这里。我们建议你对 可用的 API 列表 做进一步阅读。