第13章 Zabbix API的使用

作者: super_pcm | 来源:发表于2021-04-10 23:44 被阅读0次

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

第13章 Zabbix API的使用

13.1 Zabbix API简介

13.2 JSON-RPC

13.3 Zabbix API的使用流程

13.3.1 使用API的基本步骤

13.3.2 如何使用官方文档获取帮助

13.3.3 使用CURL调用API

13.3.4 HTTP头部Content-Type设置

13.3.5 用户认证结果的返回值

13.3.7 添加主机（host.create）

13.3.8 删除主机（host.delete）

13.4 第三方Zabbix API模块

13.5 编写命令行管理工具zbx-tool

相关文章

网友评论

延伸阅读

深度阅读

栏目导航

热点阅读

Zabbix