创建操作预检

使用 `Agent` 已保存的作用域创建有效期为五分钟的确认。`capabilities` 操作支持单次 `host_metrics` 启用、配置更新或禁用，需要 `agent.config.write` 权限。禁用时 `drainMode` 支持 `wait` 或 `discard`。被阻止的操作不会创建确认。取消平台访问需要 `agent.access.revoke` 权限，不会卸载 `Agent`。

POST/api/v1/lifecycle/managed-agent/agents/{id}/operation-prechecks

操作 ID

CreateOperationPrecheck

起始版本

1.3.0

执行模式

同步

认证信息

需要认证

认证信息

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

Authorizationstring必填

Bearer 令牌

X-Tenant-IDstring

X-Tenant-ID

请求参数

application/json

路径参数

id
String必填
资源ID。

请求体字段

requestId
String
资源。
示例： value
operation
Object
操作。
- type
  String
  需要预检查的操作：`revoke_access`、`restart_runtime`、`upgrade` 或 `capabilities`。`capabilities` 用于请求变更期望状态，不是任务类型。
  示例： value
- reason
  String
  原因说明。
  示例： value
- changes
  List
  变更。
  示例： (nested array)
  capabilityId
  String
  资源。
  示例： value
  desiredState
  String
  资源。
  示例： value
  configurationRevision
  String
  配置修订版本。
  示例： value
  drainMode
  String
  排空模式。
  示例： value
- targetVersion
  String
  目标版本。
  示例： value

响应状态

200 OK

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

precheckId
String
资源。
示例： value
result
String
执行结果。
示例： value
agentRowVersion
String
资源。
示例： 10
expiresAt
String
过期时间。
示例： 2026-01-15T08:00:00Z
plannedImpact
Object
资源。
- platformAccessRevoked
  Boolean
  资源。
  示例： true
- localBacklogMayNotUpload
  Boolean
  该资源的本地积压数据可能无法上传。
  示例： true
- localAgentUninstalled
  Boolean
  资源。
  示例： true
- metricsContinuity
  String
  `buffered`、`unprotected` 或 `unknown`；重启时报告 `unknown`。撤销访问时为空。
  示例： value
- resumeCollection
  Boolean
  资源。
  示例： true
- drainMode
  String
  仅用于禁用：`wait` 或 `discard`。
  示例： value
- drainWaitSeconds
  Integer
  `wait` 时固定为 1800；`discard` 时不提供。
  示例： 10
- cancelledEnableTaskId
  String
  资源。
  示例： value
- queueFacts
  Object
  资源。
  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
- collectorRestart
  Boolean
  收集器重启。
  示例： true
- agentRestart
  Boolean
  代理重启。
  示例： true
- previousAgentVersion
  String
  资源。
  示例： value
- targetAgentVersion
  String
  资源。
  示例： value
- previousAgentRelease
  String
  该资源此前的 `Agent` 发布版本。
  示例： 10
- targetAgentRelease
  String
  该资源的目标 `Agent` 发布版本。
  示例： 10
confirmationMessage
String
资源。
示例： value
agentDisplayName
String
资源。
示例： value
blockedBy
List
已阻塞人。
示例： item1,item2
capabilityImpacts
List
严格按照请求的能力变更项排序。单个变更时，还包含其预期影响；多个变更时该字段缺省。
示例： (nested array)
- capabilityId
  String
  资源。
  示例： value
- impact
  Object
  影响类型。
  platformAccessRevoked
  Boolean
  资源。
  示例： true
  localBacklogMayNotUpload
  Boolean
  该资源的本地积压数据可能无法上传。
  示例： true
  localAgentUninstalled
  Boolean
  资源。
  示例： true
  metricsContinuity
  String
  `buffered`、`unprotected` 或 `unknown`；重启时报告 `unknown`。撤销访问时为空。
  示例： value
  resumeCollection
  Boolean
  资源。
  示例： true
  drainMode
  String
  仅用于禁用：`wait` 或 `discard`。
  示例： value
  drainWaitSeconds
  Integer
  `wait` 时固定为 1800；`discard` 时不提供。
  示例： 10
  cancelledEnableTaskId
  String
  资源。
  示例： value
  queueFacts
  Object
  资源。
  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
  collectorRestart
  Boolean
  收集器重启。
  示例： true
  agentRestart
  Boolean
  代理重启。
  示例： true
  previousAgentVersion
  String
  资源。
  示例： value
  targetAgentVersion
  String
  资源。
  示例： value
  previousAgentRelease
  String
  该资源此前的 `Agent` 发布版本。
  示例： 10
  targetAgentRelease
  String
  该资源的目标 `Agent` 发布版本。
  示例： 10

请求示例

curl -X POST '{host}/api/v1/lifecycle/managed-agent/agents/{id}/operation-prechecks' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
  "requestId": "value",
  "operation": {
    "type": "value",
    "reason": "value",
    "changes": [
      {
        "capabilityId": "value",
        "desiredState": "value",
        "configurationRevision": "value",
        "drainMode": "value"
      }
    ],
    "targetVersion": "value"
  }
}'

响应示例

{
  "precheckId": "value",
  "result": "value",
  "agentRowVersion": "10",
  "expiresAt": "2026-01-15T08:00:00Z",
  "plannedImpact": {
    "platformAccessRevoked": true,
    "localBacklogMayNotUpload": true,
    "localAgentUninstalled": true,
    "metricsContinuity": "value",
    "resumeCollection": true,
    "drainMode": "value",
    "drainWaitSeconds": 10,
    "cancelledEnableTaskId": "value"
  },
  "confirmationMessage": "value",
  "agentDisplayName": "value",
  "blockedBy": [
    "value"
  ]
}

变更历史

查看全部变更历史

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

变更时间
2026-09-22
新增响应字段 capabilityId, capabilityImpacts, impact
查看 API
变更时间
2026-09-17
新增响应字段 previousAgentRelease, targetAgentRelease
查看 API

资产

采集任务

基础设施综合

安装器

生命周期

OTA 升级计划

OTA 版本与策略

联邦与 SSO

变更管理

生命周期升级

告警规则

告警模板

告警通道与集成

告警事件

告警路由与策略

安全

ZMetis 审计

平台管理

平台联邦

平台健康

平台综合

ZMetis 任务

创建操作预检

认证信息

请求参数

路径参数

请求体字段

响应状态

变更历史