附录 1. 参考说明

注释

数据类型

Zabbix API支持输入以下数据类型:

类型描述
boolean布尔值,接受truefalse
flag如果传递的值不为nullfalse,认为其值是true
integer整数。
float浮点数。
string文本字符串。
text长文本字符串。
timestampUnix 时间戳。
array有序的值序列,即普通数组。
object关联数组。
query用于定义应返回的数据。

可定义为仅返回指定属性的属性名称数组,或者预定值的其中一个:
extend - 返回所有的对象属性;
count - 返回检索到的记录数量,仅支持某些子查询。

Zabbix API始终仅以字符串或数组的形式返回值。

属性标签

一些对象属性用短标签来描述它们的行为。可使用以下标签:

  • readonly - 属性值是自动设置的,不能被客户端定义或修改;
  • constant - 属性值可以在创建对象时被设置,创建后不能被修改。

Parameter behavior

Some of the operation parameters are marked with short labels to describe their behavior for the operation. The following labels are used:

  • read-only - the value of the parameter is set automatically and cannot be defined or changed by the user, even in some specific conditions (e.g., read-only for inherited objects or discovered objects);
  • write-only - the value of the parameter can be set, but cannot be accessed after;
  • supported - the value of the parameter is not required to be set, but is allowed to be set in some specific conditions (e.g., supported if status of Proxy object is set to “passive proxy”);
  • required - the value of the parameter is required to be set.

Parameters that are not marked with labels are optional.

预留ID值“0”

预留ID值“0”,可以用来过滤元素和删除引用的对象。例如,从主机中删除一个引用的代理,proxy_hostid 应该设置为 0 (“proxy_hostid”: “0”), 或者要过滤被zabbix server监控的主机,proxyids 选项应该被设置为 0 (“proxyids”: “0”)。

通用“get”方法参数

所有的get方法都支持以下参数:

参数类型描述
countOutputboolean返回结果中的记录数,而不是实际的数据。
editableboolean如果设置为true,则只返回用户具有写权限的对象。

默认:false
excludeSearchboolean返回与在search参数中给定条件不匹配的结果。
filterobject仅返回与给定过滤条件完全匹配的结果。

接受一个数组,键是属性名,值是单个值或者要匹配值的数组。

不适用于text 字段。
limitinteger限制返回记录的数量。
outputquery要返回的对象属性。

默认:extend
preservekeysboolean在结果数组中,用ID作为键。
searchobject返回给定通配符(不区分大小写)匹配到的结果。

接受一个数组,键是属性名,值是要搜索的字符串。如果没有给出其他选项,将会执行LIKE “%…%”搜索。

仅适用于stringtext字段。
searchByAnyboolean如果设置为true,则返回与filter or search参数中给定的任何条件匹配的结果,而不是所有条件。

默认:false
searchWildcardsEnabledboolean如果设置为true,则可以在search参数中使用”*”作为通配符。

默认:false
sortfieldstring/array按照给定的属性对结果进行排序。可用于排序的属性列表,请参考特定API get方法描述。宏在排序前不会被展开。

如果没有给出特定的值,数据会无序返回。
sortorderstring/array排序顺序。如果传递数组,则每个值都将与sortfield参数中给定的对应属性匹配。

可用值:
ASC - (默认) 升序;
DESC - 降序。
startSearchbooleansearch参数比较字段的开始,即执行LIKE “…%”搜索。

如果searchWildcardsEnabled设置为true,则忽略。

示例

用户权限检查

用户是否有权限修改以“MySQL”或“Linux”开头的主机?

请求:

  1. {
  2. "jsonrpc": "2.0",
  3. "method": "host.get",
  4. "params": {
  5. "countOutput": true,
  6. "search": {
  7. "host": ["MySQL", "Linux"]
  8. },
  9. "editable": true,
  10. "startSearch": true,
  11. "searchByAny": true
  12. },
  13. "auth": "766b71ee543230a1182ca5c44d353e36",
  14. "id": 1
  15. }

响应:

  1. {
  2. "jsonrpc": "2.0",
  3. "result": "0",
  4. "id": 1
  5. }

结果0,表示没有具有读/写权限的主机。

不匹配统计

统计名称中不包含“ubuntu”的主机数量。

请求:

  1. {
  2. "jsonrpc": "2.0",
  3. "method": "host.get",
  4. "params": {
  5. "countOutput": true,
  6. "search": {
  7. "host": "ubuntu"
  8. },
  9. "excludeSearch": true
  10. },
  11. "auth": "766b71ee543230a1182ca5c44d353e36",
  12. "id": 1
  13. }

响应:

  1. {
  2. "jsonrpc": "2.0",
  3. "result": "44",
  4. "id": 1
  5. }

使用通配符搜索主机

查找名称中包含单词“server”,并且接口端口是“10050”或“10071”的主机。结果按照主机名称倒序排序,并且限制返回5台主机。

请求:

  1. {
  2. "jsonrpc": "2.0",
  3. "method": "host.get",
  4. "params": {
  5. "output": ["hostid", "host"],
  6. "selectInterfaces": ["port"],
  7. "filter": {
  8. "port": ["10050", "10071"]
  9. },
  10. "search": {
  11. "host": "*server*"
  12. },
  13. "searchWildcardsEnabled": true,
  14. "searchByAny": true,
  15. "sortfield": "host",
  16. "sortorder": "DESC",
  17. "limit": 5
  18. },
  19. "auth": "766b71ee543230a1182ca5c44d353e36",
  20. "id": 1
  21. }

响应:

  1. {
  2. "jsonrpc": "2.0",
  3. "result": [
  4. {
  5. "hostid": "50003",
  6. "host": "WebServer-Tomcat02",
  7. "interfaces": [
  8. {
  9. "port": "10071"
  10. }
  11. ]
  12. },
  13. {
  14. "hostid": "50005",
  15. "host": "WebServer-Tomcat01",
  16. "interfaces": [
  17. {
  18. "port": "10071"
  19. }
  20. ]
  21. },
  22. {
  23. "hostid": "50004",
  24. "host": "WebServer-Nginx",
  25. "interfaces": [
  26. {
  27. "port": "10071"
  28. }
  29. ]
  30. },
  31. {
  32. "hostid": "99032",
  33. "host": "MySQL server 01",
  34. "interfaces": [
  35. {
  36. "port": "10050"
  37. }
  38. ]
  39. },
  40. {
  41. "hostid": "99061",
  42. "host": "Linux server 01",
  43. "interfaces": [
  44. {
  45. "port": "10050"
  46. }
  47. ]
  48. }
  49. ],
  50. "id": 1
  51. }

加上 “preservekeys”参数使用通配符搜索主机

如果将参数“preservekeys”添加到上一个请求中,结果会返回一个关联数组,键是对象的id。

请求:

  1. {
  2. "jsonrpc": "2.0",
  3. "method": "host.get",
  4. "params": {
  5. "output": ["hostid", "host"],
  6. "selectInterfaces": ["port"],
  7. "filter": {
  8. "port": ["10050", "10071"]
  9. },
  10. "search": {
  11. "host": "*server*"
  12. },
  13. "searchWildcardsEnabled": true,
  14. "searchByAny": true,
  15. "sortfield": "host",
  16. "sortorder": "DESC",
  17. "limit": 5,
  18. "preservekeys": true
  19. },
  20. "auth": "766b71ee543230a1182ca5c44d353e36",
  21. "id": 1
  22. }

响应:

  1. {
  2. "jsonrpc": "2.0",
  3. "result": {
  4. "50003": {
  5. "hostid": "50003",
  6. "host": "WebServer-Tomcat02",
  7. "interfaces": [
  8. {
  9. "port": "10071"
  10. }
  11. ]
  12. },
  13. "50005": {
  14. "hostid": "50005",
  15. "host": "WebServer-Tomcat01",
  16. "interfaces": [
  17. {
  18. "port": "10071"
  19. }
  20. ]
  21. },
  22. "50004": {
  23. "hostid": "50004",
  24. "host": "WebServer-Nginx",
  25. "interfaces": [
  26. {
  27. "port": "10071"
  28. }
  29. ]
  30. },
  31. "99032": {
  32. "hostid": "99032",
  33. "host": "MySQL server 01",
  34. "interfaces": [
  35. {
  36. "port": "10050"
  37. }
  38. ]
  39. },
  40. "99061": {
  41. "hostid": "99061",
  42. "host": "Linux server 01",
  43. "interfaces": [
  44. {
  45. "port": "10050"
  46. }
  47. ]
  48. }
  49. },
  50. "id": 1
  51. }