AI 助理
文档备案控制台
官方文档
输入文档关键字查找
首页

使用EventBridge和云监控订阅云助手事件

更新时间：
复制为 MD 格式
产品详情
我的收藏

通过订阅云助手事件，可以构建自动化的运维响应流程。例如，在自动化任务（如安装软件、执行巡检脚本）失败时立即接收告警，从而替代高成本、高延迟的手动轮询检查。

操作步骤

操作步骤以订阅云助手任务状态事件为例，更多信息，请参见云助手事件说明。

使用EventBridge订阅云助手事件

操作前，请确认已开通事件总线EventBridge并授权。

  1. 登录事件总线EventBridge控制台，在左侧导航栏，单击事件总线。

  2. 在顶部菜单栏，选择地域。

  3. 在事件总线页面，单击default。

  4. 在事件总线页面，单击左侧导航栏的事件规则，然后单击创建规则。

  5. 在配置基本信息页签，在名称文本框输入规则名称，在描述文本框输入规则的描述，然后单击下一步。

  6. 在配置事件模式页签，完成以下配置，然后单击下一步。

    1. 在事件源下拉列表中选择acs.ecs。

    2. 在事件类型下拉列表中选择需要订阅的云助手事件类型。

      云助手任务状态事件：ecs:CloudAssistant:TaskCompleted。

    3. 在事件模式调试中，查看订阅的事件类型的示例。

      {
    "id": "45ef4dewdwe1-7c35-447a-bd93-fab****",
    "source": "acs.ecs",
    "specversion": "1.0",
    "subject": "acs.ecs:cn-hangzhou:123456789098****:215672",
    "time": "2020-11-19T21:04:41+08:00",
    "type": "ecs:CloudAssistant:TaskCompleted",
    "aliyunaccountid": "123456789098****",
    "aliyunpublishtime": "2020-11-19T21:04:42Z",
    "aliyuneventbusname": "default",
    "aliyunregionid": "cn-hangzhou",
    "aliyunpublishaddr": "172.25.XX.XX",
    "data": {
        "commandId": "c-hz045**********",
        "commandName": "hello-linux.sh",
        "exitCode": "0",
        "finishTime": "2023-12-14T07:39:48Z",
        "instanceId": "i-bp114***************",
        "invocationStatus": "Success",
        "invokeId": "t-hz045**********",
        "ownerId": "158*************",
        "playerUid": "256***************",
        "repeatMode": "Once",
        "repeats": "1",
        "startTime": "2023-12-14T07:39:48Z",
        "errorCode": "0",
        "errorDesc": ""
    }
}

    4. 在示例下方，单击测试模拟事件触发。如果显示匹配通过，事件可正常被触发，表示事件可正常触发。

  7. 配置事件目标，选择不同的服务类型，设置推送场景。

    更多推送场景说明，请参见设置推送场景。

使用云监控订阅云助手事件

  1. 登录云监控控制台。

  2. 在左侧导航栏，选择事件中心 > 事件订阅。

  3. 在订阅策略页签，单击创建订阅策略。

  4. 在创建订阅策略页面，设置订阅云助手事件的相关参数。

    本示例仅展示云助手事件的相关参数，更多参数说明，请参见订阅策略参数说明。

    • 订阅类型：选择系统事件。

    • 订阅范围：

      • 产品：选择云服务器ECS。

      • 事件类型：选择通知。

      • 事件名称：选择云助手任务状态事件。

  5. 设置完成后，单击提交。

    当相关事件触发时，将会收到相关事件的通知。您也可以通过调用DescribeSystemEventAttribute查询系统事件详情。

云助手事件说明

云助手任务状态事件

事件描述

命令或脚本运行需要一定时间，云助手任务状态事件用于加强对任务完成情况的感知，可以利用该事件达到以下目的：

  • 在任务失败或任务处于完成状态时，可获得通知，以便设置报警、处理任务等。

  • 使用轮询会占用用户的API调用额度，通过事件订阅的方式可以避免该问题。

  • 轮询的过程较长，容易被应用发布所打断。使用事件规避状态中断，可以降低用户的复杂度。

事件触发条件&限制

事件触发条件：用户使用RunCommand/InvokeCommand触发任务执行，云助手内部监听任务完成状态，处于完成状态的任务则发出该事件。

事件使用限制：

  • 仅在云助手在实例上的任务执行状态（InvocationStatus）变为以下状态时，才会触发发送事件。

    • Aborted：任务下发失败

    • Success：任务执行成功

    • Failed：任务执行失败

    • Invalid：任务内容非法

    • Timeout：任务执行超时

    • Cancelled：任务执行取消

    • Terminated：任务执行被终止

  • 在OpenAPI（DescribeInvocations/DescribeInvocationResults）中，事件查询的返回数据格式为array<object>。在本事件中，上报的是一个任务在单个实例上的执行状态，而不是多个任务。

事件字段说明

字段

说明

示例值

instanceId

实例ID。

i-bp114***************

invokeId

命令执行ID。

t-hz045**********

commandId

命令ID。

c-hz045**********

commandName

命令名称。

ACS-ECS-ResetPassword-for-linux.sh

ownerUid

执行命令的实例归属账号。

158*************

playerUid

角色扮演者账号ID。

256***************

repeatMode

命令执行的方式。如果同时设置了InstanceId参数，则不生效。取值范围：

  • Once：立即执行命令。

  • Period：定时执行命令。

  • NextRebootOnly：当实例下一次启动时，自动执行命令。

  • EveryReboot：实例每一次启动都将自动执行命令。

Once

repeats

命令在该实例上执行的次数。

  • 若执行方式为立即执行，则值为0或1。

    • 0：命令下发失败，命令脚本未启动执行。

    • 1：命令下发成功，命令第一次在此实例上执行。

  • 若执行方式为定时执行，则值为执行过多少次。

0

invocationStatus

命令执行的状态。

  • Invalid：指定命令类型或参数错误。

  • Aborted：向实例发送命令失败。实例必须在运行中，且命令可以在1分钟内发送完成。

  • Success：

    • 单次执行的命令：命令执行完成，且退出码为0。

    • 定时执行的命令：上一次执行成功且退出码为0，且指定的执行时间已结束。

  • Failed：

    • 单次执行的命令：命令执行完成，且退出码非0。

    • 定时执行的命令：上一次执行成功且退出码非0，且指定的执行时间将被中止。

  • Timeout：命令执行超时。

  • Cancelled：命令的执行动作已经取消，命令未曾启动。

  • Terminated：命令执行时被终止。

Success

exitCode

命令进程的退出码。

0

startTime

任务开始时间。

2023-12-20T06:15:55Z

finishTime

任务结束时间。

2023-12-20T06:15:59Z

errorCode

命令下发失败或执行失败原因错误码。

0

errorDesc

命令下发失败或执行失败的原因详情。

-

云助手首次心跳事件

事件描述

云助手的心跳是判定实例操作系统状态的手段之一。其中，首次心跳可以用来判断操作系统真正启动的时间，作为实例健康状态、下发云助手命令等场景的参考。

相比通过轮询DescribeCloudAssistantStatus的方式查看心跳是否上报，云助手首次心跳事件可以规避以下问题：

  • 轮询查询DescribeCloudAssistantStatus状态是否变为true，实现比较复杂。如果间隔不当，可能产生过多请求，造成流控或对系统造成压力。

  • 由于实例操作系统真正的启动时间差别较大，部分Windows实例偶尔需要5分钟才能启动完成，轮询不容易控制总时长。

  • DescribeCloudAssistantStatus对状态的判断有一定的滞后性，从有心跳到无心跳会有2分钟的滞后，所以对于重启实例的场景，DescribeCloudAssistantStatus不容易识别。

事件触发条件&限制

事件触发条件：在云助手心跳上报时，当判定为首次心跳时触发事件，由云助手服务端发送云助手客户端启动后的首次心跳事件。

云助手版本限制：

  • Windows实例：云助手版本必须高于1.0.0.149。

  • Linux实例：云助手版本必须高于1.0.2.569。

低版本云助手不会通过每分钟一次的心跳上报接口上报心跳，或不会上报index字段，因此不能准确识别出启动后的首次心跳，暂时不对这些低版本做支持。

事件字段说明

字段

说明

示例值

bizEventId

事件ID。

ea33c3e2-aaf0-****-****-5d49b1ecce99

vmName

事件关联的实例ID。

i-bp19****************

extensions

业务扩展信息。

-

azone

可用区。

cn-shenzhen-e

region

地域。

cn-shenzhen

agentVersion

云助手Agent版本。

2.2.3.529

uptime

操作系统已启动的时间（毫秒）

19000

云助手任务执行Output投递结果事件

事件描述

  • 执行命令时，命令执行输出结果最多保留24 KB，超出部分会自动截断。

  • 当期望获取完整的执行Output，或需要持久化保存执行Output时，可以配置命令执行达到终态时，将输出结果投递到的OSS路径。

  • 利用该事件达到以下目的：

    • 获取Output投递结果的通知与投递详情，收到投递成功的事件通知时，可以从对应OSS中下载Output文件，避免轮询调用DescribeInvocations获取结果，提升效率。

    • 当投递失败时，从事件中获得投递失败的详细原因。

事件触发条件&限制

事件触发条件：用户使用RunCommand/InvokeCommand触发任务执行，指定了合法的OssOutputDelivery参数，处于完成状态的任务则发出该事件。

事件使用限制：

  • 仅在云助手在实例上的任务执行状态（InvocationStatus）变为以下状态时，才会触发发送事件。

    • Aborted：任务下发失败

    • Success：任务执行成功

    • Failed：任务执行失败

    • Invalid：任务内容非法

    • Timeout：任务执行超时

    • Cancelled：任务执行取消

    • Terminated：任务执行被终止

云助手版本限制：

  • Windows实例：云助手版本必须高于2.1.4.1007。

  • Linux实例：云助手版本必须高于2.2.4.1007。

事件字段说明

字段

说明

instanceId

实例ID。

invokeId

命令执行ID。

ownerUid

执行命令的实例归属账号。

playerUid

角色扮演者账号id。

repeatMode

命令执行的方式，取值范围：

  • Once：立即执行命令。

  • Period：定时执行命令。

  • NextRebootOnly：当实例下一次启动时，自动执行命令。

  • EveryReboot：实例每一次启动都将自动执行命令。

repeats

命令在该实例上执行的次数。

  • 若执行方式为立即执行，则值为0或1。

    • 0：命令下发失败，命令脚本未启动执行。

    • 1：命令下发成功，命令第一次在此实例上执行。

  • 若执行方式为定时执行，则值为执行过多少次。

ossOutputDelivery

命令执行输出结果投递OSS配置。

ossOutputUri

命令执行输出结果投递到OSS的文件URI地址。

status

投递结果状态。

  • InProgress：投递中。

  • Finished：投递完成。

  • Failed：投递失败。

statusCode

投递状态码，仅在status为Failed时返回。

errorCode

投递失败时的错误码，仅在status为Failed时返回。可能值：

  • UnsupportedInvocationStatus：命令发送失败、命令校验失败。

  • ClientNeedUpgrade：云助手版本不支持投递功能。

  • 投递到OSS失败，请参考错误码

  • 网络不通时返回对应网络库错误码。

errorInfo

投递失败时的错误详情，仅在status为Failed时返回。

云助手Agent升级失败通知事件

事件描述

  • 云助手Agent默认每隔30分钟会自动进行版本升级检查。

  • 通过订阅升级失败通知事件，可以及时获知升级失败的原因与解决方案，方便问题排查。

事件字段说明

字段

说明

示例值

instanceId

实例ID。

i-bp114***************

currentVersion

当前云助手Agent版本。

2.2.3.529

expectedVersion

待升级到的云助手Agent版本。

2.2.4.1007

errorCode

升级失败错误码。详细错误码请参见下方错误码说明。

AgentUpdateFailure:DownloadPackageFailed:NetworkTimeout

errorInfo

升级失败原因。

The aliyun service network is blocked.

occurrenceTime

升级失败发生时间。

2026-02-28T03:30:00Z

错误码说明

错误码统一前缀为AgentUpdateFailure:，具体错误码如下。

失败原因

错误说明

errorCode

下载失败

访问被拒绝。

DownloadPackageFailed:AccessDenied

网络超时。

DownloadPackageFailed:NetworkTimeout

磁盘空间不足。

DownloadPackageFailed:NoEnoughSpace

意外文件结束（数据不完整或连接提前中断）。

DownloadPackageFailed:UnexpectedEOF

MD5校验失败

MD5校验失败。

CheckMD5Failed

安装包解压失败

安装包解压失败。

ExtractPackageFailed

可执行文件验证失败

可执行文件验证失败。

ValidateExecutableFailed

执行升级脚本超时失败

脚本文件不存在。

ExecuteUpdateScriptRunnerTimeout:FileNotExist

进程被信号终止（如SIGKILL、SIGTERM等）。

ExecuteUpdateScriptRunnerTimeout:ExitedBySignal

进程被强制杀死。

ExecuteUpdateScriptRunnerTimeout:Killed

进程退出状态异常（非预期的退出码）。

ExecuteUpdateScriptRunnerTimeout:UnexpectedExitStatus

执行升级脚本失败

脚本文件不存在。

ExecuteUpdateScriptRunnerFailed:FileNotExist

进程被信号终止（如SIGKILL、SIGTERM等）。

ExecuteUpdateScriptRunnerFailed:ExitedBySignal

进程被强制杀死。

ExecuteUpdateScriptRunnerFailed:Killed

进程退出状态异常（非预期的退出码）。

ExecuteUpdateScriptRunnerFailed:UnexpectedExitStatus

事件JSON示例

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234****",
    "source": "acs.ecs",
    "specversion": "1.0",
    "subject": "acs.ecs:cn-hangzhou:123456789098****:215672",
    "time": "2026-02-28T03:30:00+08:00",
    "type": "ecs:CloudAssistant:UpdateFailed",
    "aliyunaccountid": "123456789098****",
    "aliyunpublishtime": "2026-02-28T03:30:01Z",
    "aliyuneventbusname": "default",
    "aliyunregionid": "cn-hangzhou",
    "aliyunpublishaddr": "172.25.XX.XX",
    "data": {
        "instanceId": "i-bp114***************",
        "currentVersion": "2.2.3.529",
        "expectedVersion": "2.2.4.1007",
        "errorCode": "AgentUpdateFailure:DownloadPackageFailed:NetworkTimeout",
        "errorInfo": "The aliyun service network is blocked.",
        "occurrenceTime": "2026-02-28T03:30:00Z"
    }
}

云助手Agent升级成功通知事件

事件描述

  • 云助手Agent默认每隔30分钟会自动进行版本升级检查。

  • 通过订阅升级成功通知事件，可以及时知晓升级情况，方便问题排查。

事件字段说明

字段

说明

示例值

instanceId

实例ID。

i-bp114***************

currentVersion

当前云助手Agent版本。

2.2.4.1007

occurrenceTime

升级成功时间。

2026-02-28T03:30:00Z

事件JSON示例

{
    "id": "f1e2d3c4-b5a6-7890-abcd-123456****",
    "source": "acs.ecs",
    "specversion": "1.0",
    "subject": "acs.ecs:cn-hangzhou:123456789098****:215672",
    "time": "2026-02-28T03:30:00+08:00",
    "type": "ecs:CloudAssistant:UpdateCompleted",
    "aliyunaccountid": "123456789098****",
    "aliyunpublishtime": "2026-02-28T03:30:01Z",
    "aliyuneventbusname": "default",
    "aliyunregionid": "cn-hangzhou",
    "aliyunpublishaddr": "172.25.XX.XX",
    "data": {
        "instanceId": "i-bp114***************",
        "currentVersion": "2.2.4.1007",
        "occurrenceTime": "2026-02-28T03:30:00Z"
    }
}

应用于生产环境建议

  • 幂等性：事件系统可能因为网络或重试导致同一事件被多次投递，处理逻辑需要具备幂等性，即多次处理同一事件和一次处理的结果相同。可以利用事件中的id或data.bizEventId作为唯一标识，在处理前检查该ID是否已被处理过。

  • 重试与死信队列：在配置EventBridge事件目标时，强烈建议配置重试策略和死信队列。当处理函数暂时失败时，EventBridge会自动重试；如果最终依然失败，事件将被发送到死信队列（如MNS队列）中，供后续手动排查和恢复，避免事件丢失。

  • 监控与告警：对事件处理函数本身进行监控。监控其执行成功率、耗时和错误日志，并设置告警。当处理逻辑出现持续性失败时，可以第一时间介入。

常见问题

使用EventBridge订阅云助手事件后，无法收到事件通知？

  1. 检查前置条件：确认云助手版本是否满足要求。

  2. 检查EventBridge规则：

    • 登录EventBridge控制台，确认规则的事件模式是否正确，source应为acs.ecs，type应为正确的事件类型。

    • 使用事件模式调试功能，用一个真实的事件JSON样本测试规则是否能匹配。

  3. 检查事件目标健康度：

    • 在EventBridge控制台的事件规则详情页，查看事件目标的调用记录和错误日志。

    • 确认目标服务（如函数计算、Webhook）本身是否在正常运行，以及网络是否可达。

上一篇：会话操作记录投递下一篇：使用云助手与本地执行命令差异说明