新建SQL作业 - CreateFlinkSqlJob

功能介绍

该API用于创建Flink SQL作业。

调试

您可以在API Explorer中调试该接口。

授权信息

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

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

如果使用身份策略授权，需具备如下身份策略权限。

授权项 Action	访问级别 Access Level	资源类型（为必须） Resource Type (: required)	条件键 Condition Key	别名 Alias	依赖的授权项 Dependencies
dli:jobs:create	write	jobs *	-	-	-
-	g:RequestTag/<tag-key> g:TagKeys	-	-

授权项

Action

访问级别

Access Level

资源类型（*为必须）

Resource Type (*: required)

条件键

Condition Key

别名

Alias

依赖的授权项

Dependencies

dli:jobs:create

write

jobs *

URI

URI格式
 POST /v1.0/{project_id}/streaming/sql-jobs
参数说明

表1 URI参数说明

参数名称

是否必选

参数类型

说明

project_id

是

String

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

表1 URI参数说明
参数名称	是否必选	参数类型	说明
project_id	是	String	项目编号，用于资源隔离。获取方式请参考获取项目ID。

请求消息

表2 请求参数说明
参数名称	是否必选	参数类型	说明
name	是	String	作业名称。长度限制：1-57个字符。
desc	否	String	作业描述。长度限制：0-512个字符。
template_id	否	Integer	模板ID。如果“template_id”和“sql_body”都不为空，优先选择“sql_body”的内容；如果“template_id”不为空，“sql_body”为空，选择“template_id”的内容填充“sql_body”。
queue_name	否	String	队列名称。长度限制：0-128个字符。
sql_body	否	String	Stream SQL语句，至少包含source, query, sink三个部分。长度限制：1024*1024个字符。
run_mode	否	String	作业运行模式： shared_cluster：共享。 exclusive_cluster：独享。 edge_node：边缘节点。默认值为“shared_cluster”。
cu_number	否	Integer	用户为作业选择的CU数。默认值为“2”。 CU数量为DLI的计算单元数量和管理单元数量总和，CU也是DLI的计费单位，1CU=1核4G。当前配置的CU数量为运行作业时所需的CU数，不能超过其绑定队列的CU数量。管理单元参数设置详见：manager_cu_number。
parallel_number	否	Integer	用户设置的作业并行数目。默认值为“1”。并行数是指同时运行Flink SQL作业的最大任务数。适度增加并行数会提高作业整体算力，但也须考虑线程增多带来的切换开销。最大并行数不能大于计算单元（CU数量-管理单元）的4倍。管理单元参数设置详见：manager_cu_number。
checkpoint_enabled	否	Boolean	是否开启作业自动快照功能。开启：true 关闭：false 默认：false
checkpoint_mode	否	String	快照模式，两种可选： 1：表示exactly_once，数据只被消费一次。 2：表示at_least_once，数据至少被消费一次。默认值为1。
checkpoint_interval	否	Integer	快照时间间隔。单位为秒，默认值为“10”。
obs_bucket	否	String	当“checkpoint_enabled”为“true”时，该参数是用户授权保存快照的OBS桶名。当“log_enabled” 为“true”时，该参数是用户授权保存作业日志的OBS桶名。
log_enabled	否	Boolean	是否开启作业的日志上传到用户的OBS功能。默认为“false”。
smn_topic	否	String	当作业异常时，向该SMN主题推送告警信息。
restart_when_exception	否	Boolean	是否开启作业异常自动重启。默认为“false”。
idle_state_retention	否	Integer	空闲状态保留时间。单位为秒，默认值为“3600”。
job_type	否	String	作业类型：flink_sql_job、flink_opensource_sql_job。默认值：“flink_opensource_sql_job”。 “run_mode”为“exclusive_cluster”时，作业类型须为“flink_sql_job”或“flink_opensource_sql_job”。 “run_mode””为“shared_cluster”时作业类型必须为”flink_sql_job“。
edge_group_ids	否	Array of Strings	边缘计算组ID列表, 多个ID以逗号分隔。
dirty_data_strategy	否	String	作业脏数据策略。 “2:obsDir”：保存，obsDir表示脏数据存储路径。 “1”：抛出异常。 “0”：忽略。默认值为“0”。
udf_jar_url	否	String	用户已上传到DLI资源管理系统的资源包名，用户sql作业的udf jar包通过该参数传入。 Flink1.15及以上版本在创建作业时仅支持配置OBS中的程序包，不支持读取DLI程序包。
manager_cu_number	否	Integer	用户为作业选择的管理单元（jobmanager）CU数量，默认值为“1”。
tm_cus	否	Integer	每个taskmanager的CU数，默认值为“1”。
tm_slot_num	否	Integer	每个taskmanager的slot数，默认值为“(parallel_number*tm_cus)/(cu_number-manager_cu_number)”。
resume_checkpoint	否	Boolean	异常重启是否从checkpoint恢复。
resume_max_num	否	Integer	异常重试最大次数，单位：次/小时。取值范围：-1或大于0。默认值为“-1”，表示无限次数。
tags	否	Array of Objects	Flink SQL作业的标签。具体请参考表3。
runtime_config	否	String	Flink作业运行时自定义优化参数。
flink_version	否	String	Flink版本。
execution_agency_urn	否	String	授权给DLI的委托名。Flink1.15版本时支持配置该参数。
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"时，配置无效。
flink_log_config	否	String	参数解释：配置日志和状态。Flink 1.15及以上版本支持配置该参数。取值范围：包括：root_logger_level、loggers_level_of_class 日志级别取值说明请参考表7。 root_logger_level 日志级别用于区分日志信息的重要性和紧急程度。根日志级别是全局的日志级别设置，它为整个应用程序提供了一个默认的日志级别。当没有为特定的日志记录器或类设置日志级别时，根日志级别将被使用。例如，如果根日志级别设置为INFO，那么所有未单独设置级别的日志记录器都将输出INFO及以上级别的日志。从低到高，日志级别的优先级通常为：TRACE<DEBUG<INFO<WARN<ERROR<FATAL 在实际使用中，可以根据日志级别来过滤和显示日志信息。例如：在开发阶段，可能会启用TRACE和DEBUG级别。在生产环境中，通常只启用INFO、WARN和ERROR级别，以减少日志文件的大小和提高性能。 loggers_level_of_class 类日志等级是指针对特定类或包设置的日志级别。它允许用户对不同的类或包进行更精细的日志控制。通过设置类日志等级，可以对特定的类或包进行更详细的日志记录，而不会影响到其他部分的日志输出。例如，在调试过程中，可以将某个关键类的日志级别设置为DEBUG，以便获取更多调试信息。配置样例 {"root_logger_level":"INFO","loggers_level_of_class":{"org.apache.flink":"WARN","org.apache.kafka.clients.consumer.KafkaConsumer":"DEBUG","com.mycompany.job.MainFunction":"TRACE"}}

表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 根日志与类日志级别
类型	说明	适用场景
TRACE	最细粒度的信息，通常用于开发和调试阶段。它记录系统的所有操作细节，包括变量值、函数调用等。	主要用于开发阶段，帮助开发者理解代码的执行流程和状态。
DEBUG	比TRACE稍低的详细程度，用于调试目的。它记录程序的运行状态和关键变量的值，但不会像TRACE那样记录所有细节。	主要用于开发和测试阶段，帮助开发者定位问题。
INFO	用于记录正常运行时的重要信息，这些信息对系统操作者和维护者有用，但不会影响系统的正常运行。	记录系统的主要操作和状态，例如启动、停止、配置变更等。
WARN	表示潜在问题或异常情况，但不会影响系统的正常运行。它提醒开发者或操作者注意某些可能的问题。	记录可能会影响系统性能或功能的潜在问题。
ERROR	表示严重问题或异常，这些错误会影响系统的正常运行，需要立即处理。	记录系统运行中的错误和异常情况，帮助开发者快速定位和解决问题。

响应消息

表8 响应参数说明
参数名称	是否必选	参数类型	说明
is_success	否	String	执行请求是否成功。“true”表示请求执行成功。
message	否	String	消息内容。
job	否	Object	作业状态信息。具体请参考表9。

表9 job参数说明
参数名称	是否必选	参数类型	说明
job_id	是	Long	作业ID。
status_name	否	String	当前状态名称。参数说明可以参考查询作业详情 - ShowFlinkJob中status作业状态字段说明。
status_desc	否	String	当前状态描述。包含异常状态原因及建议。

请求示例

使用ID为100000的模板创建名为myjob的Flink SQL作业，该作业执行在testQueue队列上以独享的模式运行。

{
    "name": "myjob",
    "desc": "这是个做字符记数的作业",
    "template_id": 100000,
    "queue_name": "testQueue",
    "sql_body": "select * from source_table",
    "run_mode": "exclusive_cluster",
    "cu_number": 2,
    "parallel_number": 1,
    "checkpoint_enabled": false,
    "checkpoint_mode": "1",
    "checkpoint_interval": 0,
    "obs_bucket": "my_obs_bucket",
    "log_enabled": false,
    "restart_when_exception": false,
    "idle_state_retention": 3600,
    "job_type": "flink_sql_job",
    "dirty_data_strategy": "0",
    "execution_agency_urn": "myAgencyName",
    "udf_jar_url": "group/test.jar"
}

响应示例

{
    "is_success": "true",
    "message": "创建作业成功",
    "job": {
        "job_id": 148,
        "status_name": "job_init",
        "status_desc": ""
    }
}