[comment]: # ({92f30379-92f30379}) # 19 API [comment]: # ({/92f30379-92f30379}) [comment]: # ({f3807be5-13405b49}) ### 概述 Zabbix API 允许您以编程方式检索和修改 Zabbix的配置，并提供对历史数据的访问。它被 广泛用于： - 创建与Zabbix协同工作的新应用程序； - 将Zabbix与第三方软件集成； - 自动化日常任务。 Zabbix API 是一个基于Web的API，作为Web 前端的一部分提供。它使用JSON-RPC 2.0协议，这意味着两点： - API 由一组独立的方法组成； - 客户端与API之间的请求和响应经过编码 using the JSON format. 有关协议和JSON的更多信息，请参阅[JSON-RPC 2.0 specification](http://www.jsonrpc.org/specification)和[JSON format homepage](http://json.org/)。 有关将Zabbix功能集成到Python应用程序中的更多信息，请参阅用于Zabbix API的[zabbix_utils](https://github.com/zabbix/python-zabbix-utils) Python库。 [comment]: # ({/f3807be5-13405b49}) [comment]: # ({9cb56d09-9cb56d09}) ### 结构 API由多个方法组成，这些方法名义上被分组到不同的API中。每个方法执行一个特定任务。例如，`host.create`方法属于*主机* API，用于create新的主机。历史上，API有时被称为"类"。 ::: notetip 大多数API至少包含四种方法：`get`、`create`、`update`和`delete`，分别用于检索、创建、更新和删除数据，但某些API可能提供完全不同的方法集。 ::: [comment]: # ({/9cb56d09-9cb56d09}) [comment]: # ({e4e06a45-9cb2f5ca}) ### 执行请求 完成前端配置后，您可通过远程HTTP请求调用API。为此需向位于前端目录的`api_jsonrpc.php` file发送HTTP POST请求。例如： 若Zabbix前端安装在*http://example.com/zabbix*路径下，调用`apiinfo.version`方法的HTTP请求示例如下： ```yaml 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`。 [comment]: # ({/e4e06a45-9cb2f5ca}) [comment]: # ({ec5a9f60-ec5a9f60}) ### 示例工作流 以下部分将更详细地介绍一些使用示例。 [comment]: # ({/ec5a9f60-ec5a9f60}) [comment]: # ({b4227e17-ef3f5841}) #### 认证 要访问Zabbix中的任何数据，您需要： - 使用现有的[api-令牌](/manual/web_interface/frontend_sections/administration/general#api-令牌)（在Zabbix前端创建或使用[Token API](/manual/api/reference/token)）； - 使用通过[user.login](/manual/api/reference/user/login)方法获取的身份验证令牌。 例如，如果您想以标准*Admin*用户身份登录获取新的身份验证令牌，JSON请求将如下所示： ```json { "jsonrpc": "2.0", "method": "user.login", "params": { "username": "Admin", "password": "zabbix" }, "id": 1, "auth": null } ``` 让我们仔细看看请求object。它具有以下属性： - `jsonrpc` - API使用的JSON-RPC协议的version； Zabbix API实现了JSON-RPC version 2.0； - `method` - 调用的API方法； - `params` - 传递给API方法的参数； - `id` - 请求的任意标识符； 如果省略，API会将请求视为[notification](https://www.jsonrpc.org/specification#notification)； - `auth` - 用户身份验证令牌；由于我们还没有， it's set to `null`. `null`。 如果您提供了正确的凭据，API返回的响应将包含用户身份验证令牌： ```json { "jsonrpc": "2.0", "result": "0424bd59b807674191e7d77572075f33", "id": 1 } ``` 响应object包含以下属性： - `jsonrpc` - 再次是JSON-RPC协议的version； - `result` - 方法返回的数据； - `id` - 对应请求的标识符。 [comment]: # ({/b4227e17-ef3f5841}) [comment]: # ({61809060-f572ecc2}) #### 检索主机 我们现在拥有一个有效的用户认证令牌，可用于访问Zabbix中的数据。例如，让我们使用 [host.get](/manual/api/reference/host/get)方法来获取所有已配置 [hosts](/manual/api/reference/host/object)的ID、 主机名称和接口信息： ```json { "jsonrpc": "2.0", "method": "host.get", "params": { "output": [ "hostid", "host" ], "selectInterfaces": [ "interfaceid", "ip" ] }, "id": 2, "auth": "0424bd59b807674191e7d77572075f33" } ``` ::: noteimportant 请注意`auth`属性现在被设置为我们通过调用 `user.login`获得的认证令牌。 ::: 响应object将包含所请求的主机数据： ```json { "jsonrpc": "2.0", "result": [ { "hostid": "10084", "host": "Zabbix server", "interfaces": [ { "interfaceid": "1", "ip": "127.0.0.1" } ] } ], "id": 2 } ``` ::: notetip 出于性能考虑，我们建议始终列出您需要获取的 object属性，避免获取全部数据。 ::: [comment]: # ({/61809060-f572ecc2}) [comment]: # ({e4c060f4-ee2c324f}) #### 创建新的 监控项 让我们基于从上一个`host.get`请求获取的数据，在"Zabbix服务器"上create一个新的[item](/manual/api/reference/item/object)。这可以通过使用[item.create](/manual/api/reference/item/create)方法实现： ```json { "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，该ID可用于在后续请求中引用该监控项： ```json { "jsonrpc": "2.0", "result": { "itemids": [ "24759" ] }, "id": 3 } ``` ::: notetip `item.create`方法以及其他create方法也可以接受objects数组，并通过一次API调用来create多个监控项。 ::: [comment]: # ({/e4c060f4-ee2c324f}) [comment]: # ({e511a956-5ed44978}) #### 创建多个触发器 如果create方法接受数组参数，我们可以像这样批量添加 [triggers](/manual/api/reference/trigger/object)： ```json { "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数组： ```json { "jsonrpc": "2.0", "result": { "triggerids": [ "17369", "17370" ] }, "id": 4 } ``` [comment]: # ({/e511a956-5ed44978}) [comment]: # ({2a515812-aa174634}) #### 更新 监控项 启用一个监控项，即将其状态设置为"0": ```json { "jsonrpc": "2.0", "method": "item.update", "params": { "itemid": "10092", "status": 0 }, "auth": "0424bd59b807674191e7d77572075f33", "id": 5 } ``` 成功响应将包含更新后的监控项的ID: ```json { "jsonrpc": "2.0", "result": { "itemids": [ "10092" ] }, "id": 5 } ``` ::: notetip `item.update`方法以及其他update方法 也可以接受objects数组，并通过一次API 调用update多个监控项。 ::: [comment]: # ({/2a515812-aa174634}) [comment]: # ({3772c85a-e217b4a2}) #### 更新多个触发器 启用多个触发器，即将它们的状态设置为0： ```json { "jsonrpc": "2.0", "method": "trigger.update", "params": [ { "triggerid": "13938", "status": 0 }, { "triggerid": "13939", "status": 0 } ], "auth": "0424bd59b807674191e7d77572075f33", "id": 6 } ``` 成功的响应将包含已更新触发器的ID： ```json { "jsonrpc": "2.0", "result": { "triggerids": [ "13938", "13939" ] }, "id": 6 } ``` ::: notetip 这是推荐的更新方法。某些API 方法如`host.massupdate`允许编写更简单的代码，但 不建议使用这些方法，因为它们将在未来版本中被移除。 ::: [comment]: # ({/3772c85a-e217b4a2}) [comment]: # ({0ba3cefc-7665e280}) #### 错误处理 到目前为止我们尝试的所有操作都运行良好。但如果尝试错误调用API会发生什么？让我们通过调用[host.create](/manual/api/reference/host/create)但省略必需的`groups`参数来create另一个主机。 ```json { "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" } ``` 响应将包含错误信息： ```json { "jsonrpc": "2.0", "error": { "code": -32602, "message": "Invalid params.", "data": "No groups for host \"Linux server\"." }, "id": 7 } ``` 如果发生错误，响应object将不再包含`result`属性，而是包含带有以下数据的`error`属性： - `code` - 错误代码； - `message` - 简短的错误摘要； - `data` - 更详细的错误信息。 错误可能发生在不同场景中，例如使用错误的输入值、会话超时或尝试访问不存在的objects。您的应用程序应能妥善处理这类错误。 [comment]: # ({/0ba3cefc-7665e280}) [comment]: # ({db15f318-c1074d48}) ### API 版本 为简化API版本管理，自Zabbix 2.0.4起，API的version 与Zabbix自身的version保持一致。您可通过 [apiinfo.version](/manual/api/reference/apiinfo/version)方法查询 当前使用的API的version。这有助于调整应用程序以使用 version专属功能。 我们保证在主版本version内的功能向后兼容性。当主版本间存在 不兼容变更时，通常会在下一版本中将旧功能标记为弃用，并在 后续版本中移除。极少数情况下，我们可能不提供兼容层就直接 移除主版本间的功能。请务必避免依赖任何弃用功能，并尽快 迁移至新方案。 ::: notetip 您可通过[API changelog](/manual/api/changes_5.4_-_6.0)跟踪 API的所有变更记录。 ::: [comment]: # ({/db15f318-c1074d48}) [comment]: # ({dfd7315f-dfd7315f}) ### 延伸阅读 您现在已掌握足够知识开始使用Zabbix API，但请不要止步于此。建议您进一步阅读[list of available APIs](/manual/api/reference)以深入学习。 [comment]: # ({/dfd7315f-dfd7315f})