异步任务主要用于支持长任务、重计算场景。函数服务提供 Webserver 模式 和 非 Webserver 模式 的异步任务。两者的主要区别在于业务侧是否需要基于一个 Webserver 来处理请求，在业务场景上并无明显差异。本文为您介绍如何开启这两种模式的异步任务。

前提条件

已在本地完成代码开发，具体请参见 Native 运行时。其中，开发方法章节，Webserver 模式请参照 开发方式（Web 应用）章节，非 Webserver 模式请参照 开发方法（任务） 章节。

使用限制

• 不支持切换同步/异步模式。仅支持创建函数时选择是否开启异步任务模式，函数创建后该配置将锁定，不提供修改更新操作。

• 不支持切换异步任务的 Webserver 模式/非 Webserver 模式。

• 如果您的任务 QPS 较高，建议开启 单实例多并发 配置，或者提高当前函数的 实例数上限 配置。

• 仅支持对系统错误进行自动重试，暂不支持用户侧的任务重试。

• 当前支持的任务执行时长范围为 10 s ~ 3 h。请根据业务实际需要设置合理的超时时间。

• 当任务超时/用户主动终止（Terminate）任务时，veFaaS 的表现根据以下情况略有不同：

  • 对于 Webserver 模式:
    • 如果未开启单实例多并发，veFaaS 会终止请求并重启业务（Webserver）进程。
    • 如果开启单实例多并发，veFaaS 仅取消（Cancel）对应的请求。

      注意

      请确保在业务逻辑中正确处理取消信号，例如监听 Context 取消信号并终止业务逻辑执行。否则，您的业务逻辑可能会在请求被取消后继续执行，从而导致资源浪费或任务未按预期停止。

  • 对于 非 Webserver 模式，veFaaS 会终止相应的任务进程。

• 对于已经完成的任务，任务执行状态最长可保存 30 天或 1000 条。1000 条记录和 30 天记录，两者之间为 逻辑或 关系。

• 当前支持的事件触发类型有：API 网关触发器、Timer 触发器。

• 异步任务 Payload 最大支持 128 KB。

开启异步任务

按如下步骤说明，开启异步任务：

1. 创建异步任务函数。
   • Webserver 模式
     创建函数时选择 创建「事件函数」或 创建「Web 应用」，并在 高级配置 中启用异步任务。
   • 非 Webserver 模式
     创建函数时选择 创建「任务」，该场景会自动启用异步任务。

2. 将函数 发布 至线上。

异步任务结果回调

veFaaS 接收异步调用请求后，将请求持久化并立即返回响应，无需等待请求执行完成。如果您需要在函数异步执行失败后将结果通知到下游服务，可以通过配置结果回调功能实现。配置异步目标服务后，异步调用请求执行完成，veFaaS 根据执行结果自动回调对应的服务。

场景介绍

异步任务结果回调适用于如下场景：

• 保存会被丢弃的事件供后续使用
  当异步任务执行失败，并且按照指定的策略重试后仍然失败时，如果您需要及时感知任务失败信息，并按需进行处理，可通过配置异步任务结果回调，将失败事件推送到目标服务。您也可以将目标服务设置为另一个函数，veFaaS 会自动把失败事件的上下文信息推送到该函数，执行您自定义的错误处理逻辑。
• 自动通知下游服务执行结果
  异步任务执行成功后，如果需要将结果自动通知到下游服务，方便下游服务进行下一步动作，可通过配置异步任务结果回调实现。例如，您配置了使用 veFaaS 实现自动解压上传到火山引擎对象存储（TOS）的 ZIP 文件，解压完成后想要接收消息通知，可以为目标服务配置异步任务结果回调。

使用限制

• 当前仅支持 HTTP(S) 类型的 Webhook 作为异步调用目标服务。
• 仅支持配置一个目标服务。
• 请勿回调函数自身，避免循环调用。
• Webserver 类型异步任务返回的负载大小限制为 64 KiB，若超过该大小，在回调消息中会进行截断处理。

回调消息格式

回调消息格式及各参数说明，如下代码片段所示：

{
    "version": "1.0", // 回调消息版本，当前固定为 1.0。
    "timestamp": 1733998143975, // 回调发起时间，毫秒精度时间戳。
    "requestContext": { // 请求上下文。
        "requestId": "e4b46cbf-b738-xmpl-8880-********", // 异步任务的请求 ID。
        "functionName": "my-function", // 函数名称。
        "condition": "RetriesExhausted", // 调用错误码。
        "approximateInvokeCount": 3 // 异步任务的执行次数。当该值大于 1 时，说明函数服务对您的任务进行了重试。
    },
    "requestPayload": { // 提交任务的原始请求负载。
        "tos_bucket": "my-bucket"
    },
    "responseContext": { // 响应上下文。
        "statusCode": 200, // Webserver 模式下表示函数返回的状态码，非 Webserver 模式下表示任务的退出码。
        "revisionNumber": 1, // 函数版本。
        "functionError": "Unhandled" // 任务执行失败信息。
    },
    "responsePayload": { // Webserver 模式下表示函数返回的原始负载，非 Webserver 模式下为空。
        "errorMessage": "error executing command `exit 1`: exit status 1, please check the logs for more details" // 详细的错误信息。
    }
}

配置异步回调目标服务

1. 登录 函数服务控制台。
2. 左侧导航栏单击 函数，找到已开启异步任务的函数后，单击函数名称。
3. 在函数详情页的 函数配置 页签，编辑异步任务。
   
4. 在异步任务的 编辑配置信息 页面，配置异步回调目标服务。
   

   参数	说明
   异步任务重试次数	异步任务失败重试的次数。取值范围：0 ~ 3。
   异步目标配置	配置异步回调的目标服务： 成功时调用：异步任务执行成功后，调用目标服务。 失败时调用：异步任务执行失败后，调用目标服务。 注意 仅支持配置 HTTP(S) 类型的 Webhook 作为后端服务。 请确保配置的 目标服务 能够通过私有网络（VPC）或公网访问。

5. 单击 保存，保存配置。

后续操作

提交任务，通过异步模式调用函数。提交任务、终止任务等详情可参见 任务管理。