Zabbix的API非常丰富，界面上能够完成的操作几乎都可以通过API来实现。因此，Zabbix很容易实现与第三方程序的集成。本章将介绍Zabbix API的使用方法。通过本章的学习，读者可以加深对Zabbix API的理解并灵活运用。
13.1 Zabbix API简介
Zabbix API具有重要的功能，为第三方调用Zabbix、批量操作提供可编程接口，从而实现Zabbix监控平台与第三方系统集成。
Zabbix API是基于前端HTTP协议实现的，数据格式采用JSONRPC协议。
由于Zabbix的Web前端是用PHP语言编写的，PHP本身的性能与其相关配置参数有极大的关系。因此，在大型环境中使用需要对PHP进行优化，可以使用最新版本PHP 7，以及通过对前端进行负载均衡、服务器性能优化等技术提高PHP处理性能。
13.2 JSON-RPC
JSON-RPC是基于JSON的跨语言远程调用协议，比XML-RPC、WebService等基于文本的协议传输数据量要小。目前主流语言都有JSON-RPC的实现框架。
- JSON-RPC协议描述
JSON-RPC协议非常简单，发起远程调用时向服务器传输数据的格式如下：
{"method": "getid", "params": ["arg"], "id": 1}
参数说明如下：
- method：调用的方法名。
- params：方法传入的参数，若无参数，则传入[]。
- id：调用标识符，用于标识一次远程调用过程。
服务器接收到JSON-RPC的调用请求后，处理该请求的方法调用，然后将结果返回调用方。返回的数据格式如下：
{
"result": "id is 000",
"error": null,
"id": 1
}
参数说明如下：
- result：方法返回值，若无返回值或调用出错，则返回null。
- error：调用时发生错误，若无错误则返回null。·
- id：调用标识符，与调用方传入的标识符一致。
以上就是JSON-RPC协议规范的内容，它非常简单、小巧，且便于用各种语言实现。
- Zabbix API支持的数据类型
Zabbix API支持的基本数据类型如表13-1所示。
| 类 型 | 说 明 |
|---|---|
| bool | 布尔值为true或者false |
| flag | 当该值不等于空或者false时，被认为是true |
| integer | 整数 |
| float | 浮点数 |
| string | 文本字符串 |
| timestamp | UNIX 时间戳 |
| array | 数组 |
| object | 关联数组 |
| query | 可以是一个数值，也可以是部分参数· extend：返回所有的对象值· count：返回值的数量 |
当使用查询操作（get方法）时，可以使用更多的参数，查询操作支持的参数如表13-2所示。
| 参 数 | 类 型 | 描 述 |
|---|---|---|
| countOutput | flag | 返回结果的个数，而非实际的数据 |
| editable | boolean | 如果设置为true，用户可对返回的对象进行写操作。默认值为false |
| excludeSearch | flag | 返回不匹配给定参数的结果 |
| filter | object | 返回过滤后的结果，参数的值可以为一个数组或者单个值，text字段不能使用此参数 |
| limit | integer | 限制返回结果的数量 |
| nodeids | string/array | 返回给定节点的对象信息 |
| output | query | 返回对象的属性。默认值为extend |
| preservekeys | flag | 返回以ID为键的数组 |
| search | object | 搜索匹配的字符串，仅用于字符和文本字段 |
| searchByAny | boolean | 如果设置为true，则返回 filter 或search字段中所有的值。默认值为false |
| searchWildcardsEnabled | boolean | 如果设置为true，允许使用“*”作为搜索参数的通配符。默认值为false |
| sortfield | string/array | 对给定的参数属性进行排序 |
| sortorder | string/array | 排序。ASC为升序排列；DESC为降序排列 |
| startSearch | flag | 搜索以某个参数开始的结果 |
- Zabbix API代码入口文件路径
Zabbix API代码入口文件路径如下：
/usr/share/zabbix/api_jsonrpc.php
API调用时的URL是http://x.x.x.x/zabbix/api_jsonrpc.php。
13.3 Zabbix API的使用流程
13.3.1 使用API的基本步骤
使用API的基本步骤如下：
（1）连接http://x.x.x.x/zabbix/api_jsonrpc.php，提供用户名和密码，并标识HTTP头部Content-Type":"application/json", HTTP方法为POST。
（2）获取sessionid。
（3）通过sessionid建立后续的连接。
（4）提交POST数据，格式为JSON，按需提供参数，获取相关的数据。
13.3.2 如何使用官方文档获取帮助
使用Zabbix API需要大量地参考官方文档中列举的用法，我们先学习如何使用官方文档。例如，需要获取Host的信息，查看官方文档，地址如下：
https://www.zabbix.com/documentation/4.0/manual/api/reference/host/get
官方文档给了一个查询实例，如下所示。
{
"jsonrpc": "2.0",
"method": "host.get",
"params": {
"filter": {
"host": [
"Zabbix server",
"Linux server"
]
}
},
"auth": "038e1d7b1735c6a5436ee9eae095879e",
"id": 1
}
13.3.3 使用CURL调用API
下面我们通过Linux下的命令行工具CURL来熟悉API的使用过程。如果读者熟悉Postman等HTTP请求工具，也可以使用该工具进行数据请求，原理一样。
（1）获取sessionid，命令如下：
shell# curl -X POST \
-H 'Content-Type:application/json' \
-d '{"jsonrpc": "2.0",
"method":"user.login",
"params":{"user":"Admin",
"password":"zabbix"},
"auth": null,
"id":0
}' \
http://127.0.0.1/zabbix/api_jsonrpc.php
（2）使用sessionid请求来调用API的host.get方法，命令如下：
shell# curl -X POST \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0",
"method":"host.get",
"params":{
"output":"extend",
"filter":{"host":""}
},
"auth":"b545519b2e2f7b08e1a63b360f24b533",
"id":1
}' \
http://127.0.0.1/zabbix/api_jsonrpc.php
至此，我们已经学会了API的调用方法，下面我们来学习更多的例子。
13.3.4 HTTP头部Content-Type设置
HTTP头部Content-Type必须被设置为application/json；否则返回HTTP状态码为412的错误.
13.3.5 用户认证结果的返回值
认证成功的提示内容如下：
得到的结果如下：
{
"jsonrpc":"2.0",
"result":"b545519b2e2f7b08e1a63b360f24b533",
"id":0
}
### 13.3.6 获取主机信息（用Python实现的示例）
```python
#!/usr/bin/env python
#coding=utf-8
#导入模块，urllib2是一个模拟浏览器HTTP方法的模块
import json
import urllib2
import sys
from urllib2 import Request, urlopen, URLError, HTTPError
#url and url header
#zabbix的api 地址，用户名，密码，这里修改为自己实际的参数
zabbix_url="http://127.0.0.1/zabbix/api_jsonrpc.php"
zabbix_header = {"Content-Type":"application/json"}
zabbix_user = "Admin"
zabbix_pass = "zabbix"
auth_code = ""
#auth user and password
#用户认证信息的部分，最终的目的是得到一个SESSIONID
#这里是生成一个json格式的数据，用户名和密码
auth_data = json.dumps(
{
"jsonrpc":"2.0",
"method":"user.login",
"params":
{
"user":zabbix_user,
"password":zabbix_pass
},
"id":0
})
# create request object
request = urllib2.Request(zabbix_url,auth_data)
for key in zabbix_header:
request.add_header(key,zabbix_header[key])
#auth and get authid
try:
result = urllib2.urlopen(request)
#对于出错新的处理
except HTTPError, e:
print 'The server couldn\'t fulfill the request, Error code: ', e.code
except URLError, e:
print 'We failed to reach a server.Reason: ', e.reason
else:
response=json.loads(result.read())
result.close()
#判断SESSIONID是否在返回的数据中
if 'result' in response:
auth_code=response['result']
else:
print response['error']['data']
# request json
json_data={
"method":"host.get",
"params":{
"output": "extend",
}
}
json_base={
"jsonrpc":"2.0",
"auth":auth_code,
"id":1
}
json_data.update(json_base)
#用得到的SESSIONID去通过验证，获取主机的信息（用http.get方法）
if len(auth_code) == 0:
sys.exit(1)
if len(auth_code) != 0:
get_host_data = json.dumps(json_data)
# create request object
request = urllib2.Request(zabbix_url,get_host_data)
for key in zabbix_header:
request.add_header(key,zabbix_header[key])
# get host list
try:
result = urllib2.urlopen(request)
except URLError as e:
if hasattr(e, 'reason'):
print 'We failed to reach a server.'
print 'Reason: ', e.reason
elif hasattr(e, 'code'):
print 'The server could not fulfill the request.'
print 'Error code: ', e.code
else:
response = json.loads(result.read())
result.close()
#将所有的主机信息显示出来
print response['result'][0]
#显示主机的个数
#print "Number Of Hosts: ", len(response['result'])
13.3.7 添加主机（host.create）
添加主机的方法，请参考官方文档，地址如下：
https://www.zabbix.com/documentation/4.0/manual/api/reference/host/create
官方文档中列出了host.create的用法，如下所示。
官方文档中列出了host.create的用法，如下所示。
{'
auth': '038e1d7b1735c6a5436ee9eae095879e',
'id': 1,
'jsonrpc': '2.0',
'method': 'host.create',
'params': {'groups': [{'groupid': '50'}],
'host': 'Linux server[是否是：servers]'[此处需要复数],
'interfaces': [{'dns': '',
'ip': '192.168.3.1',
'main': 1,
'port': '10050',
'type': 1,
'useip': 1}],
'inventory': {'macaddress_a': '01234', 'macaddress_b': '56768'},
'templates': [{'templateid': '20045'}]}
}
上述代码表示添加IP地址为192.168.3.1、主机名为“Linux servers”的这台主机，将其放在id为50的主机组中，引用id为20045的模板。
由于官方示例中的部分参数值并不是实际环境的参数值，所以在API中使用时需要替换为实际环境的参数值。
在MySQL数据库中查询模板id（严格地说，获取模板id也应该通过API），确保存在此id。这里选用Template OS Linux模板，通过数据库查询到其id为10001，因此host.create中的templateid参数值为10001。
下面是python的示例：
修改代码中的参数值，替换为实际参数值，如下所示。
shell# vim zabbix_api_host_create.py
{
'method': 'host.create',
'params': {'groups': [{'groupid': '2'}],
'host': 'Web Linux server',
'interfaces': [{'dns': '',
'ip': '192.168.8.1',
'main': 1,
'port': '10050',
'type': 1,
'useip': 1}],
'inventory': {'macaddress_a': '01234', 'macaddress_b': '56768'},
'templates': [{'templateid': '10001'}]}
}
运行代码，结果显示主机创建成功，hostid为10284（后续会用到）。
shell# python zabbix_api_host_create.py
{
'jsonrpc': '2.0',
'result': {'hostids[是否多了一个s][正确]': ['10284']},
'id': 1
}
13.3.8 删除主机（host.delete）
删除主机的方法，请参考官方文档，地址如下：
https://www.zabbix.com/documentation/4.0/manual/api/reference/host/delete
官方文档给出的示例如下：
{
'jsonrpc': '2.0',
'method': 'host.delete',
'params': [
'13',
'32'
],
'auth': '038e1d7b1735c6a5436ee9eae095879e',
'id': 1
}
上述介绍表示删除hostid为13和32的两台主机。
现在，我们使用API删除上一节刚添加的hostid为10284的这台主机，将参数值修改为10284，如下所示。
shell# vim zabbix_api_host_delete.py
json_data={
"method":"host.delete",
"params":['10284']
}
运行脚本，如下所示。
shell# python zabbix_api_host_delete.py
{
u"jsonrpc": "2.0",
u"result": {
u"hostids": [
u"10284"
]
},
u"id": 1
}
通过前面的学习，我们掌握了获取主机信息，以及添加、删除主机的API用法。其他更多API的用法基本都是类似的，具体请读者参考官方文档，地址如下：
https://www.zabbix.com/documentation/4.0/manual/api
13.4 第三方Zabbix API模块
官方收集的模块都是用各种语言编写的，读者可以选用自己熟悉的语言来使用现有的模块，地址如下：
https://zabbix.org/wiki/Docs/api/libraries
这里以pyzabbix为例，简单讲解其使用方法。
shell# pip install pyzabbix #如图13-3所示
13.5 编写命令行管理工具zbx-tool
本节我们来实现主机的命令行管理工具zbx-tool，项目地址如下：
https://github.com/zabbix-book/zbx_tool
