附录 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 agent"、"TELNET agent"或"HTTP agent",则为支持);然而,注意支持属性仍可能在不考虑条件的情况下设置为其默认值;
  • 必需 - 所有操作(除获取操作外)或在某些特定条件下(例如,对于创建操作;如果operationtype设置为"全局脚本"且未设置opcommand_hst,则为必需)都要求设置属性的值。

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

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

参数行为

一些操作参数被标记为简短标签,以描述它们在操作中的行为。使用了以下标签:

  • read-only - 参数的值自动设置,用户即使在某些特定条件下也无法定义或更改(例如,对于继承的对象或发现的对象,标记为read-only);
  • write-only - 参数的值可以设置,但设置后无法访问;
  • supported - 参数的值无需设置,但在某些特定条件下允许设置(例如,如果Proxy对象的operating_mode设置为"passive proxy",则标记为supported);然而,需要注意的是,即使在任何条件下,supported参数仍可能被设置为其默认值;
  • required - 必须设置参数的值。

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

预留ID值“0”

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

常见的 "get" 方法参数

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

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

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

接受一个对象,其中键是属性名称(例如,host.get 中的 Host 对象属性,item.get 中的 Item 对象属性等),值是单个值或与之匹配的值数组。

不支持 text 数据类型的属性。

请注意,某些方法对此参数具有特定功能,这些功能在方法页面上进行了描述(例如,host.get 中的 filter 参数还支持 Host 接口属性)。
limit 整数 限制返回的记录数量。
output 查询 要返回的对象属性。

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

接受一个对象,其中键是属性名称(例如,host.get 中的 Host 对象属性,item.get 中的 Item 对象属性等),值是用于搜索的字符串。如果没有给出其他选项,这将执行 LIKE "%…%" 搜索。

仅支持 stringtext 数据类型的属性。

请注意,某些方法对此参数具有特定功能,这些功能在方法页面上进行了描述(例如,host.get 中的 search 参数还支持 Host 接口属性)。
searchByAny 布尔值 如果设置为 true,返回与 filtersearch 参数中任何标准匹配的结果,而非所有标准。

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

默认:false
sortfield 字符串/数组 根据给定属性对结果进行排序。参考特定的API get方法描述以获取可用于排序的属性列表。在排序之前不扩展宏。

如果没有指定值,数据将以未排序的形式返回。
sortorder 字符串/数组 排序顺序。如果传递数组,每个值将与 sortfield 参数中给出的相应属性匹配。

可能的值:
ASC - (默认) 升序;
DESC - 降序。
startSearch 布尔值 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
       }