附录 1. 参考说明

注释

数据类型

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

类型 描述
ID 用于引用实体的唯一标识符。
boolean 布尔值(truefalse)。
flag 如果传递的值不等于 null,则被视为 true;否则,该值被视为 false
integer 整数。
float 浮点数。
string 文本字符串。
text 更长的文本字符串。
timestamp Unix时间戳。
array 有序值序列(普通数组)。
object 关联数组。
query 定义要返回的数据的值。该值可以定义为属性名称的数组(仅返回特定属性),或作为以下预定义值之一:
extend - 返回所有对象属性;
count - 返回检索到的记录数,仅由某些子查询支持。

Zabbix API 返回结果为字符串或数组。

属性行为

某些对象属性带有简短的标签来描述其行为。以下标签被使用:

  • 只读 - 属性的值会自动设置,用户无法定义或更改,即使在某些特定条件下(例如,对于继承的对象或发现的对象,为只读);
  • 只写 - 可以设置属性的值,但之后无法访问;
  • 常量 - 在创建对象时可以设置属性的值,但之后无法更改;
  • 支持 - 在某些特定条件下允许设置属性的值,但不需要设置(例如,如果type设置为"简单检查"、"外部检查"、"SSH代理"、"TELNET代理"或"HTTP代理",则为支持);
  • 必需 - 对于所有操作(除了获取操作)或在某些特定条件下,需要设置属性的值(例如,对于创建操作为必需;如果operationtype设置为"全局脚本"且未设置opcommand_hst,则为必需)。

对于更新操作,如果在更新操作期间设置属性,则认为该属性为"设置"。

未标记标签的属性是可选的。

参数行为

一些操作参数带有简短的标签,用于描述它们在操作中的行为。 使用的标签如下:

  • 只读 - 参数的值会自动设置,用户无法定义或更改,即使在某些特定条件下(例如,对于继承的对象或发现的对象,为只读);
  • 只写 - 可以设置参数的值,但之后无法访问;
  • 支持 - 在某些特定条件下允许设置参数的值,但不需要设置(例如,如果代理对象的operating_mode设置为"被动代理",则为支持);
  • 必需 - 必须设置参数的值。

未标记标签的参数是可选的。

预留ID值“0”

保留的ID值“0”可用于过滤元素和删除引用对象。 - 例如,要从主机中删除 proxy 的代理,应将proxyid设置为0(“proxyid”:“0”) - 或用于过滤由zabbix server监控的主机,proxyids设置为0(“proxyids”:“0”)。

常用的 "get" 方法参数

The following parameters are supported by all get methods:

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

参数 类型 描述
countOutput 布尔值 返回结果中的记录数,而不是实际数据。
editable 布尔值 如果设置为true,则仅返回用户具有写入权限的对象。

默认值:false
excludeSearch 布尔值 返回与search参数中给定的条件不匹配的结果。
filter 对象 仅返回与给定过滤器完全匹配的结果。

接受一个对象,其中键是属性名,值是单个值或要与之匹配值的数组。

不支持text数据类型的属性。
limit 整数 限制返回的记录数。
output 查询 要返回的对象属性。

默认值:extend
preservekeys 布尔值 在结果数组中使用ID作为键。
search 对象 返回与给定模式匹配的结果(不区分大小写)。

接受一个对象,其中键是属性名,值是要搜索的字符串。如果没有给出其他选项,则执行LIKE "%…%"搜索。

仅支持stringtext数据类型的属性。
searchByAny 布尔值 如果设置为true,则返回与filtersearch参数中给出的任何条件匹配的结果,而不是与所有条件匹配的结果。

默认值:false
searchWildcardsEnabled 布尔值 如果设置为true,则允许在search参数中使用"*"作为通配符字符。

默认值:false
sortfield string/array 按给定属性对结果排序。有关可用于排序的属性列表,请参考特定的 API get 方法描述。在排序之前不解析宏。

如果未指定值,则返回的数据将是未排序的。
sortorder string/array 排序次序。如果传递的是数组,则每个值将与sortfield 参数中给定的对应属性匹配。

可能的值:
ASC - (默认) 升序;
DESC - 降序.
startSearch boolean search 参数将比较字段的开头,即执行LIKE "…%"模糊搜索。

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

示例

用户权限检查

用户是否有权写入以"MySQL"或"Linux"开头的主机?

请求

{
           "jsonrpc": "2.0",
           "method": "host.get",
           "params": {
               "countOutput": true,
               "search": {
                   "host": ["MySQL", "Linux"]
               },
               "editable": true,
               "startSearch": true,
               "searchByAny": true
           },
           "id": 1
       }

响应:

{
           "jsonrpc": "2.0",
           "result": "0",
           "id": 1
       }

返回结果是 "0" 意思是没有主机具有 "读/写" 权限。

不匹配统计

计算名称不包含子字符串"ubuntu"的主机数量

请求:

{
           "jsonrpc": "2.0",
           "method": "host.get",
           "params": {
               "countOutput": true,
               "search": {
                   "host": "ubuntu"
               },
               "excludeSearch": true
           },
           "id": 1
       }

响应:

{
           "jsonrpc": "2.0",
           "result": "44",
           "id": 1
       }

使用通配符搜索主机

查找名称包含单词"server"且主机接口的端口号为"10050"或"10071"的主机。按主机名降序排序,并限制只输出5个主机。

请求:

{
           "jsonrpc": "2.0",
           "method": "host.get",
           "params": {
               "output": ["hostid", "host"],
               "selectInterfaces": ["port"],
               "filter": {
                   "port": ["10050", "10071"]
               },
               "search": {
                   "host": "*server*"
               },
               "searchWildcardsEnabled": true,
               "searchByAny": true,
               "sortfield": "host",
               "sortorder": "DESC",
               "limit": 5
           },
           "id": 1
       }

响应:

{
           "jsonrpc": "2.0",
           "result": [
               {
                   "hostid": "50003",
                   "host": "WebServer-Tomcat02",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },
               {
                   "hostid": "50005",
                   "host": "WebServer-Tomcat01",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },
               {
                   "hostid": "50004",
                   "host": "WebServer-Nginx",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },
               {
                   "hostid": "99032",
                   "host": "MySQL server 01",
                   "interfaces": [
                       {
                           "port": "10050"
                       }
                   ]
               },
               {
                   "hostid": "99061",
                   "host": "Linux server 01",
                   "interfaces": [
                       {
                           "port": "10050"
                       }
                   ]
               }
           ],
           "id": 1
       }

使用"preservekeys"和通配符搜索主机

如果您在前面的请求中添加参数“preservekeys”,则结果将作为关联数组返回,其中键是对象的id。

请求:

{
           "jsonrpc": "2.0",
           "method": "host.get",
           "params": {
               "output": ["hostid", "host"],
               "selectInterfaces": ["port"],
               "filter": {
                   "port": ["10050", "10071"]
               },
               "search": {
                   "host": "*server*"
               },
               "searchWildcardsEnabled": true,
               "searchByAny": true,
               "sortfield": "host",
               "sortorder": "DESC",
               "limit": 5,
               "preservekeys": true
           },
           "id": 1
       }

响应:

{
           "jsonrpc": "2.0",
           "result": {
               "50003": {
                   "hostid": "50003",
                   "host": "WebServer-Tomcat02",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },
               "50005": {
                   "hostid": "50005",
                   "host": "WebServer-Tomcat01",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },
               "50004": {
                   "hostid": "50004",
                   "host": "WebServer-Nginx",
                   "interfaces": [
                       {
                           "port": "10071"
                       }
                   ]
               },
               "99032": {
                   "hostid": "99032",
                   "host": "MySQL server 01",
                   "interfaces": [
                       {
                           "port": "10050"
                       }
                   ]
               },
               "99061": {
                   "hostid": "99061",
                   "host": "Linux server 01",
                   "interfaces": [
                       {
                           "port": "10050"
                       }
                   ]
               }
           },
           "id": 1
       }