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

更新监控 API

编辑

更新监控 API编辑

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

请求编辑

PUT <kibana 主机>:<端口>/api/synthetics/monitors/<配置 ID>

PUT <kibana 主机>:<端口>/s/<空间 ID>/api/synthetics/monitors/<配置 ID>

先决条件编辑

您必须对 可观察性 部分中 Synthetics 功能具有 all 权限 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")：命名空间字段应为小写且不包含空格。命名空间不得包含以下任何字符：*、\、/、?、"、<、>、|、空格、,、#、: 或 -
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：要与正文输出负匹配的正则表达式列表。如果单个表达式匹配，则返回匹配失败。支持最大 100 MiB 的 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 message”或“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
(必需，字符串)：内联脚本。
屏幕截图
(可选，字符串，默认值："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 »