19. 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_utils Python 库用于 Zabbix API。
结构
API 由一系列方法组成，这些方法名义上被分组到不同的 API 中。每种方法执行一个特定任务。例如，host.create 方法属于 host API，用于创建新的主机。从历史上看，API 有时被称为 "类"。
大多数 API 至少包含四种方法：get, create, update 和 delete，分别用于获取、创建、更新和删除数据，但有些 API 可能提供完全不同的一组方法。
执行请求
一旦您设置好了前端，就可以使用远程 HTTP 请求来调用 API。为此，您需要发送 HTTP POST 请求到前端目录中的 api_jsonrpc.php 文件。例如，如果您的 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 返回的响应应该像这样：
响应对象依次包含以下属性：
jsonrpc- JSON-RPC 协议的版本；result- 方法返回的数据；id- 对应请求的标识符。
示例工作流程
下面的部分将以更详细的示例向您展示一些使用方法。
认证
要在 Zabbix 中访问任何数据，您需要：
- 使用现有的 API 令牌（在 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 返回的响应应该包含用户认证令牌：
获取主机
现在您有一个有效的用户认证令牌，可以用来访问 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.jsondata.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 可用于在随后的请求中引用该监控项。
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：
更新监控项
将监控项的状态设置为“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：
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：
这是更新的首选方法。一些 API 方法，如 host.massupdate，允许编写更简洁的代码。 然而，不建议使用这些方法，因为它们将在未来版本中被移除。
错误处理
到目前为止，您尝试的所有操作都运行得很好。但是，如果您尝试对 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 列表。