HTTP 任务 (HttpJob)
约 515 字大约 2 分钟
2026-05-19
概述 (Overview)
HttpJob 是 UniCon 内置的 HTTP 请求定时任务,基于 IHttpClientFactory 实现,支持 GET、POST、PUT、DELETE 等所有标准 HTTP 方法。可配置请求头、Query 参数及请求体,适用于定时向云平台 Webhook、RESTful API 发送数据或心跳包。
任务执行结果记录在日志系统中,不抛出异常(异常时降级为日志记录),保证调度器稳定运行。
使用方法 (Usage)
通过 JobScheduler.ScheduleJobAsync<HttpJob>() 注册任务,使用 JobDataMap 传入参数:
await jobScheduler.ScheduleJobAsync<HttpJob>(
jobId: "PushDataToCloud",
cronExpression: "0 0/5 * * * ?",
data: new JobDataMap
{
[JobDataKeys.HttpUrl] = "https://api.example.com/v1/data",
[JobDataKeys.HttpMethod] = "POST",
[JobDataKeys.HttpBody] = "{\"deviceId\": \"PLC_01\", \"status\": \"running\"}",
[JobDataKeys.HttpHeaders]= "{\"Authorization\": \"Bearer token123\", \"Content-Type\": \"application/json\"}"
}
);参数说明 (Parameters)
通过 JobDataMap 传递以下键值(使用 JobDataKeys 常量类访问,避免拼写错误):
| JobDataKeys 常量 | 实际键名 | 类型 | 说明 | 是否必填 | 默认值 |
|---|---|---|---|---|---|
JobDataKeys.HttpUrl | Job_Http_Url | string | 目标 URL | 是 | — |
JobDataKeys.HttpMethod | Job_Http_Method | string | 请求方法(GET、POST、PUT、DELETE 等) | 否 | "GET" |
JobDataKeys.HttpHeaders | Job_Http_Headers | string | JSON 序列化的请求头字典 Dictionary<string, string> | 否 | 无 |
JobDataKeys.HttpQueryParams | Job_Http_QueryParams | string | JSON 序列化的 Query 参数字典 Dictionary<string, string> | 否 | 无 |
JobDataKeys.HttpBody | Job_Http_Body | string | 请求体字符串(固定以 application/json 编码发送) | 否 | 无 |
返回值 (Returns)
HttpJob 为异步执行任务,无直接返回值。执行结果通过日志系统记录:
| 情况 | 日志级别 | 内容 |
|---|---|---|
| 执行开始 | Information | Executing HttpJob: {Method} {Url} |
| 执行成功 | Information | HttpJob response: {StatusCode} |
| URL 为空 | Warning | HttpJob skipped: URL is null or empty. |
| 执行失败 | Error | HttpJob request failed. {Exception} |
| Query 参数解析失败 | Error | Failed to parse HttpJob query parameters. {Exception} |
| 请求头解析失败 | Error | Failed to apply HttpJob headers. {Exception} |
使用示例 (Examples)
示例 1:每 5 分钟 POST 数据到云端 Webhook
await jobScheduler.ScheduleJobAsync<HttpJob>(
jobId: "PushDataToCloud",
cronExpression: "0 0/5 * * * ?", // 每 5 分钟
data: new JobDataMap
{
[JobDataKeys.HttpUrl] = "https://api.example.com/v1/data",
[JobDataKeys.HttpMethod] = "POST",
[JobDataKeys.HttpBody] = "{\"deviceId\": \"PLC_01\", \"status\": \"running\"}",
[JobDataKeys.HttpHeaders] = "{\"Authorization\": \"Bearer token123\"}"
}
);示例 2:带 Query 参数的定时 GET 请求
await jobScheduler.ScheduleJobAsync<HttpJob>(
jobId: "QueryCloudConfig",
cronExpression: "0 0 * * * ?", // 每小时
data: new JobDataMap
{
[JobDataKeys.HttpUrl] = "https://config.example.com/api/settings",
[JobDataKeys.HttpMethod] = "GET",
[JobDataKeys.HttpQueryParams] = "{\"gatewayId\": \"GW_01\", \"version\": \"2\"}"
}
);示例 3:每 5 分钟 GET 心跳检测
await jobScheduler.ScheduleJobAsync<HttpJob>(
jobId: "Heartbeat",
cronExpression: "0 0/5 * * * ?",
data: new JobDataMap
{
[JobDataKeys.HttpUrl] = "https://api.example.com/heartbeat",
[JobDataKeys.HttpMethod] = "GET"
}
);