Skip to content

Job Management Rest Api

Jump to bottom
Jeff Zhu edited this page Dec 18, 2017 · 1 revision

1 创建作业

1.1 请求地址：/rest/v1/{namespace}/jobs

1.2 请求方式：POST

1.3 参数说明：

URL参数：

参数名 类型 是否可选 描述
namespace String 必填 域名

Body参数：

参数名 类型 是否可选 描述
jobName String 必填 作业名 A
jobConfig JSONObject 必填 配置
jobConfig.channelName String 发送返回结果的channel名称
jobConfig.cron String 作业调度的Cron表达式。类型是Java和Shell必填。
jobConfig.jobClass String 作业类。类型是Java此项是必填项。
jobConfig.jobParameter String 作业参数
jobConfig.jobType String 必填 作业类型
jobConfig.loadLevel Integer 作业负荷
jobConfig.localMode String 是否为本地模式
jobConfig.pausePeriodDate String 暂停时间日期段
jobConfig.pausePeriodTime String 暂停时间时分段
jobConfig.preferList String 优先executor列表
jobConfig.queueName String MSG作业消费的Queue名称
jobConfig.shardingItemParameters String 必填 分片参数对照表
jobConfig.sharidngTotalCount Integer 必填 分片总数
jobConfig.timeout4AlarmSeconds Integer 作业超时告警阈值
jobConfig.timeoutSeconds Integer 作业超时阈值
jobConfig.useDispreferList Boolean 是否使用非 优先列表
jobConfig.useSerial Boolean MSG作业是否串行
jobConfig.jobDegree Integer 作业重要等级
jobConfig.dependencies String 依赖作业列表

示例：

{
    "jobName": "DemoShellJob", 
    "description": "shell作业例子", 
    "jobConfig": {
        "channelName": "", 
        "cron": "0/5 * * * * ?", 
        "jobClass": "", 
        "jobParameter": "", 
        "jobType": "SHELL_JOB", 
        "loadLevel": 1,
        "localMode": false,
        "pausePeriodDate": "", 
        "pausePeriodTime": "", 
        "preferList": "@yfb-saturn-java.vip.vip.com-xptest1", 
        "queueName": "", 
        "shardingItemParameters": "0=echo 0,1=echo 1",
        "shardingTotalCount": 2, 
        "timeout4AlarmSeconds": 0, 
        "timeoutSeconds": 0, 
        "useDispreferList": true,
        "useSerial": false,
        "jobDegree": 0, 
        "dependencies": ""
    }
}

1.4 返回header（只有失败的情况才有）：application/json;charset=UTF-8

1.5 返回结果：

1.5.1 状态码201，创建成功。

1.5.2 状态码400，参数有误。情况包括

1.5.2.1 参数必填没有填

{"message":"Invalid request. Missing parameter: {parameter}"}

1.5.2.2 参数类型有误

{"message":"Invalid request. Parameter: {parameter} is malformed"}

1.5.2.3 job已经存在

{"message":"Invalid request. Job: {parameter} already existed"}

1.5.3 状态码404，失败。Namespace不存在。

{"message":"The namespace does not exists"}

1.5.4 状态码500，失败。内部错误。

{"message":"Internal server error"}

2 查询单个作业

2.1 请求地址：/rest/v1/{namespace}/jobs/{jobName}

2.2 请求方式：GET

2.3 参数说明：

参数名 类型 是否可选 描述
namespace String 必填 域名
jobName String 必填 作业名

2.4 返回内容格式：application/json;charset=UTF-8

2.5 返回结果：

2.5.1 状态码200，成功。返回内容为JSON字符串，内容demo如下：

{
        "jobName": "DemoShellJob", // 作业名称
        "description": "shell作业例子", // 作业描述
        "runningStatus": "READY", // 作业运行状态
        "enabled": true, // 作业启用状态
        "jobConfig": {
            "channelName": "", // 发送返回结果的Channel名称
            "cron": "0/5 * * * * ?", // 作业调度的cron表达式
            "jobClass": "", // 作业类
            "jobParameter": "", // 作业参数
            "jobType": "SHELL_JOB", // 作业类型
            "loadLevel": 1, // 作业负荷
            "localMode": false, // 是否为本地模式
            "pausePeriodDate": "", // 暂停时间日期段
            "pausePeriodTime": "", // 暂停时间时分段
            "preferList": "@yfb-saturn-java.vip.vip.com-xptest1", // 优先Executor列表
            "queueName": "", // MSG作业消费的Queue名称
            "shardingItemParameters": "0=echo 0,1=echo 1", // 分片参数对照表
            "shardingTotalCount": 2, // 分片总数
            "timeout4AlarmSeconds": 0, // 作业超时（告警）时间
            "timeoutSeconds": 0, // 作业超时（Kill线程/进程）时间
            "useDispreferList": true, // 是否使用非优先Executor
            "useSerial": false, // MSG作业是否串行消费
            "jobDegree": 0, // 作业重要等级：0:没有定义,1:非线上业务,2:简单业务,3:一般业务,4:重要业务,5:核心业务
            "dependencies": "" // 依赖的作业
        },
        "statistics": {
            "lastBeginTime": 1479810720246, // 作业最近执行开始时间
            "lastCompleteTime": 0, // 作业最近执行完成时间
            "nextFireTime": 1479810725000, // 作业下次开始执行时间
            "processCount": 12, // 作业执行次数
            "processErrorCount": 0 // 作业执行失败次数
        }
}

2.5.2 状态码400，参数错误，必填参数没有填。

{"message":"Invalid request. Missing parameter: {parameter}"}

2.5.3 状态码404，Namespace不存在。

{"message":"The namespace/jobName does not exists"}

2.5.4 状态码500，内部错误。

{"message":"Internal server error"}

3 查询域下的作业

3.1 请求地址：/rest/v1/{namespace}/jobs

3.2 请求方式：GET

3.3 参数说明：

参数名 类型 是否可选 描述
namespace String 必填 域名

3.4 返回内容格式：application/json;charset=UTF-8

3.5 返回结果：

3.5.1 状态码200，返回内容为JSON字符串，内容demo如下：

[
    {
        "jobName": "DemoShellJob", // 作业名称
        "description": "shell作业例子", // 作业描述
        "runningStatus": "READY", // 作业运行状态
        "enabled": true, // 作业启用状态
        "jobConfig": {
            "channelName": "", // 发送返回结果的Channel名称
            "cron": "0/5 * * * * ?", // 作业调度的cron表达式
            "jobClass": "", // 作业类
            "jobParameter": "", // 作业参数
            "jobType": "SHELL_JOB", // 作业类型
            "loadLevel": 1, // 作业负荷
            "localMode": false, // 是否为本地模式
            "pausePeriodDate": "", // 暂停时间日期段
            "pausePeriodTime": "", // 暂停时间时分段
            "preferList": "@yfb-saturn-java.vip.vip.com-xptest1", // 优先Executor列表
            "queueName": "", // MSG作业消费的Queue名称
            "shardingItemParameters": "0=echo 0,1=echo 1", // 分片参数对照表
            "shardingTotalCount": 2, // 分片总数
            "timeout4AlarmSeconds": 0, // 作业超时（告警）时间
            "timeoutSeconds": 0, // 作业超时（Kill线程/进程）时间
            "useDispreferList": true, // 是否使用非优先Executor
            "useSerial": false, // MSG作业是否串行消费
            "jobDegree": 0, // 作业重要等级：0:没有定义,1:非线上业务,2:简单业务,3:一般业务,4:重要业务,5:核心业务
            "dependencies": "" // 依赖的作业
        },
        "statistics": {
            "lastBeginTime": 1479810720246, // 作业最近执行开始时间
            "lastCompleteTime": 0, // 作业最近执行完成时间
            "nextFireTime": 1479810725000, // 作业下次开始执行时间
            "processCount": 12, // 作业执行次数
            "processErrorCount": 0 // 作业执行失败次数
        }
    }
]

3.5.2 状态码500，内部错误：

{"message":"The namespace of parameter is required"}

4 启用作业

4.1 请求地址：/rest/v1/{namespace}/jobs/{jobName}/enable

4.2 请求方式：POST

4.3 参数说明：

参数名 类型 是否可选 描述
namespace String 必填 域名
jobName String 必填 作业名

4.4 返回内容格式：application/json;charset=UTF-8

4.5 返回结果：

4.5.1 状态码200，启用成功。

4.5.2 状态码201，原先已经处于启用状态。

4.5.3 状态码403，连续两次更新时间不得小于3秒。返回内容JSON字符串，内容如下：

{"message":"The update interval time cannot less than 3 seconds"}

4.5.4 状态码500，内部错误，返回内容为JSON字符串，内容demo如下：

{"message":"The namespace of parameter is required"}

5 禁用作业

5.1 请求地址：/rest/v1/{namespace}/jobs/{jobName}/disable

5.2 请求方式：POST

5.3 参数说明：

参数名 类型 是否可选 描述
namespace String 必填 域名
jobName String 必填 作业名

5.4 返回内容格式：application/json;charset=UTF-8

5.5 返回结果：

5.5.1 状态码200，禁用成功。

5.5.2 状态码201，原先已经处于禁用状态。

5.5.3 状态码403，连续两次更新时间不得小于3秒。返回内容JSON字符串，内容如下：

{"message":"The update interval time cannot less than 3 seconds"}

5.5.4 状态码500，内部错误，返回内容为JSON字符串，内容demo如下：

{"message":"The namespace of parameter is required"}

6 作业告警

  • 注意：实际的发送告警逻辑需要自行实现（需要修改ReportAlarmService.raise()方法）。

6.1 请求地址：/rest/v1/{namespace}/alarms/raise

6.2 请求方式：POST

6.3 参数说明：

URL参数:

参数名 类型 是否可选 描述
namespace String 必填 域名

Body参数:

参数名 类型 是否可选 描述
jobName String 必填 作业名
executorName String 必填 executor名
shardItem Integer 分片名（如果不填，默认为0）
level String 必填 目前支持：严重告警（CRITICAL）、主要告警（MAJOR）、次要告警（MINOR）、警告告警（WARNING）、清除（CLEAR）
name String 必填 alarm的名字。例如网络中断、osp某种异常等，使用点分隔的字符串。
title String 必填 alarm的简要描述。如果没有特殊需求，可以使用和name相同的字符串。
message String alarm 详细描述
additionalInfo JSONObject 定制参数，以一个Map存储。

示例：

{
    "jobName": "jobA",
    "executorName": "executorName",    
    "shardItem": 0,
    "level":"CRITICAL",
    "name": "PMS.JOB.EXCEPTION",
    "title":"PMS.JOB.EXCEPTION",
    "message":"this is a msg.",
    "additionalInfo": {
        "key1":"value1"
    }
}

6.4 返回header（只有失败的情况才有）：application/json;charset=UTF-8

6.5 返回结果：

6.5.1 状态码201，发送告警成功。

6.5.2 状态码400，参数有误，情况包括

6.5.2.1 参数必填没有填

{"message":"Invalid request. Missing parameter: {parameter}"}

6.5.2.2 参数类型或格式有误

{"message":"Invalid request. Parameter: {parameter} is malformed"}

6.5.2.3 超过配置的域下最大作业数

{"message": "Invalid request. The current number of job reach the maximum limit[100]"}

6.5.4 状态码404，namespace/job/shard不存在。

{"message":"The namespace {parameter} does not exists"}
{"message": "The job {parameter} does not exists."}

6.5.5 状态码500，内部错误。

{"message":"Internal server error"}

7 删除作业

7.1 请求地址：/rest/v1/{namespace}/jobs/{jobName}

7.2 请求方式：DELETE

7.3 参数说明：

URL参数:

参数名 类型 是否可选 描述
namespace String 必填 域名
jobName String 必填 作业名

Body参数:无 7.4 返回header（只有失败的情况才有）：application/json;charset=UTF-8

7.5 返回结果：

7.5.1 状态码204，成功。

7.5.2 状态码400，参数有误，情况包括

7.5.2.1 作业状态不是Stopped

{"message":"job' status is not {STOPPED}"}

7.5.2.2 创建后2分钟内删除

{"message":"Job cannot be deleted until 120 seconds after job creation"}

7.5.3 状态码404，Namespace或Job不存在。

{"message": "The job {JavaJob} does not exists."}

{"message": "The namespace {mydomain2} does not exists."}

7.5.4 状态码500，内部错误。

{"message":"Internal server error"}

8 立即执行作业

8.1 请求地址：/rest/v1/{namespace}/jobs/{jobName}/run

8.2 请求方式：POST

8.3 参数说明：

URL参数:

参数名 类型 是否可选 描述
namespace String 必填 域名
jobName String 必填 作业名

Body参数:无 8.4 返回header（只有失败的情况才有）：application/json;charset=UTF-8

8.5 返回结果：

8.5.1 状态码204，成功。

8.5.2 状态码400，参数有误，情况包括

8.5.2.1 作业状态不是ready

{"message": "job's status is not {READY}"}

8.5.2.2 没有executor

{"message": "no executor found for this job"}

8.5.3 状态码404，Namespace或Job不存在。

{"message": "The job {JavaJob} does not exists."}

{"message": "The namespace {mydomain2} does not exists."}

8.5.4 状态码500，内部错误。

{"message":"The namespace of parameter is required"}

9 立即终止作业

9.1 请求地址：/rest/v1/{namespace}/jobs/{jobName}/stop 9.2 请求方式：POST

9.3 参数说明：

URL参数:

参数名 类型 是否可选 描述
namespace String 必填 域名
jobName String 必填 作业名

Body参数:无 9.4 返回header（只有失败的情况才有）：application/json;charset=UTF-8

9.5 返回结果：

9.5.1 状态码204，成功。

9.5.2 状态码400，参数有误，情况包括

9.5.2.1 作业状态不是stopping （executor处于RUNNING，同时作业被disable）

{"message": "job's status is not {STOPPING}"}

9.5.2.2 作业状态不是enable

{"message": "job cannot be stopped while it is enable"}

9.5.2.3 没有executor

{"message": "no executor found for this job"}

9.5.2.4 作业状态是Ready

{"message": "job cannot be stopped while its status is READY or RUNNING"}

9.5.3 状态码404，Namespace或Job不存在。

{"message": "The job {JavaJob} does not exists."}

{"message": "The namespace {mydomain2} does not exists."}

9.5.4 状态码500，内部错误。

{"message":"The namespace of parameter is required"}
Clone this wiki locally