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

更新SQL作业 - UpdateFlinkSqlJob

功能介绍

该API用于修改Flink SQL作业。

调试

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

授权信息

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

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

    授权项

    Action

    访问级别

    Access Level

    资源类型（*为必须）

    Resource Type (*: required)

    条件键

    Condition Key

    别名

    Alias

    依赖的授权项

    Dependencies

    dli:jobs:update

    write

    jobs *

    -

    -

URI

  • URI格式

    PUT /v1.0/{project_id}/streaming/sql-jobs/12345

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

    参数名称

    是否必选

    参数类型

    说明

    project_id

    是

    String

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

    job_id

    是

    Long

    作业ID。具体可以从新建SQL作业 - CreateFlinkSqlJob中获取。

请求消息

表2 请求参数说明

参数名称

是否必选

参数类型

说明

name

否

String

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

desc

否

String

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

queue_name

否

String

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

sql_body

否

String

Stream SQL语句，至少包含source, query, sink三个部分。长度限制：0-1024*1024个字符。

run_mode

否

String

作业运行模式：

  • shared_cluster：共享。
  • exclusive_cluster：独享。
  • edge_node：边缘节点。

默认值为“shared_cluster”。

cu_number

否

Integer

用户为作业选择的CU数量。默认值为“2”。

parallel_number

否

Integer

用户设置的作业并行数目。默认值为“1”。

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”。

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)”。

operator_config

否

String

算子的并行度配置。

resume_checkpoint

否

Boolean

异常重启是否从checkpoint恢复。

resume_max_num

否

Integer

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

static_estimator_config

否

String

每个算子的流量/命中率配置，json格式的字符串。例如：

{"operator_list":[{"id":"0a448493b4782967b150582570326227","rate_factor":0.55},{"id":"6d2677a0ecc3fd8df0b72ec675edf8f4","rate_factor":1},{"id":"ea632d67b7d595e5b851708ae9ad79d6","rate_factor":0.55},{"id":"bc764cd8ddf7a0cff126f51c16239658","output_rate":2000}]}

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 作业的资源配置。 具体参数说明请参考表3。

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

flink_log_config

否

String

参数解释：

配置日志和状态。Flink 1.15及以上版本支持配置该参数。

取值范围：

包括：root_logger_level、loggers_level_of_class

日志级别取值说明请参考表6。

  • 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 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资源规格。具体参数说明请参考表4。

taskmanager_resource_spec

否

Object

TaskManager资源规格。具体参数说明请参考表5。
表4 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。
表5 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。
表6 根日志与类日志级别

类型

说明

适用场景

TRACE

最细粒度的信息，通常用于开发和调试阶段。它记录系统的所有操作细节，包括变量值、函数调用等。

主要用于开发阶段，帮助开发者理解代码的执行流程和状态。

DEBUG

比TRACE稍低的详细程度，用于调试目的。它记录程序的运行状态和关键变量的值，但不会像TRACE那样记录所有细节。

主要用于开发和测试阶段，帮助开发者定位问题。

INFO

用于记录正常运行时的重要信息，这些信息对系统操作者和维护者有用，但不会影响系统的正常运行。

记录系统的主要操作和状态，例如启动、停止、配置变更等。

WARN

表示潜在问题或异常情况，但不会影响系统的正常运行。它提醒开发者或操作者注意某些可能的问题。

记录可能会影响系统性能或功能的潜在问题。

ERROR

表示严重问题或异常，这些错误会影响系统的正常运行，需要立即处理。

记录系统运行中的错误和异常情况，帮助开发者快速定位和解决问题。

响应消息

表7 响应参数说明

参数名称

是否必选

参数类型

说明

is_success

否

String

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

message

否

String

消息内容。

job

否

Object

作业更新信息。具体请参考表8。
表8 job参数说明

参数名称

是否必选

参数类型

说明

update_time

否

Long

作业更新时间，毫秒数。

请求示例

更新已有的SQL作业，更新后的作业名称为myjob，以共享模式运行在testQueue上。

{
    "name": "myjob",
    "desc": "这是我的第一个作业",
    "queue_name": "testQueue",
    "sql_body": "select * from source_table",
    "run_mode": "shared_cluster",
    "cu_number": 4,
    "parallel_number": 4,
    "checkpoint_enabled": false,
    "checkpoint_mode": "1",
    "checkpoint_interval": 10,
    "log_enabled": false,
    "restart_when_exception": false,
    "idle_state_retention": 3600,
    "edge_group_ids": [
        "62de1e1c-066e-48a8-a79d-f461a31b2ee1",
        "2eb00f85-99f2-4144-bcb7-d39ff47f9002"
    ],
    "dirty_data_strategy": "0",
    "execution_agency_urn": "myAgencyName",
    "udf_jar_url": "group/test.jar"
}

响应示例

{
    "is_success": "true",
    "message": "作业更新成功",
    "job": {
        "update_time": 1578905682534
    }
}

状态码

状态码如表9所示。

表9 状态码

状态码

描述

200

作业更新成功。

400

输入参数无效。

错误码

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

父主题： Flink作业相关API

相关文档