Skip to main content
POST
浏览拓扑主机

限制说明

使用说明

  • 与其余四个服务拓扑只读接口不同,本接口在服务拓扑存储不可用时会优雅降级:匹配逻辑仍基于清单数据运行,受影响的项通过 servicemap.error_code=status_unavailablepartial=true 披露,而不会导致整个请求失败。
  • cursor 是不透明值,请原样传入 next_cursor 返回的值,不要自行构造或解析。
  • 在找到 limit 个匹配前先达到 scan_limit 时,会设置 truncated=true 且仍会返回 next_cursor——这与扫描到账户主机末尾不是一回事。
  • coverage.scanned/matched/returned 仅描述本页的扫描情况,不代表账户内主机总量。

授权

app_key
string
query
必填

在 Flashduty 控制台 账户 → APP Key 中签发的 app_key。调用任何公开 API 时都必须携带。它等同于所属账户的身份凭证,请妥善保管。

请求体

application/json

浏览已启用服务拓扑能力主机的过滤与分页参数。

cursor
string

不透明的分页游标。请原样传入上一次响应中的 next_cursor;首页请省略此字段。

limit
integer
默认值:50

本页最多返回的匹配主机数。默认 50,范围 1~100。

必填范围: 1 <= x <= 100
scan_limit
integer
默认值:1000

填充本页时最多检查的候选主机数。默认 1000,范围 limit~2000。

必填范围: x <= 2000
statuses
enum<string>[]

筛选处于以下任一状态的主机,最多 20 个值。

Maximum array length: 20
可用选项:
active,
degraded,
stale,
initializing,
disabled,
unsupported,
no_data
agent_versions
string[]

筛选运行以下任一确切 Agent 版本的主机,最多 20 个值。

Maximum array length: 20
edge_clusters
string[]

筛选属于以下任一确切边缘集群名称的主机,最多 20 个值。

Maximum array length: 20
capture_modes
enum<string>[]

筛选使用以下任一采集模式的主机。unknown 匹配尚未上报采集模式的主机。

Maximum array length: 3
可用选项:
ebpf,
polling,
unknown

响应

成功

成功响应结构。2xx 响应中 request_id 标识本次调用(同时出现在 Flashcat-Request-Id 响应头中),data 为接口业务 payload。失败响应使用不同结构,参见 ErrorResponse

request_id
string
必填

本次请求的唯一 ID,也会在 Flashcat-Request-Id 响应头中返回。反馈问题时请一并附上。

示例:

"01HK8XQE3Z7JM2NTFQ5YJ8P9R4"

data
object
必填

匹配主机群浏览过滤条件的一页主机结果。