On this page
附录 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设置为 "Simple check"、"External check"、"SSH agent"、"TELNET agent" 或 "HTTP agent" 时为 支持）；但请注意，无论条件如何，支持 属性仍可能被设置为其默认值； - 必需 - 对于所有操作（get 操作除外）或在某些特定条件下，必须设置属性值（例如，创建操作时为 必需；当
operationtype设置为 "global script" 且未设置opcommand_hst时为 必需）。
对于更新操作，属性在更新操作期间被设置时，即视为“已设置”。
未标记这些标签的属性为可选。
参数行为
部分操作参数带有简短标签，用于说明该参数在操作中的行为。使用以下标签：
- 只读 - 参数值会自动设置，用户无法定义或更改，即使在某些特定条件下也是如此（例如，继承对象或发现对象的 只读 参数）；
- 只写 - 参数值可以设置，但之后无法访问；
- 支持 - 不要求必须设置参数值，但在某些特定条件下允许设置（例如，当 Proxy 对象的
operating_mode设置为“passive proxy”时，参数为 支持）；但请注意，无论条件如何，支持 参数仍可能被设置为其默认值； - 必填 - 必须设置参数值。
未标记标签的参数为可选。
预留ID值“0”
保留的ID值“0”可用于过滤元素和删除引用对象。
- 例如，要从主机中删除 proxy 的代理，应将proxyid设置为0（“proxyid”：“0”）
- 或用于过滤由zabbix server监控的主机，proxyids设置为0（“proxyids”：“0”）。
通用 "get" 方法参数
以下参数受所有 get 方法支持：
| 参数 | 类型 | 说明 |
|---|---|---|
| countOutput | boolean | 返回结果中的记录数，而不是实际数据。 |
| editable | boolean | 如果设置为 true，则仅返回用户具有写权限的对象。默认值： false。 |
| excludeSearch | boolean | 返回与 search 参数中给定条件不匹配的结果。 |
| filter | object | 仅返回与给定过滤条件完全匹配的结果。 接受一个对象，其中键为属性名称（例如， host.get 中的主机对象属性、item.get 中的监控项对象属性等），值可以是单个值或用于匹配的值数组。不支持 text 数据类型 的属性。请注意，某些方法对此参数具有特定功能，详见相应的方法页面（例如，host.get 中的 filter 参数还支持主机接口属性）。 |
| limit | integer | 限制返回的记录数。 |
| output | query | 要返回的对象属性。 请注意，对象 ID（即 hostid、itemid 等）始终包含在响应中，即使未在 output 参数中指定也是如此。默认值： extend。 |
| preservekeys | boolean | 在结果数组中使用 ID 作为键。 |
| search | object | 返回与给定模式匹配的结果（不区分大小写）。 接受一个对象，其中键为属性名称（例如， host.get 中的主机对象属性、item.get 中的监控项对象属性等），值为要搜索的字符串。如果未提供其他选项，将执行 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 | 排序顺序。如果传递的是数组，则每个值将与 sortfield 参数中给定的相应属性对应。可能的值： ASC - (默认) 升序；DESC - 降序。 |
| startSearch | boolean | search 参数将比较字段的开头，即改为执行 LIKE "…%" 搜索。如果 searchWildcardsEnabled 设置为 true，则忽略此参数。 |
实体来源标志
Get 方法会为与低级发现相关的实体（LLD 规则/LLD 规则原型、监控项/监控项原型等）返回一个 flags 属性。此属性可用于标识实体是否已被发现，因为对已发现实体的编辑受到限制。
flags 属性会根据以下这些值的组合（“+”运算）返回结果：
| Value | Description |
|---|---|
| 0 | 基础实体（监控项、触发器、图形、主机） |
| 1 | 低级发现规则 |
| 2 | 任意原型（监控项原型、触发器原型、LLD 规则原型等） |
| 4 | 已发现实体（已发现的监控项、触发器、图形、主机、LLD 规则） |
flags 属性返回的组合值可能为：
| Value | Combination of | Description |
|---|---|---|
| 0 | 0 | 普通实体（监控项、触发器、图形、主机）。 |
| 2 | 2 | 实体原型（监控项原型、触发器原型等）。 |
| 6 | 2+4 | 已发现的监控项、触发器、图形、主机（由原型转换而来）。 |
| 1 | 1 | 低级发现规则。 |
| 3 | 1+2 | 低级发现规则原型。 |
| 5 | 1+4 | 已发现的低级发现规则（由原型转换而来）。 |
| 7 | 1+2+4 | 已发现的低级发现规则原型。 |
示例
用户权限检查
用户是否有权写入以"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
}