第13章 Zabbix API的使用

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的实现框架。

  1. 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协议规范的内容,它非常简单、小巧,且便于用各种语言实现。

  1. 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 搜索以某个参数开始的结果
  1. 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章 Zabbix API的使用_第1张图片

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

本节我们来实现主机的命令行管理工具zbx-tool,项目地址如下:
https://github.com/zabbix-book/zbx_tool

你可能感兴趣的:(第13章 Zabbix API的使用)