[comment]: # translation:outdated

[comment]: # ({6d056871-6d056871})
# 附录 1. 参考说明

[comment]: # ({/6d056871-6d056871})

[comment]: # ({6594bdc4-6594bdc4})
### 注释

[comment]: # ({/6594bdc4-6594bdc4})

[comment]: # ({8c926b1a-2df08058})
#### 数据类型

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

|类型|描述|
|----|----|
|ID|用于引用实体的唯一标识符。|
|boolean|布尔值（`true` 或 `false`）。|
|flag|如果传递的值不等于 `null`，则被视为 `true`；否则，该值被视为 `false`。|
|integer|整数。|
|float|浮点数。|
|string|文本字符串。|
|text|更长的文本字符串。|
|timestamp|Unix时间戳。|
|array|有序值序列（普通数组）。 |
|object|关联数组。|
|query|定义要返回的数据的值。该值可以定义为属性名称的数组（仅返回特定属性），或作为以下预定义值之一：<br>`extend` - 返回所有对象属性；<br>`count` - 返回检索到的记录数，仅由某些子查询支持。|

::: noteimportant
Zabbix API 返回结果为字符串或数组。
:::

[comment]: # ({/8c926b1a-2df08058})

[comment]: # ({8f68b338-a2c16a18})
#### 属性行为

某些对象属性会用简短标签标记，以描述其行为。使用的标签如下：

-   ***只读*** - 属性值会自动设置，用户无法定义或更改，即使在某些特定条件下也是如此（例如，继承对象或发现对象的 *只读* 属性）；
-   ***只写*** - 属性值可以设置，但之后无法访问；
-   ***常量*** - 属性值可在创建对象时设置，但之后无法更改；
-   ***支持*** - 不要求设置属性值，但在某些特定条件下允许设置（例如，当 `type` 设置为 "Simple check"、"External check"、"SSH agent"、"TELNET agent" 或 "HTTP agent" 时为 *支持*）；但请注意，无论条件如何，*支持* 属性仍可能被设置为其默认值；
-   ***必需*** - 对于所有操作（get 操作除外）或在某些特定条件下，必须设置属性值（例如，创建操作时为 *必需*；当 `operationtype` 设置为 "global script" 且未设置 `opcommand_hst` 时为 *必需*）。

::: noteclassic
对于更新操作，属性在更新操作期间被设置时，即视为“已设置”。
:::

未标记这些标签的属性为可选。

[comment]: # ({/8f68b338-a2c16a18})

[comment]: # ({f960f4be-f255da9d})
#### 参数行为

部分操作参数带有简短标签，用于说明该参数在操作中的行为。使用以下标签：

-   ***只读*** - 参数值会自动设置，用户无法定义或更改，即使在某些特定条件下也是如此（例如，继承对象或发现对象的 *只读* 参数）；
-   ***只写*** - 参数值可以设置，但之后无法访问；
-   ***支持*** - 不要求必须设置参数值，但在某些特定条件下允许设置（例如，当 Proxy 对象的 `operating_mode` 设置为“passive proxy”时，参数为 *支持*）；但请注意，无论条件如何，*支持* 参数仍可能被设置为其默认值；
-   ***必填*** - 必须设置参数值。

未标记标签的参数为可选。

[comment]: # ({/f960f4be-f255da9d})

[comment]: # ({cf59def4-5e99748d})
### 预留ID值“0”

保留的ID值“0”可用于过滤元素和删除引用对象。
- 例如，要从主机中删除 proxy 的代理，应将proxyid设置为0（“proxyid”：“0”）
- 或用于过滤由zabbix server监控的主机，proxyids设置为0（“proxyids”：“0”）。

[comment]: # ({/cf59def4-5e99748d})

[comment]: # ({da9957c2-b4e0f5ab})
### 通用 "get" 方法参数

以下参数受所有 `get` 方法支持：

|参数|[类型](#data-types)|说明|
|-|-|--------|
|countOutput|boolean|返回结果中的记录数，而不是实际数据。|
|editable|boolean|如果设置为 `true`，则仅返回用户具有写权限的对象。<br><br>默认值：`false`。|
|excludeSearch|boolean|返回与 `search` 参数中给定条件不匹配的结果。|
|filter|object|仅返回与给定过滤条件完全匹配的结果。<br><br>接受一个对象，其中键为属性名称（例如，`host.get` 中的主机对象属性、`item.get` 中的监控项对象属性等），值可以是单个值或用于匹配的值数组。<br><br>不支持 `text` [数据类型](#data-types) 的属性。<br><br>请注意，某些方法对此参数具有特定功能，详见相应的方法页面（例如，[host.get](/manual/api/reference/host/get) 中的 `filter` 参数还支持主机接口属性）。|
|limit|integer|限制返回的记录数。|
|output|query|要返回的对象属性。<br><br>请注意，对象 ID（即 `hostid`、`itemid` 等）始终包含在响应中，即使未在 `output` 参数中指定也是如此。<br><br>默认值：`extend`。|
|preservekeys|boolean|在结果数组中使用 ID 作为键。|
|search|object|返回与给定模式匹配的结果（不区分大小写）。<br><br>接受一个对象，其中键为属性名称（例如，`host.get` 中的主机对象属性、`item.get` 中的监控项对象属性等），值为要搜索的字符串。如果未提供其他选项，将执行 `LIKE "%…%"` 搜索。<br><br>仅支持 `string` 和 `text` [数据类型](#data-types) 的属性。<br><br>请注意，某些方法对此参数具有特定功能，详见相应的方法页面（例如，[host.get](/manual/api/reference/host/get) 中的 `search` 参数还支持主机接口属性）。|
|searchByAny|boolean|如果设置为 `true`，则返回匹配 `filter` 或 `search` 参数中任一条件的结果，而不是匹配全部条件。<br><br>默认值：`false`。|
|searchWildcardsEnabled|boolean|如果设置为 `true`，则允许在 `search` 参数中使用 "\*" 作为通配符。<br><br>默认值：`false`。|
|sortfield|string/array|按给定属性对结果进行排序。可用于排序的属性列表请参见具体 API get 方法的说明。在排序前不会展开宏。<br><br>如果未指定值，则返回的数据不排序。|
|sortorder|string/array|排序顺序。如果传递的是数组，则每个值将与 `sortfield` 参数中给定的相应属性对应。<br><br>可能的值：<br>`ASC` - *(默认)* 升序；<br>`DESC` - 降序。|
|startSearch|boolean|`search` 参数将比较字段的开头，即改为执行 `LIKE "…%"` 搜索。<br><br>如果 `searchWildcardsEnabled` 设置为 `true`，则忽略此参数。|

[comment]: # ({/da9957c2-b4e0f5ab})

[comment]: # ({1f52febe-4a0aeab6})
### 实体来源标志

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|已发现的低级发现规则原型。|

[comment]: # ({/1f52febe-4a0aeab6})

[comment]: # ({b41637d2-b41637d2})
### 示例

[comment]: # ({/b41637d2-b41637d2})

[comment]: # ({7f8a25ac-7a121fac})
#### 用户权限检查

用户是否有权写入以"MySQL"或"Linux"开头的主机？

[请求](/manual/api#执行请求)：

```json
{
    "jsonrpc": "2.0",
    "method": "host.get",
    "params": {
        "countOutput": true,
        "search": {
            "host": ["MySQL", "Linux"]
        },
        "editable": true,
        "startSearch": true,
        "searchByAny": true
    },
    "id": 1
}
```

响应:

```json
{
    "jsonrpc": "2.0",
    "result": "0",
    "id": 1
}
```

::: noteclassic
返回结果是 "0" 意思是没有主机具有 "读/写" 权限。
:::

[comment]: # ({/7f8a25ac-7a121fac})

[comment]: # ({b814e950-ea3cccd8})
#### 不匹配统计

计算名称不包含子字符串"ubuntu"的主机数量

[请求](/manual/api#执行请求):

```json
{
    "jsonrpc": "2.0",
    "method": "host.get",
    "params": {
        "countOutput": true,
        "search": {
            "host": "ubuntu"
        },
        "excludeSearch": true
    },
    "id": 1
}
```

响应:

```json
{
    "jsonrpc": "2.0",
    "result": "44",
    "id": 1
}
```

[comment]: # ({/b814e950-ea3cccd8})

[comment]: # ({a325f949-e911c08b})
#### 使用通配符搜索主机

查找名称包含单词"server"且主机接口的端口号为"10050"或"10071"的主机。按主机名降序排序，并限制只输出5个主机。

[请求](/manual/api#执行请求):

```json
{
    "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
}
```

响应:

```json
{
    "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
}
```

[comment]: # ({/a325f949-e911c08b})

[comment]: # ({8c8fa5f6-8ce6f554})
#### 使用"preservekeys"和通配符搜索主机

如果您在前面的请求中添加参数“preservekeys”，则结果将作为关联数组返回，其中键是对象的id。

[请求](/manual/api#执行请求):


```json
{
    "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
}
```

响应:

```json
{
    "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
}
```

[comment]: # ({/8c8fa5f6-8ce6f554})