全部产品
Search

搜索本产品

    云服务器 ECS：使用EventBridge和云监控订阅云助手事件

    文档中心

    云服务器 ECS：使用EventBridge和云监控订阅云助手事件

    更新时间：Dec 23, 2025

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

    操作步骤

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

    使用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

    命令下发失败或执行失败原因code。

    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时返回。

    应用于生产环境建议

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

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

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

    常见问题

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

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

    2. 检查EventBridge规则：

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

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

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

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

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