跳到主要内容

ScheduleJobHelper

ScheduleJobHelper 提供平台定时任务的外部管理能力，包括创建、编辑、启用、停用、删除以及按 ID 查询定时任务定义。

概述​

Chameleon 平台的定时任务由调度节点在后台周期触发执行。通过 ScheduleJobHelper，开发者可以在 C# 脚本或微服务中程序化地管理定时任务。执行参数使用字典（Dictionary<string,string>）传递，序列化存储等细节由平台内部处理，开发者无需手动拼接 JSON。

API 方法​

创建定时任务​

CreateScheduleJobAsync — 创建定时任务​

创建一个定时任务，创建后即为启用状态，返回任务 ID。

Task<string> CreateScheduleJobAsync(ScheduleJobCreateRequest request);

主要参数：

参数说明
Name任务名称
Description任务描述（可选）
MetaInterfaceId任务触发时调用的平台接口 ID
CrontabExpressionQuartz Cron 表达式
Params执行参数（key/value 字典），会填充到接口执行上下文

示例：

var jobId = await sdk.ScheduleJobHelper.CreateScheduleJobAsync(new ScheduleJobCreateRequest
{
    Name = "销售报表统计",
    Description = "每天生成销售统计报表",
    MetaInterfaceId = "report-generate-interface-id",
    CrontabExpression = "0 0 9 * * ?",
    Params = new Dictionary<string, string>
    {
        ["reportType"] = "daily",
        ["deptId"] = "10001"
    }
});

sdk.Logger.LogInformation($"已创建定时任务，任务ID: {jobId}");

编辑定时任务​

EditScheduleJobAsync — 编辑定时任务​

编辑已有定时任务，其中 Params 为全量替换。

Task EditScheduleJobAsync(ScheduleJobEditRequest request);

主要参数：

参数说明
Id任务 ID
Name任务名称
Description任务描述
MetaInterfaceId平台接口 ID
CrontabExpressionCron 表达式
Params执行参数（全量替换）

示例：

await sdk.ScheduleJobHelper.EditScheduleJobAsync(new ScheduleJobEditRequest
{
    Id = jobId,
    Name = "销售报表统计",
    CrontabExpression = "0 30 9 * * ?",
    MetaInterfaceId = "report-generate-interface-id",
    Params = new Dictionary<string, string>
    {
        ["reportType"] = "weekly"
    }
});

启用 / 停用定时任务​

EnableScheduleJobAsync — 启用定时任务​

Task EnableScheduleJobAsync(string jobId);

DisableScheduleJobAsync — 停用定时任务​

Task DisableScheduleJobAsync(string jobId);

示例：

// 停用后可通过同一 ID 再次启用
await sdk.ScheduleJobHelper.DisableScheduleJobAsync(jobId);
await sdk.ScheduleJobHelper.EnableScheduleJobAsync(jobId);

查询 / 删除定时任务​

GetScheduleJobAsync — 查询定时任务定义​

根据任务 ID 查询定时任务定义。

Task<ScheduleJobResponse> GetScheduleJobAsync(string jobId);

响应字段：

字段类型说明
Idstring任务 ID
Namestring任务名称
Descriptionstring任务描述
MetaInterfaceIdstring平台接口 ID
CrontabExpressionstringCron 表达式
ParamsDictionary<string,string>执行参数
Statusint0=停用，1=启用

DeleteScheduleJobAsync — 删除定时任务​

删除定时任务定义，后续调度对账会同步移除对应的执行任务。

Task DeleteScheduleJobAsync(string jobId);

示例：

var job = await sdk.ScheduleJobHelper.GetScheduleJobAsync(jobId);
sdk.Logger.LogInformation($"任务名称: {job.Name}, 状态: {job.Status}");

await sdk.ScheduleJobHelper.DeleteScheduleJobAsync(jobId);

典型场景​

每日统计报告的定时调度​

public async Task<object> ExecuteAsync(ComponentContext context, ChameleonSDK sdk)
{
    var jobId = await sdk.ScheduleJobHelper.CreateScheduleJobAsync(new ScheduleJobCreateRequest
    {
        Name = "每日销售汇总",
        Description = "每个工作日早上 9 点生成销售汇总",
        MetaInterfaceId = context.MetaObject.Code,
        CrontabExpression = "0 0 9 ? * MON-FRI",
        Params = new Dictionary<string, string>
        {
            ["summaryType"] = "sales",
            ["includeRegion"] = "true"
        }
    });

    return new { success = true, jobId };
}

注意事项​

  • 定时任务通过平台接口（MetaInterfaceId）执行，请确保接口处于可用状态
  • 调度节点最长需要约 1 分钟才会将配置变更对账同步，创建、编辑、启用、停用、删除后请在下一分钟生效窗口内观察结果
  • 编辑时 Params 为全量替换，若无需修改参数请传入原有参数或省略
  • 执行参数仅支持 string 类型的 key/value，复杂结构请先序列化为字符串

相关文档​