附录 1. 参考说明

附录 1. 参考说明

注释

数据类型

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

类型	描述
ID	用于引用实体的唯一标识符。
boolean	布尔值（`true` 或 `false`）。
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 “%…%”`搜索。仅支持`string`和`text`数据类型的属性。
searchByAny	布尔值	如果设置为`true`，则返回与`filter`或`search`参数中给出的任何条件匹配的结果，而不是与所有条件匹配的结果。默认值：`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
       }