文档首页/数据湖探索 DLI/API参考/Flink作业相关API/新建Flink Jar作业
更新时间：2025-12-30 GMT+08:00
在线调试
CLI示例
查看PDF
分享

新建Flink Jar作业

功能介绍

该API用于创建用户自定义的作业，目前支持jar格式，运行在独享队列中。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。

  • 如果使用角色与策略授权，具体权限要求请参见权限及授权项说明。
  • 如果使用身份策略授权，需具备如下身份策略权限。

    授权项

    Action

    访问级别

    Access Level

    资源类型（*为必须）

    Resource Type (*: required)

    条件键

    Condition Key

    别名

    Alias

    依赖的授权项

    Dependencies

    dli:jobs:create

    write

    jobs *

    -

    -

    -

    -

    -

    -

URI

  • URI格式

    POST /v1.0/{project_id}/streaming/flink-jobs

  • 参数说明
    表1 URI参数说明

    参数名称

    是否必选

    参数类型

    说明

    project_id

    是

    String

    项目编号，用于资源隔离。获取方式请参考获取项目ID。

请求消息

表2 参数说明

参数名称

是否必选

参数类型

说明

name

是

String

作业名称。长度限制：1-57个字符。

desc

否

String

作业描述。长度限制：0-512个字符。

queue_name

否

String

队列名称。长度限制：0-128个字符。

cu_number

否

Integer

用户为作业选择的CU数量。

manager_cu_number

否

Integer

用户为作业选择的管理节点CU数量，对应为flink jobmanager数量。默认值为“1”。

parallel_number

否

Integer

用户为作业选择的并发量。

checkpoint_enabled

否

Boolean

是否开启作业自动快照功能。

  • 开启：true
  • 关闭：false
  • 默认：false

checkpoint_mode

否

Integer

快照模式，两种可选：

  • 1：表示exactly_once，数据只被消费一次。
  • 2：表示at_least_once，数据至少被消费一次。

默认值为1。

checkpoint_interval

否

Integer

快照时间间隔。单位为秒，默认值为“10”。

log_enabled

否

Boolean

是否开启作业日志。

  • 开启：true
  • 关闭：false
  • 默认：false

obs_bucket

否

String

当“log_enabled”为“true”时, 用户授权保存作业日志的OBS桶名。

smn_topic

否

String

当作业异常时，向该SMN主题推送告警信息。

main_class

否

String

作业入口类。

entrypoint_args

否

String

作业入口类参数，多个参数之间空格分隔。

restart_when_exception

否

Boolean

是否开启异常重启功能，默认值为“false”。

entrypoint

否

String

用户已上传到OBS的程序包名，用户自定义作业主类所在的jar包。

Flink1.15推荐配置OBS中的程序包，不推荐使用DLI程序包。Flink1.15以上版本将不再支持读取DLI程序包。

示例：obs://bucket_name/test.jar

dependency_jars

否

Array of Strings

用户已上传到OBS的程序包名，用户自定义作业的其他依赖包。

Flink1.15推荐配置OBS中的程序包，不推荐使用DLI程序包。Flink1.15以上版本将不再支持读取DLI程序包。

示例“obs://bucket_name/test1.jar, obs://bucket_name/test2.jar”。

dependency_files

否

Array of Strings

用户已上传到OBS的资源包名，用户自定义作业的依赖文件。

Flink1.15推荐配置OBS中的程序包，不推荐使用DLI程序包。Flink1.15以上版本将不再支持读取DLI程序包。

示例："[obs://bucket_name/file1, obs://bucket_name/file2]"。

通过在应用程序中添加以下内容可访问对应的依赖文件。其中，“fileName”为需要访问的文件名，“ClassName”为需要访问该文件的类名。

ClassName.class.getClassLoader().getResource("userData/fileName")

tm_cus

否

Integer

每个taskmanager的CU数，默认值为“1”。

tm_slot_num

否

Integer

每个taskmanager的slot数，默认值为“(parallel_number*tm_cus)/(cu_number-manager_cu_number)”。

feature

否

String

作业特性。表示用户作业使用的Flink镜像类型。

  • basic：表示使用DLI提供的基础Flink镜像。
  • custom：表示使用用户自定义的Flink镜像。

flink_version

否

String

Flink版本。当用户设置“feature”为“basic”时，该参数生效。用户可通过与“feature”参数配合使用，指定作业运行使用的DLI基础Flink镜像的版本。

execution_agency_urn

否

String

授权给DLI的委托名。Flink1.15版本时支持配置该参数。

image

否

String

自定义镜像。格式为：组织名/镜像名:镜像版本。

当用户设置“feature”为“custom”时，该参数生效。用户可通过与“feature”参数配合使用，指定作业运行使用自定义的Flink镜像。关于如何使用自定义镜像，请参考《数据湖探索用户指南》。

resume_checkpoint

否

Boolean

异常重启是否从checkpoint恢复。

resume_max_num

否

Integer

异常重试最大次数，单位：次/小时。取值范围：-1或大于0。默认值为“-1”，表示无限次数。

checkpoint_path

否

String

用户Jar中checkpoint的储存地址，不同作业路径需要保持不同。

tags

否

Array of Objects

Flink jar作业的标签。具体请参考表3。

runtime_config

否

String

Flink作业运行时自定义优化参数。

resource_config_version

否

String

资源配置版本。可选值 "v1" ,"v2".默认为“v1”。

v2版本对比于v1模版不支持设置CU数量，支持直接设置Job Manager Memory和Task Manager Memory。

v1：适用于Flink 1.12、Flink 1.15

v2：适用于Flink 1.15、Flink 1.17

优先推荐使用V2版本的参数设置。

resource_config

否

Object

Flink 作业的资源配置。 具体参数说明请参考表4。

资源配置版本 为 "v2"时，配置生效，资源配置版本 为 "v1"时，配置无效。

表3 tags参数

参数名称

是否必选

参数类型

说明

key

是

String

标签的键。

说明：

标签的键的最大长度为128个字符，标签的键可以包含任意语种字母、数字、空格和_ . : =+-@ ,但首尾不能含有空格，不能以_sys_开头。

value

是

String

标签的值。

说明：

标签值的最大长度为255个字符，标签的值可以包含任意语种字母、数字、空格和_ . : =+-@ ,但首尾不能含有空格。

表4 resource_config参数说明

参数名称

是否必选

参数类型

说明

max_slot

否

integer

该参数用于设置单个TaskManager可以提供的并行任务数量。每个Task Slot可以并行执行一个任务。增加 Task Slots 可以提高 TaskManager 的并行处理能力，但也会增加资源消耗。

Task Slots的数量与TaskManager的CPU数相关联，因为每个CPU可以提供一个Task Slot。

单TM Slot默认值为1。最小并行数不能小于1。

parallel_number

否

integer

作业的并行数，指作业中各个算子的并行执行的子任务的数量，算子的子任务数就是其对应算子的并行度。默认值为“1”。

jobmanager_resource_spec

否

Object

JobManager资源规格。具体参数说明请参考表5。

taskmanager_resource_spec

否

Object

TaskManager资源规格。具体参数说明请参考表6。

表5 jobmanager_resource_spec参数说明

参数名称

是否必选

参数类型

说明

cpu

否

double

JobManager可以使用的CPU核数，默认值为1.0个CPU核数，最低不得小于0.5个CPU核数。

如果当前作业是运行在基础版弹性资源池（16-64CUs）上，推荐JobManager CPU的值不超过2，避免执行作业时资源调度失败。

memory

否

string

JobManager可以使用的内存，单位MB，GB。默认GB。默认值为4GB，最低不得小于2G。

表6 taskmanager_resource_spec参数说明

参数名称

是否必选

参数类型

说明

cpu

否

double

TaskManager可以使用的CPU核数，默认值为1.0个CPU核数，最低不得小于0.5个CPU核数。

如果当前作业是运行在基础版弹性资源池（16-64CUs）上，推荐TaskManager CPU的值不超过2，避免执行作业时资源调度失败。

memory

否

string

TaskManager可以使用的内存，单位MB,GB。默认GB。默认值为4GB，最低不得小于2G

响应消息

表7 响应参数说明

参数名称

是否必选

参数类型

说明

is_success

否

String

执行请求是否成功。“true”表示请求执行成功。

message

否

String

消息内容。

job

否

Object

作业状态信息。具体请参考表8。

表8 job参数说明

参数名称

是否必选

参数类型

说明

job_id

是

Long

作业ID。

status_name

否

String

当前状态名称。

status_desc

否

String

当前状态描述。包含异常状态原因及建议。

请求示例

新建名为test的Flink Jar作业，并设置作业执行在testQueue上，设置作业运行所使用的CU数、开启作业日志。

{
    "name": "test",
    "desc": "job for test",
    "queue_name": "testQueue",
    "manager_cu_number": 1,
    "cu_number": 2,
    "parallel_number": 1,
    "tm_cus": 1,
    "tm_slot_num": 1,
    "log_enabled": true,
    "obs_bucket": "bucketName",
    "smn_topic": "topic",
    "main_class": "org.apache.flink.examples.streaming.JavaQueueStream",
    "restart_when_exception": false,
    "entrypoint": "javaQueueStream.jar",
    "entrypoint_args":"-windowSize 2000 -rate 3",
    "dependency_jars": [
        "myGroup/test.jar",
        "myGroup/test1.jar"
    ],
    "execution_agency_urn": "myAgencyName",
    "dependency_files": [
        "myGroup/test.csv",
        "myGroup/test1.csv"
    ]
}

响应示例

{
  "is_success": true,
  "message": "新建flink作业成功",
  "job": {
    "job_id": 138,
    "status_name": "job_init",
    "status_desc": ""
  }
}

状态码

状态码如表9所示。

表9 状态码

状态码

描述

200

新建Flink自定义作业成功。

400

输入参数无效。

错误码

调用接口出错后，将不会返回上述结果，而是返回错误码和错误信息，更多介绍请参见错误码。