实时计算OpenAPI

    此手册用于记录有数大数据开发与管理平台中，实时计算产品所有对外开放的OpenAPI，阅读此手册，你将了解实时计算产品开放的OpenAPI能力与调用方法。

    文档编辑历史

    版本 日期 编辑人 变更内容
    V1.0.0 2022-01-13 创建文档

    一 公共参数

    1.1 响应格式

    名称 类型 描述
    code Number 响应码：非0表示失败。
    reqId String 请求ID
    msg String 响应消息
    result Object 响应结果
    cost Number 耗时

    1.2 响应码(1000~9999)

    响应码 描述
    1000 openapi请求参数为空！
    1001 请求参数必须extends OpenapiBaseRequest

    1002
    参数[{}]不能为空

    1003
    获取用户[{}]信息失败

    1004
    用户[{}]不存在

    1005
    获取产品信息失败，产品[{}]!

    1006
    用户[{}]产品列表为空

    1007
    用户[{}]不在产品里, 产品[{}]!

    1008
    产品[{}]不存在

    1009
    任务名重复

    1010
    目录[{}],不存在

    1011
    该引擎类型不存在，或者没有入库[{}]

    1012
    目录[{}]格式有问题

    1013
    目录[{}]创建失败

    1014
    目录深度超过两层

    1015
    JAR包不存在

    1016
    任务不存在

    1017
    发布失败，错误原因：[{}]

    1018
    文件已存在

    1019
    文件格式只能是*.jar, *.xml, *.proto, *.keytab, *.conf

    1.3 公共枚举定义

    1.3.1 EngineTypeEnum

    枚举值 类型 名称
    FLINK1_10 String flink引擎版本1.10
    FLINK1_12_0 String flink引擎版本1.12
    FLINK1_13 String flink引擎版本1.13
    FLINK1_14 String flink引擎版本1.14

    1.3.2 startMode

    枚举值 类型 名称
    FROM_LAST_CHECKPOINT String 从最近的checkpoint启动
    FROM_LAST_SAVEPOINT String 从最近的savepoint启动
    FROM_PATH String 从指定的路径启动
    NONE String 直接启动

    1.4 查询实体列表

    1.4.1 JobConfig

    运行参数配置

    字段说明：

    名称 类型 描述 是否必传 默认值
    clusterName String 集群名称 是
    queueName String 队列名称 是
    slots int slot 否 1
    tmMemory int tm内存：单位M 否 2048
    jmMemory int jm内存：单位M 否 2048
    paralleism int 并发数 否 1
    checkpointSwitch boolean cp开关 否 False 关闭
    checkpointInterval int cp间隔：单位s 否 30
    checkpointMode CheckpointMode cp模式 否 EXACTLY_ONCE
    checkpointTimeout int cp超时时间 否 30
    stateBackend StateBackend 存储介质 否 hdfs
    restartStrategy RestartStrategy 重启策略 否 fixed-delay
    restartAttempts int 重启失败次数 否 10
    restartDelay int 重试时间间隔 否 10
    restartInterval int 重启时间范围 否 300
    extendConfig Map flink高级配置 否

    1.4.2 CheckpointMode

    名称 类型 描述
    EXACTLY_ONCE String 至多一次
    AT_LEAST_ONCE String 至少一次

    1.4.3 StateBackend 存储介质

    名称 类型 描述
    hdfs String hdfs
    rocksdb String rocksdb

    1.4.4 RestartStrategy 重启策略

    名称 类型 描述

    fixed-delay    		 String 固定间隔，如果超过最大尝试次数，作业会最终失败，在连续两次重启尝试之间等待固定的时间

    failure-rate    		 String
    		在失败之后重新启动作业，但是当超过故障率时，作业最终会失败。在连续两次重启尝试之间等待固定时间。
    如果没有启用 checkpointing，则使用无重启 (no restart) 策略。
    如果启用了 checkpointing，但没有配置重启策略，则使用固定间隔 (fixed-delay) 策略
    fixed-delay 需要传入重启失败次数和重试时间间隔
    failure-rate 需要传入 重启失败次数、重启时间范围、重试时间间隔

    1.4.5 StartJobInfo

    任务启动参数配置

    字段说明：

    名称 类型 描述 是否必传 默认值
    jobId int 任务id 是
    startMode startMode 启动任务的方式，枚举类型 否 NONE
    statePath String 状态路径 否

    1.4.6 StopJobInfo

    任务停止参数配置

    名称 类型 描述 是否必传 默认值
    jobId int 任务id 是
    triggerSavepoint boolean 是否触发savepoint保存 否

    1.4.7 RestartJobInfo

    任务重启参数配置

    名称 类型 描述 是否必传 默认值
    jobId int 任务id 是
    startMode startMode 启动任务的方式，枚举类型 否 NONE
    statePath String 状态路径 否
    triggerSavepoint boolean 是否触发savepoint保存 否

    1.4.8 AlarmInfo

    告警信息配置

    名称 类型 描述 是否必传 默认值
    emails Array 告警用户信息 否 null
    receiveTypes Array 告警方式的接收类型：
    1：邮箱；4：短信
    5：电话；6：企业微信    		 是 null
    alarmRules Array 告警规则详细描述 是 null
    alarmGroupId int 告警接收组id，如sloth开发组 否 null
    pausingInterval int 全局告警抑制时间 否 null
    pausingEnable boolean 是否开启告警抑制 是 false
    alarmEnable boolean 是否开启告警 是 true

    1.4.9 AlarmRule

    告警规则

    名称 类型 描述 是否必传 默认值
    metricType String 告警指标类型：
    failover
    data_retention_latency：数据滞留延迟
    job_failed：任务失败
    input_qps：输入QPS
    output_qps：输出QPS
    failed_checkpoint：checkpoint失败次数
    user_defined_latency：用户自定义延迟
    record_lag：滞留数据量
    backpressure：反压    		 是
    metricName String 告警指标名称 否 -1
    cycleTime int 单个统计周期的时长：（任务失败不支持配置）
    1：1分钟周期
    5：5分钟周期
    10：10分钟周期
    15：15分钟周期
    20：20分钟周期
    25：25分钟周期
    30：30分钟周期    		 是
    alarmInterval int 报警间隔时长，单位：分钟 是
    suppressOperator String 单个统计周期内的运算符：（仅支持用户自定义延迟）
    >=：大于等于    		 否 -1
    cycleNum String 连续多少个统计周期：
    1：连续1个周期
    3：连续3个周期
    5：连续5个周期    		 否 -1
    threshold String 定义的多个统计周期内告警阈值：（任务失败不支持配置） 否 -1
    suppressThreshold String 单个统计周期内告警阈值：（仅支持用户自定义延迟） 是
    statisticsType String 聚合类型：
    max：最大值
    avg：平均值
    sum：总和    		 否 -1
    operator String 定义的多个统计周期内运算符：（任务失败不支持配置）
    >=：大于等于
    <：小于    		 是 -1

    1.4.10 JobStatusEnum 任务运行状态

    名称 枚举值 任务状态
    JobStatus
    		STARTING 启动中
    START_FAILED 启动失败
    RUNNING 运行中
    FINISHED 任务执行结束，并正确的退出
    FAILED 任务因为异常运行失败
    STOPPING 停止中
    STOPPED 已停止
    UNKNOWN 未知（无法访问集群）

    1.5 响应实体列表

    1.5.1 JobBasicInfo

    名称 类型 描述
    jobId int 任务id
    jobName String 任务名称
    jarInfo JarInfo 对Jar任务的描述
    jobType String boolean 任务类型
    rawSql String SQL文本信息
    udfList ResourceFileSimpleInfo 依赖的udf信息
    fileList ResourceFileSimpleInfo 依赖的文件信息
    creator String 任务的创建者
    createTime String 任务的创建时间
    publisher String 任务的发布人
    env int 环境id
    category int 任务所属目录id
    tags Array 任务的标签信息
    description String 任务的描述信息
    lastStartJobExecHistoryId int 最后一次启动任务的执行id
    startExecId int 任务的启动id
    lastClusterId int 任务所属的集群id
    jobStatus String 任务的运行状态
    applicationId String 对应flink任务id
    flinkUrl String Flink web URL
    monitorUrl String 任务的Grafana监控地址

    1.5.2 ResourceFileSimpleInfo

    名称 类型 描述
    id int 依赖资源id
    name String 依赖资源名称
    path String 依赖资源的绝对路径
    udfName String udf函数名称（udf独有）

    二、OpenAPI列表

    2.1 OpenAPI总览

    模块 名称 支持版本 状态 请求方法 请求路径
    任务管理 新建SQL任务 v3.9.1 已上线 POST /job/v1/sql/create
    修改SQL任务 v3.9.1 已上线 POST /job/v1/sql/modify
    删除任务 v3.9.1 已上线 POST /job/v1/delete
    获取任务信息 v3.9.1 已上线 POST /job/v1/detail
    启动任务 v3.9.1 已上线 POST /job/v1/start
    停止任务 v3.9.1 已上线 POST /job/v1/stop
    重启任务 v3.9.1 已上线 POST /job/v1/restart
    获取任务当前状态 v3.9.1 已上线 POST /job/v1/status

    2.1 新建SQL 任务

    POST /job/v1/sql/create

    版本：3.9.1

    描述：创建SQL类型的任务

    URL参数/请求体

    名称 类型 描述 是否必传 默认值
    user String 用户邮箱 是
    product String 产品名称 是
    jobName String 任务名称 是
    engineType EngineTypeEnum 引擎类型，枚举值 是
    folderPath
    		String
    		保存的文件夹路径，为空：位于根目录，格式：aa/bb，最多支持两级目录 否
    rawSql String sql语句，sql最好传入\n用于分隔 是
    description String 任务描述 否
    dependencyIds Array 依赖文件id列表 否
    udfIds Array 依赖的Udf id列表 否
    jobConfig JobConfig 任务配置参数 是
    alarmInfo AlarmInfo 告警配置 否 默认配置

    请求示例： | Prolog
    {
    “jobName”: “jarName”,
    “engineType”: “FLINK1_12_0”,
    “folderPath”: “/aaa/bbb”,
    “rawSql”: “this is sql”,
    “description”: “jar job description”,
    “dependencyIds”: [
    1,
    2,
    4
    ],
    “udfIds”: [
    1,
    3,
    4
    ],
    “jobConfig”: {},
    “alarmInfo”: {},
    “user”: “yangxiaohang@corp.netease.com”,
    “product”: “sloth”
    } | | —- |

    返回示例：

    名称 类型 描述
    jobId Integer 新创建任务的id

    2.2 修改SQL任务

    POST /job/v1/sql/modify

    版本：3.9.1

    描述：修改SQL类型的任务

    URL参数/请求体

    名称 类型 描述 是否必传 默认值
    user String 用户邮箱 是
    product String 产品名称 是
    jobId String 任务id 是
    engineType EngineTypeEnum 引擎类型，枚举值 是
    folderPath
    		String
    		保存的文件夹路径，为空：位于根目录，格式：aa/bb，最多支持两级目录 否
    rawSql String sql语句，需要传入分割符 是
    description String 任务描述 否
    dependencyIds Array 依赖文件id列表 否
    udfIds Array 依赖的Udf id列表 否
    jobConfig JobConfig 任务配置参数 否
    alarmInfo AlarmInfo 告警配置 否 不传不会修改

    请求示例：

    JSON
    {
    “jobId”: “104722”,
    “jobName”: “sqlOpenApiTest3”,
    “engineType”: “FLINK1_10”,
    “folderPath”: “”,
    “rawSql”: “— nabab\n set ‘user_action.connections.group.id’ = ‘test_group_id’;\nset ‘user_action.connector.startup-mode’ = ‘latest-offset’;\nset ‘tempTable.connector.topic’=’kafka_sink’;\nset ‘tempTable.format.type’ = ‘json’;\ninsert into sloth_autotest_kafka_eleven.mem.tempTable\nselect * from sloth_default_db.user_action;”,
    “description”: “Test2”,
    “dependencyIds”: [10],
    “udfIds”: [26],
    “jobConfig”: {
    “clusterName”: “sloth-internal-test”,
    “queueName”: “root.sloth”
    },
    “user”: “yangxiaohang@corp.netease.com”,
    “product”: “sloth”,
    “authType”: “TEST”
    }

    返回示例：

    JSON
    {
    “code”: 0,
    “msg”: “success”,
    “result”:null,
    “requestId”:null,
    “reqId”:null,
    “cost”: 2072,
    “success”: true
    }

    2.3 删除任务

    POST /job/v1/delete

    版本：3.9.1

    描述：删除调用方传入的任务列表

    URL参数/请求体：

    名称 类型 描述 是否必传 默认值
    user String 用户邮箱 是
    product String 产品名称 是
    jobIds String 待删除的任务id集合，支持传入多个任务，任务id间用逗号分割 是

    请求示例：

    JSON
    {
    “user”: “wanglei20@corp.netease.com”,
    “product”: “sloth”,
    “jobIds”: “1000074”
    }

    响应体：

    JSON
    {
    “code”: 0,
    “msg”: “success”,
    “result”: 1354,
    “requestId”: dcaf583d,
    “success”:true
    }

    2.4 获取任务信息

    POST /job/v1/detail

    版本：3.9.1

    描述：获取最新版本任务信息

    URL参数/请求体：

    名称 类型 描述 是否必传 默认值
    user String 用户邮箱 是
    product String 产品名称 是
    jobId int 任务id 是

    请求示例：

    JSON
    {
    “user”: “wanglei20@corp.netease.com”,
    “product”: “sloth”,
    “jobId”: 1000056
    }

    响应体：

    JSON
    {
    “code”: 0,
    “msg”: “success”,
    “result”: {
    “jobBasicInfo”: {
    “jobId”: 1000056,
    “jobName”: “测试任务2-rename”,
    “jarInfo”: {
    “jarName”: “”,
    “jarPath”: “”,
    “mainClass”: “”,
    “mainArgs”: “”,
    “jarVersion”: “”
    },
    “jobType”: “SQL”,
    “rawSql”: “[{\“cellType\“:\“flink.sql\“,\“enable\“:true,\“key\“:\“743a695f-9099-11ec-ad7c-fa163ea49987\“,\“source\“:[\“—SQL\“,\“—********************************************************************—\“,\“—Author: 杨晓航\“,\“—CreateTime: 2021-12-09 15:57:41\“,\“—Comment: 请输入业务注释信息\“,\“—********************************************************************—\“,\“CREATE TABLE user_log (\“,\“user_id VARCHAR,\“,\“item_id VARCHAR,\“,\“category_id VARCHAR,\“,\“behavior VARCHAR,\“,\“ts VARCHAR\“,\“) WITH (\“,\“‘connector’ = ‘datagen’\“,\“— , ‘number-of-rows’ = ‘10’\“,\“);\“,\“\“,\“create table print_table WITH (‘connector’ = ‘print’)\“,\“LIKE user_log (EXCLUDING ALL);\“,\“\“,\“insert into print_table\“,\“select * from user_log;\“],\“title\“:\“SQL\“}]“,
    “udfList”: [
    {
    “id”: 11378,
    “name”: “changeId”,
    “path”: “/sloth/sloth/RESOURCE/dirid_200458/original-sloth-udf-1.0.1_1596533529506_1609405318875_1623849633571/1623849633599/original-sloth-udf-1.0.1_1596533529506_1609405318875_1623849633571.jar”,
    “udfName”: “changeId”
    }
    ],
    “fileList”: [],
    “creator”: “yangxiaohang@corp.netease.com”,
    “createTime”: “2021-12-09T07:57:41.000+0000”,
    “publisher”: “yangxiaohang@corp.netease.com”,
    “env”: 381,
    “category”: 351,
    “tags”: [],
    “description”: “hffg”,
    “lastStartJobExecHistoryId”: 2745,
    “startExecId”: 2036,
    “lastClusterId”: 1,
    “jobStatus”: “FAILED”,
    “applicationId”: “”,
    “flinkUrl”: “http://sloth-test2.dg.163.org:8088/proxy/application\_1645065290019\_0491/#/overview“,
    “monitorUrl”: “http://sloth.bdms.netease.com/grafana/d/rZuGINgWk/sloth?orgId=1&var-jobAppKey=1000056&var-jobSource=sloth&from=1648028948000&to=1648696837704“
    }
    },
    “requestId”: dcaf583d,
    “success”:true
    }

    响应体描述：

    名称 类型 描述
    jobBasicInfo JobBasicInfo 任务的基本信息

    2.5 启动任务

    POST /job/v1/start

    版本：3.9.1

    描述：启动调用方传入的任务

    URL参数/请求体：

    名称 类型 描述 是否必传 默认值
    user String 用户邮箱 是
    product String 产品名称 是
    jobInfos Array[StartJobInfo](https://as9e2kjei0.feishu.cn/docs/doccnmlWpU6CwjNUSVmMs5IN4uh#RdHi0o)\ 任务的启动信息
    		是

    请求示例：

    JSON
    {
    “user”: “wanglei20@corp.netease.com”,
    “product”: “sloth”,
    “jobInfos”: [
    {
    “jobId”: 1000074,
    “startMode”: “NONE”,
    “statePath”: “”
    }
    ]
    }

    响应体：

    JSON
    {
    “code”: 0,
    “msg”: “success”,
    “result”: {
    “results”: [
    {
    “jobId”: 1000074,
    “jobName”: “testOpenApi”,
    “isSuccess”: true,
    “errorMessage”: “”
    }
    ]
    },
    “requestId”: “914abf5efc64444d92f92418e3c9840c”,
    “success”:true
    }

    2.6 停止任务

    POST /job/v1/stop

    版本：3.9.1

    描述：停止调用方传入的任务

    URL参数/请求体：

    名称 类型 描述 是否必传 默认值
    user String 用户邮箱 是
    product String 产品名称 是
    jobInfos Array[StopJobInfo](https://as9e2kjei0.feishu.cn/docs/doccnmlWpU6CwjNUSVmMs5IN4uh#fVRUrb)\ 任务的停止信息 是

    请求示例：

    JSON
    {
    “user”: “wanglei20@corp.netease.com”,
    “product”: “sloth”,
    “jobInfos”: [
    {
    “jobId”: 1000096,
    “triggerSavepoint”:false
    }
    ]
    }

    响应体：

    JSON
    {
    “code”: 0,
    “msg”: “success”,
    “result”: {
    “results”: [
    {
    “jobId”: 1000096,
    “jobName”: “sqlOpenApiTest3”,
    “isSuccess”:true,
    “errorMessage”: “”
    }
    ]
    },
    “requestId”: “9483bdc3f6d84be7a74f26cb78bd4b6a”,
    “success”:true
    }

    2.7 重启任务

    POST /job/v1/restart

    版本：3.9.1

    描述：重新启动调用方传入的任务

    URL参数/请求体：

    名称 类型 描述 是否必传 默认值
    user String 用户邮箱 是
    product String 产品名称 是
    jobInfos Array[RestartJobInfo](https://as9e2kjei0.feishu.cn/docs/doccnmlWpU6CwjNUSVmMs5IN4uh#c5HM5Q)\ 任务的重启信息 是

    请求示例：

    JSON
    {
    “user”: “wanglei20@corp.netease.com”,
    “product”: “sloth”,
    “jobInfos”: [
    {
    “jobId”: 1000096,
    “startMode”: “NONE”,
    “statePath”: “”,
    “triggerSavepoint”:false
    }
    ]
    }

    响应体：

    JSON
    {
    “code”: 0,
    “msg”: “success”,
    “result”: {
    “results”: [
    {
    “jobId”: 1000096,
    “isSuccess”:true,
    “errorMessage”: “”
    }
    ]
    },
    “requestId”: “19cd594800684549aa420e100f241fc5”,
    “success”:true
    }

    2.7 获取任务当前状态

    POST /job/v1/status

    版本：3.9.1

    描述：批量获取调用方传入任务的当前状态信息

    URL参数/请求体：

    名称 类型 描述 是否必传 默认值
    user String 用户邮箱 是
    product String 产品名称 是
    jobIds String 待查询的任务id集合，支持传入多个任务，任务id间用逗号分割 是

    请求示例：

    JSON
    {
    “user”: “wanglei20@corp.netease.com”,
    “product”: “sloth”,
    “jobIds”: “100056”
    }

    响应体：

    | JSON
    {
    “code”: 0,
    “msg”: “success”,
    “result”: {
    “jobStatusList”: [
    {
    “jobId”: “1000056”,
    “jobStatus”: “FAILED”
    }
    ]
    },
    “requestId”: dcaf583d,
    “success”:true
    } | | —- |