查询受管代理列表

查询 `agent.read` 授权范围内的 `Agent`，使用 limit/offset 分页并返回数值型 `total`。默认包含 `active` 和 `revoking`；`revoked` 必须显式选择。关键词匹配显示名称、`Agent` ID、主机名和 IP 地址。`sort` 支持 `displayName`、`createdAt` 或 `lastHeartbeatAt`；`order` 支持 `asc` 或 `desc`。所有筛选（包括已认证升级是否可用）均在同一数据库读取视图中于计数和分页前应用。连续性信息使用带原始时间戳的缓存观测结果，不触发指标查询。

GET/api/v1/lifecycle/managed-agent/agents

操作 ID

ListManagedAgents

起始版本

1.3.0

执行模式

同步

认证信息

需要认证

认证信息

调用该 API 时需要在请求头中携带以下认证信息。

Authorizationstring必填

Bearer 令牌

X-Tenant-IDstring

X-Tenant-ID

请求参数

查询参数

platformUuid
String
平台UUID。
regionUuid
String
过滤关联区域UUID。
accessState
String
过滤当前访问状态。
primaryStatus
String
过滤主运行时状态。
capabilityId
String
过滤受支持能力标识符。

响应状态

200 OK

该 API 成功时返回以下响应结构。

items
List
条目列表。
示例： (nested array)
- agentId
  String
  代理ID。
  示例： value
- displayName
  String
  显示名称。用于界面展示。
  示例： value
- scope
  Object
  作用范围。
  platformUuid
  String
  平台UUID。
  示例： value
  regionUuid
  String
  资源。
  示例： value
- agentVersion
  String
  代理版本。
  示例： value
- accessState
  String
  资源。
  示例： value
- healthStatus
  String
  资源。
  示例： value
- runtimeState
  String
  资源。
  示例： value
- primaryStatus
  String
  资源。
  示例： value
- lastHeartbeatAt
  String
  最近一次心跳时间。
  示例： 2026-01-15T08:00:00Z
- lastStatusChangedAt
  String
  最近一次状态变更时间。
  示例： 2026-01-15T08:00:00Z
- rowVersion
  String
  资源。
  示例： 10
- capabilities
  List
  资源。
  示例： (nested array)
  capabilityId
  String
  资源。
  示例： value
  displayName
  String
  显示名称。用于界面展示。
  示例： value
  available
  Boolean
  资源。
  示例： true
  blockedBy
  List
  资源。
  示例： item1,item2
  bindingId
  String
  不存在能力已持久化绑定。
  示例： value
  desiredState
  String
  资源。
  示例： value
  effectiveState
  String
  资源。
  示例： value
  providerId
  String
  资源。
  示例： value
  providerRevision
  String
  资源。
  示例： value
  currentConfigRevision
  String
  资源。
  示例： 10
  effectiveConfigRevision
  String
  资源。
  示例： 10
  rowVersion
  String
  资源。
  示例： 10
  lastObservedAt
  String
  最近一次已观察时间。
  示例： 2026-01-15T08:00:00Z
  lastErrorReason
  String
  资源。
  示例： value
  hostMetricContinuitySummary
  Object
  资源。
  lastHostMetricAt
  String
  最近一次主机指标时间。
  示例： 2026-01-15T08:00:00Z
  collectionState
  String
  采集状态。
  示例： value
  deliveryState
  String
  投递状态。
  示例： value
  queueSize
  Long
  队列大小。
  示例： 0
  queueCapacity
  Long
  资源。
  示例： 0
  enqueueFailedMetricPoints
  Long
  资源。
  示例： 0
  sendFailedMetricPoints
  Long
  资源。
  示例： 0
  sentMetricPoints
  Long
  资源。
  示例： 0
  serviceInstanceId
  String
  资源。
  示例： value
  observedAt
  String
  已观察时间。
  示例： 2026-01-15T08:00:00Z
- latestTask
  Object
  资源。
  taskId
  String
  任务ID。
  示例： value
  type
  String
  类型。
  示例： value
  state
  String
  当前状态。
  示例： value
  bindingId
  String
  资源。
  示例： value
  createdAt
  String
  创建时间。
  示例： 2026-01-15T08:00:00Z
  startedAt
  String
  开始时间。
  示例： 2026-01-15T08:00:00Z
  completedAt
  String
  完成时间。
  示例： 2026-01-15T08:00:00Z
  errorReason
  String
  错误原因。
  示例： value
  errorMessage
  String
  错误返回消息。
  示例： value
  availableActions
  List
  可用动作。
  示例： item1,item2
  waitingReason
  String
  资源。
  示例： value
- updateAvailable
  Boolean
  更新可用。
  示例： true
- targetAgentVersion
  String
  资源。
  示例： value
- createdAt
  String
  创建时间。
  示例： 2026-01-15T08:00:00Z
- updatedAt
  String
  更新时间。
  示例： 2026-01-15T08:00:00Z
- hostName
  String
  资源。
  示例： value
- ipAddresses
  List
  资源。
  示例： item1,item2
- hostInfoObservedAt
  String
  此资源的主机信息观测时间。
  示例： 2026-01-15T08:00:00Z
- platformName
  String
  平台名称。
  示例： value
- regionName
  String
  资源。
  示例： value
- productType
  String
  产品类型。
  示例： value
- statusReasons
  List
  资源。
  示例： (nested array)
  source
  String
  来源信息。
  示例： value
  value
  String
  字段值。
  示例： value
  taskId
  String
  任务ID。
  示例： value
- recommendedActions
  List
  建议操作列表。
  示例： item1,item2
- agentRelease
  String
  该资源的 `Agent` 发布版本。
  示例： 10
- targetAgentRelease
  String
  该资源的目标 `Agent` 发布版本。
  示例： 10
total
Integer
返回结果总数。
示例： 10
limit
Integer
最大返回条目数。
示例： 10
offset
Integer
查询起始偏移量。
示例： 10

请求示例

curl -X GET '{host}/api/v1/lifecycle/managed-agent/agents?platformUuid={platformUuid}&regionUuid={regionUuid}&accessState={accessState}&primaryStatus={primaryStatus}&capabilityId={capabilityId}&updateAvailable=true&latestTaskState={latestTaskState}&keyword={keyword}&limit=0&offset=0&sort={sort}&order={order}&hasPlatform=true&hasRegion=true' \
  -H 'Authorization: Bearer {token}'

响应示例

{
  "items": [
    {
      "agentId": "value",
      "displayName": "value",
      "scope": {
        "platformUuid": "value",
        "regionUuid": "value"
      },
      "agentVersion": "value",
      "accessState": "value",
      "healthStatus": "value",
      "runtimeState": "value",
      "primaryStatus": "value"
    }
  ],
  "total": 10,
  "limit": 10,
  "offset": 10
}

变更历史

查看全部变更历史

变更时间变更内容概要操作

变更时间
2026-09-17
新增响应字段 agentRelease, targetAgentRelease
查看 API

资产

采集任务

基础设施综合

安装器

生命周期

OTA 升级计划

OTA 版本与策略

联邦与 SSO

变更管理

生命周期升级

告警规则

告警模板

告警通道与集成

告警事件

告警路由与策略

安全

ZMetis 审计

平台管理

平台联邦

平台健康

平台综合

ZMetis 任务

查询受管代理列表

认证信息

请求参数

查询参数

响应状态

变更历史