« 添加监控 API 删除监控 API »
Elastic 文档 ›Kibana 指南 [8.17] ›REST API ›Synthetics API

更新监控 API

编辑

更新监控 API

编辑

使用指定的属性更新新的监控。所需字段和默认字段可能因监控类型而异。

请求

编辑

PUT <kibana 主机>:<端口>/api/synthetics/monitors/<config_id>

PUT <kibana 主机>:<端口>/s/<space_id>/api/synthetics/monitors/<config_id>

先决条件

编辑

您必须拥有 全部 Synthetics 功能的权限，位于 可观测性 部分的 Kibana 功能权限 中。

路径参数

编辑
config_id
(必需，字符串) 要更新的监控的 ID。
space_id
(可选，字符串) 空间的标识符。如果 URL 中未提供 space_id，则使用默认空间。

请求体

编辑

请求体应包含要更新的监控的属性。所需字段和默认字段因监控类型而异

通用字段:

name
(字符串)：监控的名称。
schedule

(可选，数字)：监控的计划时间，以分钟为单位。支持的值为 1、3、5、10、15、30、60、120 和 240。

  • HTTP、TCP 和 ICMP 监控的默认值为 3 分钟。
  • 浏览器监控的默认值为 10 分钟。
locations

(Array<SyntheticsLocationsType>) 部署监控的位置。可以将监控部署在多个位置，以便您可以检测这些位置的可用性和响应时间的差异。

要列出可用的位置，您可以

  • 使用部署的 Kibana URL 运行 {locations-command}[elastic-synthetics locations] 命令。
  • 转到 Synthetics → 管理 并单击 创建监控。位置将列在“位置”中。
private_locations (Array<string>)

部署监控的私有位置。 这些私有位置是指您托管和管理的位置，而 locations 由 Elastic 托管。 您可以使用位置的名称指定私有位置。

要列出可用的私有位置，您可以

  • 使用部署的 Kibana URL 运行 {locations-command}[elastic-synthetics locations] 命令。
  • 转到 Synthetics → 设置 并单击 私有位置。私有位置将列在表中。

您可以提供 locations 或 private_locations，或两者都提供。 至少需要一个。

enabled
(可选，布尔值，默认值：true)：是否启用监控。
tags
(可选，字符串数组)：标签数组。
alert
(可选，对象，默认值：{ status: { enabled: true }, tls: { enabled: true } })：警报配置。
service.name
(可选，字符串)：APM 服务名称。
timeout
(可选，数字，默认值：16)：监控超时时间，以秒为单位，如果监控未在此时间内完成，则监控将失败。
namespace
(可选，字符串，默认值："default")：namespace 字段应为小写，且不包含空格。命名空间不得包含以下任何字符：*、\、/、?、"、<、>、|、空格、,、#、: 或 -
params
(可选，字符串)：监控参数。
retest_on_failure
(可选，布尔值，默认值：true)：在监控失败时启用或禁用重新测试。默认情况下，如果监控从“正常”变为“异常”，则会自动重新测试监控。 如果重新测试的结果也为“异常”，则会创建错误，如果配置了，则会发送警报。 然后，监控将根据定义的计划继续运行。使用 retest_on_failure 可以减少与瞬时问题相关的噪声。

HTTP 监控字段:

url
(必需，字符串)：要监控的 URL。
ssl
(可选，对象)：用于 HTTPS 端点的 TLS/SSL 连接设置。 如果未指定设置，则使用系统默认设置。有关完整的 SSL 选项，请参阅 https://elastic.ac.cn/guide/en/beats/heartbeat/current/configuration-ssl.html。
max_redirects
(可选，数字，默认值：0)：要遵循的最大重定向次数。
mode

(可选，字符串，默认值："any")：监控的模式。可以是“all”或“any”。 如果您正在使用 DNS 负载均衡器并且想要 ping 指定主机名的每个 IP 地址，则应使用 all。

  • any：监控仅 ping 主机名的一个 IP 地址。
  • all：监控 ping 主机名的所有可解析 IP。
ipv4
(可选，布尔值，默认值：true)：是否使用 ipv4 协议进行 ping。
ipv6
(可选，布尔值，默认值：true)：是否使用 ipv6 协议进行 ping。
username
(可选，字符串)：用于向服务器进行身份验证的用户名。凭据随请求传递。
password
(可选，字符串)：用于向服务器进行身份验证的密码。凭据随请求传递。
proxy_headers
(可选，对象)：在 CONNECT 请求期间发送到代理的其他标头。
proxy_url
(可选，字符串)：用于此监控的代理的 URL。
response
(可选，对象)：控制将 HTTP 响应正文内容索引到 http.response.body.contents 字段。
response.include_body

(可选，布尔值，默认值：true)：控制将 HTTP 响应正文内容索引到 http.response.body.contents 字段。

  • include_body ("on_error" | "never" | "always", 默认值：on_error) 将 response.include_body 设置为下面列出的选项之一。

    • on_error：如果在检查期间遇到错误，则包括正文。这是默认设置。
    • never：永远不包括正文。
    • always：始终包括正文。
  • include_body_max_bytes (可选，数字，默认值：1024) 设置 response.include_body_max_bytes 来控制存储的正文内容的最大大小。
check

(可选，对象)：检查请求设置。

  • request 要发送到远程主机的可选请求。在 check.request 下，指定以下选项

    • method ("HEAD" | "GET" | "POST" | "OPTIONS")：要使用的 HTTP 方法。
    • headers (可选，对象)：要发送的其他 HTTP 标头的字典。默认情况下，Synthetics 会设置 User-Agent 标头以标识自身。

    • body (可选，字符串)：可选的请求正文内容。

      Example: This POSTs an x-www-form-urlencoded string to the endpoint
      {
  "check": {
    "request": {
      "method": "POST",
      "headers": {
        "Content-Type": "application/x-www-form-urlencoded"
      },
      "body": "name=first&email=someemail%40someemailprovider.com"
    }
  }
}

  • response 预期响应。在 check.response 下，指定以下选项

    • status 预期状态代码列表。默认情况下，4xx 和 5xx 代码被视为异常。其他代码被视为正常。
    • headers (可选，对象)：预期 HTTP 标头的字典。如果未找到标头，则检查失败。
    • body.positive：用于匹配正文输出的正则表达式列表。只需要匹配一个表达式。示例：此监控检查响应正文中是否包含字符串 foo 或 Foo
    • body.negative：用于对正文输出进行负匹配的正则表达式列表。如果匹配单个表达式，则返回匹配失败。支持高达 100MiB 的 HTTP 响应正文。如果完全没有 bar 或 Bar，则此监控会成功检查匹配，如果响应正文中存在 bar 或 Bar，则会检查匹配失败

    • json：当正文被解析为 JSON 时，对正文执行的表达式列表。正文大小必须小于或等于 100 MiB。

      • description (字符串)：检查的描述。
      • expression (字符串)：以下配置显示如何在正文包含 JSON 时使用 [gval](https://github.com/PaesslerAG/gval) 表达式检查响应

TCP 监控字段:

host
(必需，字符串)：要监控的主机；它可以是 IP 地址或主机名。主机可以包含使用冒号的端口（例如，“example.com:9200”）。
ssl
(可选，对象)：用于 HTTPS 端点的 TLS/SSL 连接设置。 如果未指定设置，则使用系统默认设置。有关完整的 SSL 选项，请参阅 https://elastic.ac.cn/guide/en/beats/heartbeat/current/configuration-ssl.html。
check

要发送到远程主机的可选负载字符串和预期答案。如果未指定负载，则如果连接尝试成功，则假定端点可用。如果指定了 send 但没有指定 receive，则任何响应都被接受为 OK。如果指定了 receive 但没有指定 send，则不发送负载，但客户端希望在连接时接收“hello 消息”或“banner”形式的负载。

  • send (可选，字符串)：check.send: Hello World
  • receive (可选，字符串)：check.receive: Hello World
proxy_url
(可选，字符串)：连接到服务器时要使用的 SOCKS5 代理的 URL。该值必须是以 socks5:// 为方案的 URL。如果 SOCKS5 代理服务器需要客户端身份验证，则可以将用户名和密码嵌入到 URL 中。使用代理时，主机名会在代理服务器上而不是在客户端上解析。您可以通过设置 proxy_use_local_resolver 选项来更改此行为。
proxy_use_local_resolver
(可选，布尔值，默认值：false)：一个布尔值，用于确定主机名是在本地解析还是在代理服务器上解析。默认值为 false，这意味着名称解析发生在代理服务器上。

ICMP 监控字段:

host
(必需，字符串)：要 ping 的主机。
wait
(可选，数字，默认值：1)：等待时间，以秒为单位。

浏览器监控字段:

inline_script
(必需，字符串)：内联脚本。
screenshots
(可选，字符串，默认值："on")：屏幕截图选项，为 "on"、"off" 或 "only-on-failure"。
synthetics_args
(可选，数组)：Synthetics 代理 CLI 参数。
ignore_https_errors
(可选，布尔值，默认值：false)：是否忽略 HTTPS 错误。
playwright_options
(可选，对象)：Playwright 选项。

示例

编辑

以下是一些创建不同类型监控的示例

HTTP 监控：创建一个 HTTP 监控以检查网站的可用性。

PUT /api/synthetics/monitors/<monitor_id>
{
  "type": "http",
  "name": "Website Availability",
  "url": "https://example.com",
  "tags": ["website", "availability"],
  "locations": ["united_kingdom"]
}

TCP 监控：创建一个 TCP 监控以监控服务器的可用性。

PUT /api/synthetics/monitors/<monitor_id>
{
  "type": "tcp",
  "name": "Server Availability",
  "host": "example.com",
  "private_locations": ["my_private_location"]
}

ICMP 监控：创建一个 ICMP 监控以执行 ping 检查。

PUT /api/synthetics/monitors/<monitor_id>
{
  "type": "icmp",
  "name": "Ping Test",
  "host": "example.com",
  "locations": ["united_kingdom"]
}

浏览器监控：创建一个浏览器监控以检查网站。

PUT /api/synthetics/monitors/<monitor_id>
{
  "type": "browser",
  "name": "Example journey",
  "inline_script": "step('Go to https://google.com.co', () => page.goto('https://www.google.com'))",
  "locations": ["united_kingdom"]
}

部分更新

编辑

您还可以部分更新监控。 这只会更新请求体中指定的字段。 所有其他字段都保持不变。 指定的字段应与监控类型一致。 例如，您不能更新 HTTP 监控的 inline_scipt 字段。

PUT /api/synthetics/monitors/<monitor_id>
{
  "name": "New name"
}
« 添加监控 API 删除监控 API »