[comment]: # ({062bc405-eb22f00a})
# 9 HTTP agent
[comment]: # ({/062bc405-eb22f00a})
[comment]: # ({d15d6778-a236c83a})
#### 概述
此 监控项 类型允许使用 HTTP/HTTPS 协议进行数据轮询。也可以使用 [Zabbix sender](/manual/concepts/sender) 工具或 Zabbix sender [protocol](/manual/appendix/protocols/zabbix_sender)（用于向 Zabbix server 或 proxy 发送数据），或使用 [`history.push`](/manual/api/reference/history/push) API 方法（用于向 Zabbix server 发送数据）进行数据捕获。
HTTP 监控项 检查由 Zabbix server 执行。然而，当由 Zabbix proxy 监控 主机 时，HTTP 监控项 检查则由 proxy 执行。
HTTP 监控项 检查不需要在被监控的 一个主机 上运行任何 agent。
HTTP agent 同时支持 HTTP 和 HTTPS。Zabbix 可选择性地跟随重定向（参见下面的“跟随重定向”选项）。最大重定向次数硬编码为 10（使用 cURL 选项 CURLOPT\_MAXREDIRS）。
::: noteimportant
Zabbix server/proxy 必须首先配置 cURL（libcurl）支持。
:::
HTTP 检查是异步执行的 —— 不需要等待一个请求的响应完成后再启动其他检查。DNS 解析也是异步的。
异步检查的最大并发数为 1000（由 [maxconcurrentchecksperpoller](/manual/appendix/config/zabbix_server#maxconcurrentchecksperpoller) 定义）。
异步 HTTP agent 轮询器的数量由 [starthttpagentpollers](/manual/appendix/config/zabbix_server#starthttpagentpollers) 参数定义。
自 Zabbix 7 起，HTTP agent 检查中引入了持久连接的 cURL 特性。0
[comment]: # ({/d15d6778-a236c83a})
[comment]: # ({df1df5d7-11697b04})
#### 配置
要配置一个 HTTP 监控项：
1. 转到 *数据采集* > *主机*。
2. 点击该主机所在行中的 *监控项*。
3. 点击 *创建监控项*。
4. 在表单中输入该监控项的参数。
{width="600"}
所有必填输入字段都用红色星号标记。
HTTP 监控项需要填写的特定字段如下：
|Parameter|Description|
|--|--------|
|*Type*|在此选择 **HTTP agent**。|
|*Key*|输入唯一的监控项键值。|
|*URL*|要连接并检索数据的 URL。例如：
https://www.example.com
http://www.example.com/download
域名可以使用 Unicode 字符指定。在执行 HTTP 检查时，它们会自动转换为 ASCII 的 punycode 格式。
可使用 *Parse* 按钮将 URL 中可选的查询字段（如 ?name=Admin&password=mypassword）分离出来，并将属性和值移动到 *Query fields* 中，以便自动进行 URL 编码。
最多 2048 个字符。
支持的宏：{HOST.IP}、{HOST.CONN}、{HOST.DNS}、{HOST.HOST}、{HOST.NAME}、{ITEM.ID}、{ITEM.KEY}、{ITEM.KEY.ORIG}、用户宏、低级别发现宏。
这会设置 cURL 选项 [CURLOPT\_URL](https://curl.haxx.se/libcurl/c/CURLOPT_URL.html)。|
|*Query fields*|URL 的变量（见上文）。
以属性和值对的形式指定。
值会自动进行 URL 编码。来自宏的值会先解析，然后自动进行 URL 编码。
支持的宏：{HOST.IP}、{HOST.CONN}、{HOST.DNS}、{HOST.HOST}、{HOST.NAME}、{ITEM.ID}、{ITEM.KEY}、{ITEM.KEY.ORIG}、用户宏、低级别发现宏。
这会设置 cURL 选项 [CURLOPT\_URL](https://curl.haxx.se/libcurl/c/CURLOPT_URL.html)。|
|*Request type*|选择请求方法类型：*GET*、*POST*、*PUT* 或 *HEAD*|
|*Request body type*|选择请求正文类型：
**Raw data** - 自定义 HTTP 请求正文，宏会被替换，但不会执行编码
**JSON data** - JSON 格式的 HTTP 请求正文。宏可用作字符串、数字、true 和 false；作为字符串使用的宏必须用双引号括起来。来自宏的值会先解析，然后自动转义。如果未在标头中指定 "Content-Type"，则默认使用 "Content-Type: application/json"
**XML data** - XML 格式的 HTTP 请求正文。宏可用作文本节点、属性或 CDATA 节。来自宏的值会先解析，然后在文本节点和属性中自动转义。如果未在标头中指定 "Content-Type"，则默认使用 "Content-Type: application/xml"
*注意*，选择 *XML data* 需要 libxml2。|
|*Request body*|输入请求正文。
支持的宏：{HOST.IP}、{HOST.CONN}、{HOST.DNS}、{HOST.HOST}、{HOST.NAME}、{ITEM.ID}、{ITEM.KEY}、{ITEM.KEY.ORIG}、用户宏、低级别发现宏。|
|*Headers*|请求时发送的自定义 HTTP 标头。
以属性和值对的形式指定。
支持的宏：{HOST.IP}、{HOST.CONN}、{HOST.DNS}、{HOST.HOST}、{HOST.NAME}、{ITEM.ID}、{ITEM.KEY}、{ITEM.KEY.ORIG}、用户宏、低级别发现宏。
这会设置 cURL 选项 [CURLOPT\_HTTPHEADER](https://curl.haxx.se/libcurl/c/CURLOPT_HTTPHEADER.html)。|
|*Required status codes*|预期的 HTTP 状态码列表。如果 Zabbix 获取到不在列表中的状态码，该监控项将变为不受支持。如果为空，则不执行检查。
例如：200,201,210-299
列表中支持的宏：用户宏、低级别发现宏。
这会使用 cURL 选项 [CURLINFO\_RESPONSE\_CODE](https://curl.haxx.se/libcurl/c/CURLINFO_RESPONSE_CODE.html)。|
|*Follow redirects*|勾选此复选框以跟随 HTTP 重定向。
这会设置 cURL 选项 [CURLOPT\_FOLLOWLOCATION](https://curl.haxx.se/libcurl/c/CURLOPT_FOLLOWLOCATION.html)。|
|*Retrieve mode*|选择必须检索的响应部分：
**Body** - 仅正文
**Headers** - 仅标头
**Body and headers** - 正文和标头|
|*Convert to JSON*|如果 *Retrieve mode* 未设置为 *Body*，则标头会作为属性和值对保存在 "header" 键下。
如果遇到 'Content-Type: application/json'，则正文会保存为对象，否则会存储为字符串，例如：
|
|*HTTP proxy*|可以使用格式 `[protocol://][username[:password]@]proxy.example.com[:port]` 指定要使用的 HTTP proxy。
可选的 `protocol://` 前缀可用于指定其他 proxy 协议（例如 https、socks4、socks5；请参见[文档](https://curl.haxx.se/libcurl/c/CURLOPT_PROXY.html)；协议前缀支持是在 cURL 7.21.7 中添加的）。如果未指定协议，则该 proxy 将被视为 HTTP proxy。如果指定了错误的协议，连接将失败，该监控项将变为不受支持。
默认使用 1080 端口。
如果指定了该项，proxy 将覆盖与 proxy 相关的环境变量，如 http\_proxy、HTTPS\_PROXY。如果未指定，则 proxy 不会覆盖与 proxy 相关的环境变量。输入的值会按原样传递，不会进行有效性检查。
*注意*，HTTP proxy 仅支持简单认证。
支持的宏：{HOST.IP}、{HOST.CONN}、{HOST.DNS}、{HOST.HOST}、{HOST.NAME}、{ITEM.ID}、{ITEM.KEY}、{ITEM.KEY.ORIG}、用户宏、低级别发现宏。
这会设置 cURL 选项 [CURLOPT\_PROXY](https://curl.haxx.se/libcurl/c/CURLOPT_PROXY.html)。|
|*HTTP authentication*|选择认证选项：
**None** - 不使用认证；
**Basic** - 使用基本认证；
**NTLM** - 使用 NTLM ([Windows NT LAN Manager](http://en.wikipedia.org/wiki/NTLM)) 认证；
**Kerberos** - 使用 Kerberos 认证（另请参见：[使用 Zabbix 配置 Kerberos](/manual/appendix/items/kerberos)）；
**Digest** - 使用摘要认证。
这会设置 cURL 选项 [CURLOPT\_HTTPAUTH](https://curl.haxx.se/libcurl/c/CURLOPT_HTTPAUTH.html)。|
|*User name*|输入用户名（最多 255 个字符）。
当 *HTTP authentication* 设置为 Basic、NTLM、Kerberos 或 Digest 时，此字段可用。支持用户宏和低级别发现宏。 |
|*Password*|输入用户密码（最多 255 个字符）。
当 *HTTP authentication* 设置为 Basic、NTLM、Kerberos 或 Digest 时，此字段可用。支持用户宏和低级别发现宏。 |
|*SSL verify peer*|勾选此复选框以验证 web 服务器的 SSL 证书。服务器证书将自动从系统范围的证书颁发机构（CA）位置获取。可以使用 Zabbix 服务器或 proxy 配置参数 SSLCALocation 覆盖 CA 文件位置。
这会设置 cURL 选项 [CURLOPT\_SSL\_VERIFYPEER](http://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYPEER.html)。|
|*SSL verify host*|勾选此复选框以验证 web 服务器证书的 Common Name 字段或 Subject Alternate Name 字段是否匹配。
这会设置 cURL 选项 [CURLOPT\_SSL\_VERIFYHOST](http://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYHOST.html)。|
|*SSL certificate file*|用于客户端认证的 SSL 证书文件名。证书文件必须为 PEM^1^ 格式。如果证书文件中也包含私钥，请将 SSL key file 字段留空。如果密钥已加密，请在 SSL key password 字段中指定密码。包含此文件的目录由 Zabbix 服务器或 proxy 配置参数 SSLCertLocation 指定。
支持的宏：{HOST.IP}、{HOST.CONN}、{HOST.DNS}、{HOST.HOST}、{HOST.NAME}、{ITEM.ID}、{ITEM.KEY}、{ITEM.KEY.ORIG}、用户宏、低级别发现宏。
这会设置 cURL 选项 [CURLOPT\_SSLCERT](http://curl.haxx.se/libcurl/c/CURLOPT_SSLCERT.html)。|
|*SSL key file*|用于客户端认证的 SSL 私钥文件名。私钥文件必须为 PEM^1^ 格式。包含此文件的目录由 Zabbix 服务器或 proxy 配置参数 SSLKeyLocation 指定。
支持的宏：{HOST.IP}、{HOST.CONN}、{HOST.DNS}、{HOST.HOST}、{HOST.NAME}、{ITEM.ID}、{ITEM.KEY}、{ITEM.KEY.ORIG}、用户宏、低级别发现宏。
这会设置 cURL 选项 [CURLOPT\_SSLKEY](http://curl.haxx.se/libcurl/c/CURLOPT_SSLKEY.html)。|
|*SSL key password*|SSL 私钥文件密码。
支持的宏：用户宏、低级别发现宏。
这会设置 cURL 选项 [CURLOPT\_KEYPASSWD](http://curl.haxx.se/libcurl/c/CURLOPT_KEYPASSWD.html)。|
|*Timeout*|Zabbix 处理该 URL 的时间不会超过设置的时长（1-600 秒）。实际上，此参数定义了连接到该 URL 的最大时间以及执行 HTTP 请求的最大时间。因此，Zabbix 对一次检查的耗时不会超过 2 x *Timeout* 秒。
这会设置 cURL 选项 [CURLOPT\_TIMEOUT](https://curl.haxx.se/libcurl/c/CURLOPT_TIMEOUT.html)。
有关 *Timeout* 参数的更多信息，请参见[通用监控项属性](/manual/config/items/item#configuration)。|
|*Enable trapping*|勾选此复选框后，该监控项还将作为 trapper 监控项工作，并接受通过 [Zabbix sender](/manual/concepts/sender) 工具或 Zabbix sender [协议](/manual/appendix/protocols/zabbix_sender)发送到 Zabbix 服务器或 proxy 的数据，或者接受通过 [`history.push`](/manual/api/reference/history/push) API 方法发送到 Zabbix 服务器的数据。有关发送数据的更多信息，请参见：[Trapper 监控项](/manual/config/items/itemtypes/trapper#sending-data)。|
|*Allowed hosts*|仅在勾选 *Enable trapping* 复选框时可见。
以逗号分隔的 IP 地址列表，可选使用 CIDR 表示法，或 DNS 名称。
如果指定，则仅接受来自此处列出的主机的传入连接。
如果启用了 IPv6 支持，则 '127.0.0.1'、'::127.0.0.1'、'::ffff:127.0.0.1' 会被视为相同，且 '::/0' 将允许任何 IPv4 或 IPv6 地址。
'0.0.0.0/0' 可用于允许任何 IPv4 地址。
请注意，“IPv4-compatible IPv6 addresses”（0000::/96 前缀）受支持，但已被 [RFC4291](https://tools.ietf.org/html/rfc4291#section-2.5.5) 弃用。
示例：127.0.0.1, 192.168.1.0/24, 192.168.3.1-255, 192.168.1-10.1-255, ::1,2001:db8::/32, mysqlserver1, zabbix.example.com, {HOST.HOST}
此字段允许空格和 [用户宏](/manual/config/macros/user_macros)。
此字段允许使用主机宏：{HOST.HOST}、{HOST.NAME}、{HOST.IP}、{HOST.DNS}、{HOST.CONN}。|
::: notetip
如果 *HTTP proxy* 字段留空，使用 HTTP proxy 的另一种方式是设置与 proxy 相关的环境变量。
对于 HTTP - 为 Zabbix 服务器用户设置 `http_proxy` 环境变量。例如：
`http_proxy=http://proxy_ip:proxy_port`。
对于 HTTPS - 设置 `HTTPS_PROXY` 环境变量。例如：
`HTTPS_PROXY=http://proxy_ip:proxy_port`。更多详情可通过运行 shell 命令查看：*\# man curl*。
:::
::: noteimportant
\[1\] Zabbix 仅支持 PEM 格式的证书和私钥文件。如果您的证书和私钥数据位于 PKCS \#12 格式文件中（通常扩展名为 \*.p12 或 \*.pfx），可以使用以下命令将其生成 PEM 文件：
openssl pkcs12 -in ssl-cert.p12 -clcerts -nokeys -out ssl-cert.pem
openssl pkcs12 -in ssl-cert.p12 -nocerts -nodes -out ssl-cert.key
:::
[comment]: # ({/df1df5d7-11697b04})
[comment]: # ({4c860844-4c860844})
#### 示例
[comment]: # ({/4c860844-4c860844})
[comment]: # ({158d2fe1-67d717da})
##### 示例1
发送简单的 GET 请求以从诸如 Elasticsearch 的服务中检索数据：
- 创建一个 GET 监控项，其 URL 为：`localhost:9200/?pretty`
- 注意响应内容：
```json
{
"name" : "YQ2VAY-",
"cluster_name" : "elasticsearch",
"cluster_uuid" : "kH4CYqh5QfqgeTsjh2F9zg",
"version" : {
"number" : "6.1.3",
"build_hash" : "af51318",
"build_date" : "2018-01-26T18:22:55.523Z",
"build_snapshot" : false,
"lucene_version" : "7.1.0",
"minimum_wire_compatibility_version" : "5.6.0",
"minimum_index_compatibility_version" : "5.0.0"
},
"tagline" : "You know, for search"
}
```
- 现在使用 JSONPath 预处理步骤提取 version 数值：
`$.version.number`
[comment]: # ({/158d2fe1-67d717da})
[comment]: # ({fa9f3600-712fb81c})
##### 示例2
向类似 Elasticsearch 的服务发送简单的 POST 请求以检索数据：
- 创建一个带有如下 URL 的 POST 监控项：
`http://localhost:9200/str/values/_search?scroll=10s`
- 配置如下 POST 请求体以获取处理器负载（每个核心的 1 分钟平均值）：
```json
{
"query": {
"bool": {
"must": [{
"match": {
"itemid": 28275
}
}],
"filter": [{
"range": {
"clock": {
"gt": 1517565836,
"lte": 1517566137
}
}
}]
}
}
}
```
- 接收到的数据如下：
```json
{
"_scroll_id": "DnF1ZXJ5VGhlbkZldGNoBQAAAAAAAAAkFllRMlZBWS1UU1pxTmdEeGVwQjRBTFEAAAAAAAAAJRZZUTJWQVktVFNacU5nRHhlcEI0QUxRAAAAAAAAACYWWVEyVkFZLVRTWnFOZ0R4ZXBCNEFMUQAAAAAAAAAnFllRMlZBWS1UU1pxTmdEeGVwQjRBTFEAAAAAAAAAKBZZUTJWQVktVFNacU5nRHhlcEI0QUxR",
"took": 18,
"timed_out": false,
"_shards": {
"total": 5,
"successful": 5,
"skipped": 0,
"failed": 0
},
"hits": {
"total": 1,
"max_score": 1.0,
"hits": [{
"_index": "dbl",
"_type": "values",
"_id": "dqX9VWEBV6sEKSMyk6sw",
"_score": 1.0,
"_source": {
"itemid": 28275,
"value": "0.138750",
"clock": 1517566136,
"ns": 25388713,
"ttl": 604800
}
}]
}
}
```
- 现在使用一个 JSONPath 预处理步骤来 get 监控项 值：
`$.hits.hits[0]._source.value`
[comment]: # ({/fa9f3600-712fb81c})
[comment]: # ({9538274c-f480040f})
##### 示例3
检查 Zabbix API 是否存活，使用
[apiinfo.version](/manual/api/reference/apiinfo/version)。
- 监控项 配置：
{width="600"}
请注意使用带有 JSON 数据的 POST 方法，设置请求头并要求仅返回头信息：
- 使用正则表达式对 监控项 值进行预处理以获取 HTTP 状态码 get：
- 在 *最新数据* 中检查结果：
{width="600"}
[comment]: # ({/9538274c-f480040f})
[comment]: # ({ec243a91-466eee2b})
##### 示例4
通过连接到Openweathermap公共服务检索天气信息。
- 配置一个主监控项以在单个JSON中进行批量数据收集：
{width="600"}
请注意query字段中宏的使用。有关如何填写它们，请参阅[Openweathermap
API](https://openweathermap.org/current)。
HTTP agent响应中返回的示例JSON：
```json
{
"body": {
"coord": {
"lon": 40.01,
"lat": 56.11
},
"weather": [{
"id": 801,
"main": "Clouds",
"description": "few clouds",
"icon": "02n"
}],
"base": "stations",
"main": {
"temp": 15.14,
"pressure": 1012.6,
"humidity": 66,
"temp_min": 15.14,
"temp_max": 15.14,
"sea_level": 1030.91,
"grnd_level": 1012.6
},
"wind": {
"speed": 1.86,
"deg": 246.001
},
"clouds": {
"all": 20
},
"dt": 1526509427,
"sys": {
"message": 0.0035,
"country": "RU",
"sunrise": 1526432608,
"sunset": 1526491828
},
"id": 487837,
"name": "Stavrovo",
"cod": 200
}
}
```
下一步是配置从JSON中提取数据的依赖项监控项。
- 配置一个湿度的示例依赖项监控项：
其他天气指标如'温度'以相同方式添加。
- 使用JSONPath的示例依赖项监控项值预处理：
- 在*最新数据*中检查天气数据的结果：
{width="600"}
[comment]: # ({/ec243a91-466eee2b})
[comment]: # ({530cea3c-44596b14})
##### 示例5
连接到 nginx 状态页面并批量获取其指标。
- 按照 [official
guide](https://nginx.ru/en/docs/http/ngx_http_stub_status_module.html) 中的说明配置 nginx。
- 配置一个主 监控项 用于批量数据收集：
{width="600"}
示例 nginx stub 状态输出：
Active connections: 1 Active connections:
server accepts handled requests
52 52 52
Reading: 0 Writing: 1 Waiting: 0
下一步是配置提取数据的依赖 监控项。
- 配置一个示例依赖 监控项 以获取每秒请求数：
- 使用正则表达式 `server accepts handled requests\s+([0-9]+) ([0-9]+) ([0-9]+)` 对依赖 监控项 的值进行示例预处理：
{width="600"}
- 在 *Latest data* 中检查 stub 模块的完整结果：
{width="600"}
[comment]: # ({/530cea3c-44596b14})