附录 1. 参考说明

附录 1. 参考说明

注释

数据类型

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

类型	描述
boolean	布尔值，接受`true`或`false`。
flag	如果传递的值不为`null`和`false`，认为其值是`true`。
integer	整数。
float	浮点数。
string	文本字符串。
text	长文本字符串。
timestamp	Unix 时间戳。
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方法都支持以下参数：

参数	类型	描述
countOutput	boolean	返回结果中的记录数，而不是实际的数据。
editable	boolean	如果设置为`true`，则只返回用户具有写权限的对象。默认：`false`。
excludeSearch	boolean	返回与在`search`参数中给定条件不匹配的结果。
filter	object	仅返回与给定过滤条件完全匹配的结果。接受一个数组，键是属性名，值是单个值或者要匹配值的数组。不适用于`text` 字段。
limit	integer	限制返回记录的数量。
output	query	要返回的对象属性。默认：`extend`。
preservekeys	boolean	在结果数组中，用ID作为键。
search	object	返回给定通配符（不区分大小写）匹配到的结果。接受一个数组，键是属性名，值是要搜索的字符串。如果没有给出其他选项，将会执行`LIKE “%…%”`搜索。仅适用于`string`和`text`字段。
searchByAny	boolean	如果设置为`true`，则返回与`filter` or `search`参数中给定的任何条件匹配的结果，而不是所有条件。默认：`false`。
searchWildcardsEnabled	boolean	如果设置为`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
           },
           "auth": "766b71ee543230a1182ca5c44d353e36",
           "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
           },
           "auth": "766b71ee543230a1182ca5c44d353e36",
           "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
           },
           "auth": "766b71ee543230a1182ca5c44d353e36",
           "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
           },
           "auth": "766b71ee543230a1182ca5c44d353e36",
           "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
       }