On this page
附录 1. 参考注释
标记法
数据类型
Zabbix API 支持以下数据类型作为输入：
| 类型 | 描述 |
|---|---|
| ID | 用于引用实体的唯一标识符。 |
| 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 总是仅以字符串或数组形式返回值。
属性行为
某些 object 属性使用简短的标签来描述其行为。使用了以下标签：
- 只读 - 该属性的值由系统自动设置，用户无法定义或更改，即使在某些特定条件下也是如此（例如，继承的 objects 或发现的 objects 的 只读 属性）；
- 只写 - 该属性的值可以设置，但设置后无法访问；
- 常量 - 该属性的值在创建 object 时可以设置，但之后无法更改；
- 支持 - 该属性的值不是必须设置的，但在某些特定条件下允许设置（例如，当
type设置为 "Simple check"、"External check"、"SSH agent"、"TELNET agent" 或 "HTTP agent" 时为 支持）；但是请注意，支持 的属性仍可能被设置为其默认值，无论条件如何； - 必填 - 该属性的值在所有操作中（除 get 操作外）都必须设置，或者在某些特定条件下必须设置（例如，对于 create 操作为 必填；当
operationtype设置为 "全局脚本" 且opcommand_hst未设置时为 必填）。
对于 update 操作，当在 update 操作期间设置属性时，该属性被视为“已设置”。
未标记标签的属性是可选的。
参数行为
某些操作参数使用简短的标签进行标记，以描述该操作的行为特征。使用的标签如下：
- read-only - 参数的值由系统自动设置，用户无法定义或更改，即使在某些特定条件下也是如此（例如，继承的 objects 或发现的 objects 的 read-only）；
- write-only - 参数的值可以设置，但设置后无法访问；
- supported - 参数的值不需要设置，但在某些特定条件下允许设置（例如，当 Proxy object 的
operating_mode设置为 "passive proxy" 时为 supported）；但请注意，无论条件如何，supported 参数仍可能被设置为其默认值； - required - 参数的值必须设置。
未标记的参数为可选参数。
保留的 ID 值 "0"
保留的 ID 值 "0" 可用于筛选元素并移除引用的 objects。例如，要从一个 主机 中移除引用的 proxy，proxyid 应设置为 0（"proxyid": "0"）；或者，要筛选服务器选项 proxyids 所监控的 主机，proxyids 应设置为 0（"proxyids": "0"）。
常见的 "get" 方法参数
所有 get 方法都支持以下参数：
| Parameter | Type | Description |
|---|---|---|
| countOutput | boolean | 返回结果中的记录数，而不是实际数据。 |
| editable | boolean | 如果设置为 true，则仅返回用户具有写权限的对象。默认值： false。 |
| excludeSearch | boolean | 返回不符合 search 参数中给定条件的结果。 |
| filter | object | 仅返回与给定过滤条件完全匹配的结果。 接受一个对象，其中键为属性名称（例如， host.get 中的 Host 对象属性、item.get 中的 Item 对象属性等），值可以是单个值或用于匹配的值数组。不支持 text data type 类型的属性。请注意，某些方法对该参数有特定功能，相关说明见对应方法页面（例如，host.get 中的 filter 参数也支持 Host interface 属性）。 |
| limit | integer | 限制返回的记录数量。 |
| output | query | 要返回的对象属性。 请注意，即使未在 output 参数中指定，对象 ID（即 hostid、itemid 等）也始终会包含在响应中。默认值： extend。 |
| preservekeys | boolean | 在结果数组中使用 ID 作为键。 |
| search | object | 返回与给定模式匹配的结果（不区分大小写）。 接受一个对象，其中键为属性名称（例如， host.get 中的 Host 对象属性、item.get 中的 Item 对象属性等），值为要搜索的字符串。如果未提供其他选项，则执行 LIKE "%…%" 搜索。仅支持 string 和 text data type 类型的属性。请注意，某些方法对该参数有特定功能，相关说明见对应方法页面（例如，host.get 中的 search 参数也支持 Host interface 属性）。 |
| 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，则忽略该参数。 |
示例
用户权限检查
用户是否有权限写入名称以 "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
}结果为零表示没有具有读/写权限的 主机。
不匹配计数
统计名称中不包含子字符串“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
}Response:
{
"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
},
"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
}