基於Zabbix API文檔二次開發與java接口封裝

時間 2019-11-11

標籤基於 zabbix api 文檔二次開發 java 接口封裝欄目 Zabbix 简体版

原文原文鏈接

(繼續貼一篇以前工做期間寫的經驗案例)java

1、 案例背景git

我負責開發過一個平臺的監控報警模塊，基於zabbix實現，須要對zabbix進行二次開發。express

Zabbix官方提供了Rest API的文檔，並推薦了第三方庫，但這些庫都是zabbix老版本(2.2,2.4/3.0)的庫，多年未更新過，且變量/方法命名都不符合java的駝峯式規範。api

因此開發中基於3.4的文檔，本身封裝了一套庫。結合二次開發中對zabbix業務邏輯的理解與實踐，梳理總結出該篇接口開發文檔。app

2、 基礎知識url

二次開發前，zabbix的業務術語和基本的業務邏輯須要瞭解清楚。orm

包括模板、應用、監控項、觸發器、事件、異常、動做等。xml

參考官方手冊：blog

https://www.zabbix.com/documentation/3.4/zh/manual/definitionstoken

重點說明下problem 與 event:

觸發器被觸發時，會生成一個 problem event 記錄, 當問題恢復正常時，會生成一個recovery event記錄，兩個event的時間差，即爲事件持續時間。全部的event都存在於同一張表。對應接口25）報警時間查詢

problem存在於一張單獨的表，每一條記錄對應了兩個事件，即problem event 和 recovery event。對應接口24）報警數據查詢。

這張表zabbix後臺會按期清理，problem事件恢復30分鐘後，會被從表中刪除。

因此若是要查當前的報警事件，去problem裏查；若是要查事件的歷史記錄，到event裏查，而且要對problem event 與 recovery event 進行匹配計算，一個開始對應一個結束，纔算一條歷史報警記錄。

3、 接口封裝與使用詳解（代碼見第五節的連接）

1) 登錄

zabbix登錄token的保留時間很是長，一次登錄後，基本可數週內不用從新登錄

/**
* @return 登錄zabbix後臺true/false
*/
Boolean login();

2) 在線狀態

/**

 * 判斷zabbix是否已 在線（可用，並已登錄），沒有的話 嘗試登錄

 * @return 在線/重連成功，返回1；自系統啓動首次登錄成功返回2； 不在線，且重連失敗，返回0

 */

Integer OnLine();

3) 請求zabbix後臺，並返回結果

做爲最基礎的訪問zabbix後臺的接口，其餘接口都是基於它實現的。

/**

 * 封裝了 RestTemplate 請求 與 zabbix 自動重連功能

 * @param zabbixMethod  請求方法

 * @param zabbixParams  請求參數

 * @return result Object

 */

ZabbixResponse requestZabbixForObject(String zabbixMethod, Object zabbixParams);

4) 模板-xml導入

對於用戶來講，讓他們配置一個至關複雜的「模板-應用集-監控項-觸發器」是頗有難度的，這些應該是開發人員作的事，用戶只管會用就能夠。因此咱們把這些配置梳理好後，以xml文件的形式發給用戶，用戶只需上傳模板，便可完成整個複雜的建立過程。

/**

 * 導入xml模板

 * @param sourceXml

 * @return
  */

Boolean  importConfiguration(Document sourceXml);

5) 模板-Id 查詢

/**

 * 根據模板host名稱(全英文的那個名字 在zabbix後臺惟一標識模板) 查詢 模板在zabbix後臺的id

 * @param tempLateHostName

 * @return
  */

String getTemplateIdByHostName(String tempLateHostName);

6) 主機羣組(host group)-Id查詢

- 主機的邏輯組；它包含主機和模板。建立主機/模板時，必須指定其所屬的主機羣組，因此須要事先建立（導入模板xml時即會建立）。一個主機組裏的主機和模板之間並無任何直接的關聯。一般在給不一樣用戶組的主機分配權限時候使用主機組。

/**

 * 根據group名稱，查詢group在zabbix後臺的id

 * @param groupName

 * @return
  */

String getGroupIdByName(String groupName);

7) 主機-建立

/**

 * 建立主機

 * @param hostIps 主機ip列表

 * @param groupId 所屬分組id(zabbix)

 * @return 按hostIps 的順序 返回 對應的hostId

 */

List<String> createHost(List<String> hostIps,String groupId);

8) 主機-查詢所有

返回的Map以ip地址爲key,hostId爲value, 方便對返回值快速的搜索查詢

/**

 * 查詢所有主機

 * @return key 主機host(Ip), value 主機hostId

 */

Map<String,String> getHostAll();

9) 模板-關聯主機（批量）

關聯成功後，會生成實際的監控項和觸發器

/**

 * 批量將機器hostIds（zabbix後臺的hostId）（列表） 與 模板關聯

 * @param templateId

 * @param hostIds

 * @return
  */

Boolean templateMassAdd(String templateId,List<String> hostIds);

10) 模板-取消關聯主機（批量）

/**

 * 主機(批量) 取消 模板連接 並清理-（會刪掉主機監控項）

 * @param hostIds  須要取消模板關聯的主機id列表

 * @param templateId 須要取消關聯的 模板id

 * @return
  */

Boolean hostMassRemoveTemplate(List<String> hostIds,String templateId);

11) 模板-查詢關聯的全部主機

這個接口其實更爲通用，能夠在params 中指定查詢條件，查詢返回全部符合條件的主機，此處要查詢模板關聯的機器，只需在params中指定templateids 便可，參數格式參考官方文檔：

https://www.zabbix.com/documentation/3.4/manual/api/reference/host/get

示例

(先聲明List<String> templateIds)

zabbixService.getHosts(new HashMap(){{

put("templateids",templateIds);

}});

/**

 * 查詢 模板關聯的全部機器

 * @param params

 默認參數:

{

"output": ["hostid","host"]

}

 * @return
  */

List<ZabbixHost> getHosts(Map params);

12) 模板-刪除（批量）

/**

 * 批量刪除模板，會清理掉模板當前所關聯主機的全部監控項（已與模板解除關聯的主機，其監控項不會被清理)

 * @param templateIds

 * @return
  */

Boolean templateMassDelete(List<String> templateIds);

13) 主機-刪除（批量）

/**

 * 批量刪除主機

 * @param hostIds 主機列表

 * @return
  */

Boolean hostDelete(List<String> hostIds);

14) 監控項-查詢1

關聯查詢應用，觸發器，主機

/**

 * 查詢主機關聯的全部的監控項

 * @param params {@link <a href = "https://www.zabbix.com/documentation/3.4/manual/api/reference/item/get">item.get</a>}

選填參數：

{

   "hostids":["10205"],

   "itemids":["27692","27707"],

   "triggerids":["12345"]

}

默認參數：

{

"output":["itemid","name","key_","delay","history","status","flags","units","lastvalue","value_type"],

"selectApplications": ["applicationid","name","hostid","templateids"],

"selectTriggers":["triggerid","templateid","description","expression","comments","status","priority","value"],

"selectHosts":["hostid","host"]

}

 * @return Item列表 或 空Array

 */

List<ZabbixItem> getItems(Map params);

15) 監控項-查詢2

關聯查詢應用，主機；

/**

 * 查詢監控項數據，和監控項關聯的host，無用的字段不查

 * @param params

 默認參數

{

"output":["itemid","name","lastclock","lastvalue","lastvalue","prevvalue","status","units"],

"selectApplications": ["applicationid","name","hostid","templateids"],

"selectHosts":["hostid","host"]

}

 * @return Item列表key-zabbixItemId 或 空Map

 */

Map<String,ZabbixItem> getItemData(Map params);

16) 應用-查詢-根據id

每一個application都有個parentId和hostid, 根據parentId 向上回溯查詢application，當其parentId爲null時，對應的hostId才指向Template.

/**

 * 根據application Id 查詢 application 詳情

 * @param Id

 * @return application 或 null

 */

ZabbixApplication getApplicationById(String Id);

17) 應用-查詢-根據id（批量）

/**

 * 批量查詢，根據application Ids 查詢 applications 詳情

 * @param ids

 * @return key 爲applicationId

 */

Map<String,ZabbixApplication> getApplicationsByIds(List<String> ids);

18) 應用-查詢-根據模板id

/**

 * 批量查詢，根據application Ids 查詢 applications 詳情

 * @param ids

 * @return key 爲applicationId

 */

Map<String,ZabbixApplication> getApplicationsByIds(List<String> ids);

19) 觸發器-查詢

/**

 * 獲取全部的觸發器

 * doc:

 * @see <a href = "https://www.zabbix.com/documentation/3.4/manual/api/reference/trigger/get">trigger.get</a>

 * @param params

 * 默認參數:

 {

    "output":["triggerid","description","priority","value","expression","status","comments"],

    "selectItems":["itemid","lastvalue","units"],

    "selectHosts":["host","hostid"]

 }

 * @return map  key = {@link ZabbixTrigger#triggerId} , value = {@link ZabbixTrigger}; 或空Map

 */

Map<String,ZabbixTrigger> getTriggers(Map params);

20) 監控項-修改

/**

 * 根據itemId 修改 item

 * @param items 字段itemId 必填，只支持修改delay,history,status

 * @return
  */

Boolean itemsUpdate(List<ZabbixItem> items);

21) 觸發器-修改

/**

 * 根據triggerId 修改 trigger

 * @param triggers 字段triggerId 必填，只支持修改 status,comments,expression,

 *                 注意:經過模板關聯生成的trigger 只能修改status,comments,其餘是改不了的，會失敗

 * @return  true/false

 */

Boolean triggersUpdate(List<ZabbixTrigger> triggers);

22) 應用-監控項-組織結構查詢-根據主機id

/**

 * 根據hostIds 查詢關聯的application-Item 組織（組織結點 主要包含Id 和 name）

 * @param hostIds

 * @return
  */

List<ZabbixApplication> getApplicationAndItemOrgByHostId(List<String> hostIds);

23) 最新監控數據-查詢

若要查詢模板關聯的監控項，先查模板關聯的機器，而後調用該接口進行查詢。

/**

 * 查詢 監控數據，以主機ID 和 applicationName 做爲過濾條件

 * 會過濾掉 已被禁用的監控項數據

 * @param hostIds

 * @param appNames 爲空 時，查詢所有數據

 * @return application-item

 */

List<ZabbixApplication> getLatestItemData(List<String> hostIds,List<String> appNames);

24) 報警數據-查詢

/**

 * 查詢報警數據 --來自觸發器

 * @param params 查詢參數

 * 默認參數：

 {

    "output": "extend",

    "sortfield": ["eventid"],

    "sortorder": "DESC",

    "recent":"true",

    "selectAcknowledges": "extend"

 }

 * @see <a href="https://www.zabbix.com/documentation/3.4/manual/api/reference/problem/get">problem.get</a>

 * ctrl + 單擊 查看url連接

 * @return {@link ZabbixProblem}

 */

List<ZabbixProblem> getProblems(Map params);

25) 報警事件查詢

/**

 * 查詢報警事件 --來自觸發器

 * @param params

 * 默認參數：

 {  "output": "extend",

    "sortfield": ["clock", "eventid"],

    "sortorder": "DESC",

    "select_acknowledges":"extend",

    "selectRelatedObject":["triggerid","description","priority","value"],

    "selectHosts":["hostid","host"]

 }

 * @see <a href="https://www.zabbix.com/documentation/3.4/manual/api/reference/event/get">event.get</a>

 * @return {@link ZabbixProblem}

 */

List<ZabbixProblem> getEvents(Map params);

26) 關閉觸發器

忽略並關閉報警事件

/**
* 關閉觸發器
* @param events 需關閉的event 列表
* 默認參數：
{
"message": "忽略",
"action": 1
}
* @return
*/
Boolean acknowledgeEvents(List<String> events);

27) 歷史數據-查詢

查詢指定監控項的歷史數據

參數history 表示返回值類型，摘錄一段官方文檔解釋：

History object types to return.

Possible values:
0 - numeric float;
1 - character;
2 - log;
3 - numeric unsigned;
4 - text.

Default: 3.

就是說實際的數據類型和參數 history的類型必須一致，不然會致使查不到數據。

因此查以前，須要先查詢肯定監控項的數據類型valueType.

/**
* 查監控項的歷史數據
* @param params itemids string/array 監控項id 必填 "history":3, 必填-不填或者類型不對將查不到數據
* @see <a href="https://www.zabbix.com/documentation/3.4/manual/api/reference/history/get">history.get</a>
必填參數:
{
"itemids": ["27702"]
}
默認參數：
{
"sortfield":"clock",
"sortorder":"DESC"
}

* @return
*/
List<ZabbixHistory> getHistory(Map params);

28) 圖表-查詢配置

若是要查圖表數據，須要先查圖表配置，而後對圖表配置中的監控項id, 經過getHistory接口查詢監控項的歷史數據。

/**

 * 查詢圖表配置信息

 * @param params

 默認參數:

params.put("output",new ArrayList(){{

add("graphid");

add("name");

add("graphtype");

}});



params.put("selectGraphItems",new ArrayList(){{

add("gitemid");

add("itemid");

add("color");

}});



params.put("selectItems",new ArrayList(){{

add("itemid");

add("name");

}});

 * @return
  */

List<GraphConfig> getGraphConfig(Map params);

29) 圖表-建立

/**

 * 建立監控圖表

 * @param graphConfig

 * @return
  */

GraphConfig createGraph(GraphConfig graphConfig) throws Exception;

30) 圖表-修改

/**

 * 更新監控圖表

 * @param graphConfig

 * @return
  */

GraphConfig updateGraph(GraphConfig graphConfig) throws Exception;

31) 圖表-刪除

/**

 * 刪除圖表

 * @param params  圖表id

 * @return
  * @throws Exception

 */

Boolean deleteGraph(List params) throws Exception;

4、 監控數據單位轉換

從zabbix 後臺查詢到的監控數據，都是最小單位，如時間的單位是秒s，存儲的單位是B，流量的單位是B/s.

因此須要自適應進行轉換，轉成KB/s 或者 MB/s等。

1）轉成最合適，無溢出的單位

/**

 * @param value 原始數據

 * @param units 原始單位

 * @return 轉成最合適 無溢出的單位

 */

public static UnitsFormatResult transformValueByUnits(String value,String units)

2) 轉成指定單位的數據

繪製圖表時，每一個數據須要單位一致，纔有可比性，才能進行正確的繪製，所以會用到此方法。

/**

 *

 * @param value 原始數據

 * @param units 原始單元

 * @param targetUnits 目標單位

 * @return
  */

public static UnitsFormatResult transformValueToTargetUnits(String value,String units,String targetUnits)