附录 1. 参考注释

标记法

数据类型

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

类型	描述
boolean	boolean值，接受`true`或`false`。
flag	如果值存在且不等于`null`，则视为`true`；否则视为`false`。
integer	整型数字。
float	浮点数字。
string	文本string。
text	长文本string。
timestamp	Unix时间戳。
array	有序值序列，即普通array。
object	关联型array。
query	定义应返回数据的值。可定义为属性名array以返回特定属性，或使用预定义值： `extend` - 返回所有object属性； `count` - 返回检索记录数（仅部分子查询支持）。

Zabbix API始终仅返回字符串或数组类型的值。

属性标签

部分objects属性带有简短标签以描述其行为。使用的标签如下：

readonly - 该属性的值由系统自动设置，客户端无法定义或修改；
constant - 该属性的值在创建object时可设置，但之后不可更改。

保留的 ID 值 "0"

保留ID值"0"可用于过滤元素和移除被引用的objects。例如，要从主机中移除被引用的proxy，应将proxy_hostid设置为0（"proxy_hostid": "0"）；或要通过服务器选项proxyids过滤主机时，应将其设置为0（"proxyids": "0"）。

通用"get"方法参数

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

参数	类型	描述
countOutput	boolean	返回结果中的记录数而非实际数据。
editable	boolean	如果设置为`true`，则仅返回用户具有写入权限的objects。默认值：`false`。
excludeSearch	boolean	返回不符合`search`参数中给定条件的结果.
filter	object	仅返回与给定筛选条件完全匹配的结果。接受一个object，其中键为属性名称（例如`host.get`中的主机 object属性、`item.get`中的监控项 object属性等），值为单个值或用于匹配的array值集合。不支持`text`数据类型的属性。注意某些方法对此参数有特定功能，详见方法页面说明（例如host.get中的`filter`参数还支持主机接口属性）。
limit	integer	限制返回的记录数量。
output	query	要返回的object属性。默认值: `extend`.
preservekeys	boolean	在生成的array中使用ID作为键。
search	object	返回与给定模式匹配的结果（不区分大小写）。接受一个object，其中键为属性名称（例如`host.get`中的主机 object属性、`item.get`中的监控项 object属性等），值为要搜索的字符串。若未提供额外选项，将执行`LIKE "%…%"`搜索。仅支持`string`和`text`数据类型的属性。注意：部分方法对此参数有特定功能，详见方法页面说明（例如host.get中的`search`参数还支持主机接口属性）。
searchByAny	boolean	若设置为`true`，则返回符合`filter`或`search`参数中任意条件的匹配结果，而非全部条件。默认值：`false`。
searchWildcardsEnabled	boolean	若设置为`true`，则允许在`search`参数中使用"*"作为通配符。默认值: `false`.
sortfield	string/array	按给定属性对结果进行排序。具体可用的排序属性列表请参考特定的API get方法说明。宏在排序前不会被展开。若未指定值，数据将按未排序状态返回。
sortorder	string/array	排序顺序。如果传入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
       }

零结果表示没有具有读写权限的主机

不匹配计数

统计名称中不包含子字符串"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"，结果将以关联array的形式返回，其中键是objects的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
       }

Documentation