# 创建Flink作业 - RunFlinkJob #### 功能介绍 创建并启动Flink作业实例。此接口为异步接口，响应仅表示作业创建请求已接收，作业实际运行状态可通过[查询Flink作业状态](https://support.huaweicloud.com/api-aidatalake/ShowFlinkJobState.html)接口查询。 支持多种作业类型： - FLINK_SQL_JOB：Flink SQL作业，通过SQL脚本定义数据处理逻辑。 - FLINK_JAR_JOB：Flink JAR作业，通过自定义JAR包定义数据处理逻辑。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-aidatalake/aidatalake_02_0003.html)。 #### URI POST /v2/workspaces/{workspace_id}/flink-jobs 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | workspace_id | 是 | String | **参数解释** ：工作空间ID，用于资源隔离。获取方法请参见[获取工作空间ID](https://support.huaweicloud.com/api-aidatalake/aidatalake_02_0044.html)。 **约束限制**：不涉及。 **取值范围**：只能由英文字母、数字及中划线组成，且长度为32\~36个字符。 **默认取值**：不涉及。 | #### 请求参数 表2请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Auth-Token | 是 | String | **参数解释** ：用户Token，用于接口认证鉴权，可通过调用[获取IAM用户Token](https://support.huaweicloud.com/api-iam/iam_30_0001.html)接口获取。 **约束限制**：不涉及。 **取值范围**：长度不超过65534个字符。 **默认取值**：不涉及。 | | X-Client-Token | 否 | String | **参数解释**：客户端Token，用于接口调用幂等校验。 **约束限制**：不涉及。 **取值范围**：长度为1\~64个字符，只能由英文字母、数字、下划线和中划线组成。 **默认取值**：不涉及。 | 表3请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | name | 是 | String | **参数解释**：作业名称，用于标识Flink作业。 **约束限制**：不涉及。 **取值范围**：长度为1\~128个字符，以字母或数字开头和结尾，中间可包含字母、数字、下划线和中划线。 **默认取值**：不涉及。 | | endpoint_name | 是 | String | **参数解释** ：作业运行的端点名称，用于指定作业执行环境。可通过[查询端点列表](https://support.huaweicloud.com/api-aidatalake/ListV2Endpoints.html)或[查询所有端点列表](https://support.huaweicloud.com/api-aidatalake/ListV2AllEndpoints.html)接口获取。 **约束限制**：不涉及。 **取值范围**：只能由英文小写字母、数字及中划线组成，以英文小写字母开头，以英文小写字母或数字结尾，且长度为1\~63个字符。 **默认取值**：不涉及。 | | job_config | 是 | One of: - [FlinkSqlParameter] object - [FlinkJarParameter] object | **参数解释**：作业配置参数，用于指定Flink作业的类型和执行参数。根据作业类型自动选择对应的参数结构：FLINK_SQL_JOB对应FlinkSqlParameter，FLINK_JAR_JOB对应FlinkJarParameter。 **约束限制**：不涉及。 | | deployment_id | 否 | String | **参数解释**：已部署作业ID，用于关联聚合Flink实例。 **约束限制**：不涉及。 **取值范围**：长度为1\~64个字符，只能由英文字母、数字、下划线和中划线组成。 **默认取值**：不涉及。 | | job_agency | 否 | String | **参数解释**：用户自定义委托名称，用于授权作业访问OBS等外部资源。 **约束限制**：须为当前租户下已存在的委托，系统管理委托不可用于提交作业。 **取值范围**：长度为1\~64个字符，字符组成不限制。 **默认取值**：不指定时默认使用端点作业委托。 | | flink_config | 否 | Map\ | **参数解释**：用户自定义的Flink配置参数，为键值对形式。最多支持100个参数，每个值长度为1\~1024个字符。不允许配置execution.checkpointing.dir、execution.checkpointing.savepoint-dir、high-availability.storageDir等系统保留参数，上述系统保留参数由平台根据端点配置自动填充并在查询响应中返回，无需用户配置。 **约束限制**：不涉及。 | | autoscaling_policy | 否 | [AutoscalingPolicy] object | **参数解释**：自动调优配置，用于自动调整作业并行度。不指定时默认不开启自动扩缩容。 **约束限制**：不涉及。 | | image_config | 否 | [FlinkJobImageConfig] object | **参数解释**：镜像配置，用于指定Flink作业运行所需的镜像信息。不指定时系统将根据端点配置自动选择默认镜像。 **约束限制**：不涉及。 | | resource_config | 否 | [FlinkResourceConfig] object | **参数解释**：资源配置，配置作业的并行度和各组件资源规格。 **约束限制**：不涉及。 | | execution_mode | 否 | String | **参数解释**：执行模式，用于指定Flink作业的执行模式。 **约束限制**：不涉及。 **取值范围**： - STREAMING：流模式。 - BATCH：批模式。 **默认取值**：STREAMING。 | | restore_strategy | 否 | [RestoreStrategy] object | **参数解释**：恢复策略配置，用于指定Flink作业的状态恢复策略。 **约束限制**：不涉及。 | | logging_config | 否 | [FlinkLoggingConfig] object | **参数解释**：日志配置，可设置根目录日志级别和自定义日志类级别。 **约束限制**：不涉及。 | | labels | 否 | Array of [FlinkLabel] objects | **参数解释**：标签，用于作业分类和筛选。 **约束限制**：标签数量不能超过16条。 | | description | 否 | String | **参数解释**：描述信息，用于说明作业用途。 **约束限制**：不涉及。 **取值范围**：长度为1\~512个字符。 **默认取值**：不涉及。 | 表4FlinkSqlParameter | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | type | 否 | String | **参数解释**：作业类型。 **约束限制**：固定值为 FLINK_SQL_JOB。 **取值范围**：不涉及。 **默认取值**：FLINK_SQL_JOB。 | | sql_script_file | 是 | String | **参数解释**：SQL脚本所在的OBS文件路径，用于指定SQL作业的脚本文件。 **约束限制**：不涉及。 **取值范围**：OBS URL格式，长度为1\~512个字符，以obs://开头。 **默认取值**：不涉及。 | | dependency_jars | 否 | Array of strings | **参数解释**：SQL作业依赖的JAR包OBS路径列表，用于指定作业运行所需的依赖JAR包，单个路径为OBS URL格式，长度为1\~512个字符，以obs://开头。 **约束限制**：依赖JAR包数量不能超过100个。 | 表5FlinkJarParameter | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | type | 否 | String | **参数解释**：作业类型。 **约束限制**：固定值为 FLINK_JAR_JOB。 **取值范围**：不涉及。 **默认取值**：FLINK_JAR_JOB。 | | main_jar | 是 | String | **参数解释**：JAR作业主类所在JAR包的OBS路径，用于指定作业的入口JAR包。 **约束限制**：不涉及。 **取值范围**：长度为1\~512个字符，以obs://开头。 **默认取值**：不涉及。 | | main_class | 否 | String | **参数解释**：JAR作业入口类全限定名，用于指定作业的入口类。当主程序包manifest中已指定主类时可省略。 **约束限制**：不涉及。 **取值范围**：长度为1\~512个字符，字符组成不限制。 **默认取值**：不涉及。 | | main_args | 否 | Array of strings | **参数解释**：JAR作业入口类参数列表，按数组顺序传入。 **约束限制**：参数数量不能超过100个。 | | dependency_jars | 否 | Array of strings | **参数解释**：JAR作业依赖JAR包的OBS路径列表，用于指定作业运行所需的依赖JAR包，单个路径为OBS URL格式，长度为1\~512个字符，以obs://开头。 **约束限制**：依赖JAR包数量不能超过100个。 | | dependency_files | 否 | Array of strings | **参数解释**：JAR作业依赖文件的OBS路径列表，用于指定作业运行所需的依赖文件，单个路径为OBS URL格式，长度为1\~512个字符，以obs://开头。 **约束限制**：依赖文件数量不能超过100个。 | 表6AutoscalingPolicy | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | enabled | 否 | Boolean | **参数解释**：自动调优开关。 **约束限制**：不涉及。 **取值范围**： - true：开启自动调优。 - false：关闭自动调优。 **默认取值**：false。 | | vertex_max_parallelism | 否 | Integer | **参数解释**：算子最大并行度。 **约束限制**：不涉及。 **取值范围**：1\~1000。 **默认取值**：1000。 | | quota_cpu | 否 | Integer | **参数解释**：CPU配额（单位：毫核）。 **约束限制**：不涉及。 **取值范围**：500\~40000000。 **默认取值**：16000。 | | quota_memory | 否 | Long | **参数解释**：内存配额（单位：MB）。 **约束限制**：不涉及。 **取值范围**：2048\~81920000。 **默认取值**：65536。 | | custom_config | 否 | Map\ | **参数解释**：用户自定义的自动调优配置参数，为键值对形式，传入Flink Kubernetes Operator支持的job.autoscaler.\*参数。最多支持50个参数，每个值长度为1\~1024个字符。 **约束限制**：采用全量替换模式，传入该字段时以本次传入内容为准；不传该字段时不修改自定义自动调优配置。参数名必须以job.autoscaler.开头。结构化字段同名键（job.autoscaler.enabled、job.autoscaler.vertex.max-parallelism、job.autoscaler.quota.cpu、job.autoscaler.quota.memory）配置不生效。 | 表7FlinkJobImageConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | image_id | 是 | String | **参数解释**：镜像ID，用于指定Flink作业运行所需的镜像。须为平台镜像管理中已存在的镜像，传入不存在的镜像时接口返回错误，可通过平台镜像管理功能获取。 **约束限制**：须与image_version_id配合使用，二者对应的镜像版本须已存在。 **取值范围**：长度为2\~64个字符，字符组成不限制。 **默认取值**：不涉及。 | | image_version_id | 是 | String | **参数解释**：镜像版本ID，用于指定Flink作业运行所需的镜像版本。须为平台镜像管理中已存在的镜像版本，传入不存在的镜像版本时接口返回错误，可通过平台镜像管理功能获取。 **约束限制**：须与image_id配合使用，二者对应的镜像版本须已存在。 **取值范围**：长度为2\~64个字符，字符组成不限制。 **默认取值**：不涉及。 | 表8FlinkResourceConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | parallelism | 否 | Integer | **参数解释**：作业并行度，决定作业的并发处理能力。 **约束限制**：不涉及。 **取值范围**：1\~1000。 **默认取值**：1。 | | jobmanager_resource_spec | 否 | [FlinkResourceSpec] object | **参数解释**：JobManager的资源规格，包含CPU、内存、磁盘等信息。 **约束限制**：不涉及。 | | taskmanager_resource_spec | 否 | [FlinkResourceSpec] object | **参数解释**：TaskManager的资源规格，包含CPU、内存、磁盘等信息。 **约束限制**：不涉及。 | 表9FlinkResourceSpec | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | cpu | 否 | Integer | **参数解释**：CPU毫核数，单位为毫核，用于指定JobManager或TaskManager的CPU资源。 **约束限制**：不涉及。 **取值范围**：500\~48000。 **默认取值**：1000。 | | memory | 否 | Integer | **参数解释**：内存大小，单位为MB，用于指定JobManager或TaskManager的内存资源。 **约束限制**：不涉及。 **取值范围**：2048\~393216。 **默认取值**：4096。 | | disk | 否 | Integer | **参数解释**：Pod临时存储容量，单位为GB，用于存放作业运行时的临时文件，临时存储不持久化。 **约束限制**：不涉及。 **取值范围**：30\~1024。 **默认取值**：30。 | 表10RestoreStrategy | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | restore_type | 是 | String | **参数解释**：恢复类型，用于指定作业的恢复策略。 **约束限制**：不涉及。 **取值范围**： - NONE：无状态启动。 - FROM_SAVEPOINT_ID：从指定Savepoint快照恢复。 - FROM_CHECKPOINT_PATH：从指定Checkpoint路径恢复。 - FROM_SPECIFIED_TIMESTAMP：从指定时间戳恢复。 **默认取值**：不涉及。 | | savepoint_id | 否 | String | **参数解释** ：Savepoint的ID，用于唯一标识一个快照，仅当restore_type为FROM_SAVEPOINT_ID时必填。可通过[查询Flink作业Savepoint列表](https://support.huaweicloud.com/api-aidatalake/ListFlinkSavepoint.html)或[创建Flink作业Savepoint](https://support.huaweicloud.com/api-aidatalake/CreateFlinkSavepoint.html)接口获取。 **约束限制**：须为已存在的快照ID，传入不存在的快照ID时接口返回404错误。 **取值范围**：UUIDv7格式，固定36位，由英文小写字母、数字及中划线组成。 **默认取值**：不涉及。 | | checkpoint_path | 否 | String | **参数解释**：Checkpoint的存储路径，需指向_metadata文件的上一级目录，仅当restore_type为FROM_CHECKPOINT_PATH时必填。 **约束限制**：不涉及。 **取值范围**：1\~512个字符，需以obs://开头。 **默认取值**：不涉及。 | | allow_non_restored_state | 否 | Boolean | **参数解释**：允许忽略部分算子状态。仅当JAR类型作业且restore_type为FROM_SAVEPOINT_ID或FROM_CHECKPOINT_PATH时必填。 **约束限制**：不涉及。 **取值范围**： - true：允许忽略部分算子状态。设为true时，如果快照中包含当前作业不再使用的算子状态，将跳过这些状态而非报错。 - false：不允许忽略算子状态。 **默认取值**：不涉及。 | | job_start_time_in_ms | 否 | Long | **参数解释**：源表的数据消费起始时间戳，用于指定作业启动后从源表的哪个时间点开始消费数据。仅当restore_type为FROM_SPECIFIED_TIMESTAMP时必填，且仅支持Kafka源表。 **约束限制**：不涉及。 **取值范围**：0\~4102416000000，13位毫秒时间戳。 **默认取值**：不涉及。 | 表11FlinkLoggingConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | root_logger_level | 否 | String | **参数解释**：根目录日志级别配置，用于控制作业的整体日志输出级别。 **约束限制**：不涉及。 **取值范围**： - TRACE：跟踪。 - DEBUG：调试。 - INFO：信息。 - WARN：警告。 - ERROR：错误。 **默认取值**：不涉及。 | | log4j_loggers | 否 | Array of [FlinkLog4jLoggers] objects | **参数解释**：输出日志类的名称和对应的日志级别配置，用于为指定类设置特定的日志级别。 **约束限制**：配置项数量不能超过20个。 | 表12FlinkLog4jLoggers | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | logger_name | 是 | String | **参数解释**：输出日志类的名称，用于指定需要配置日志级别的类。 **约束限制**：不涉及。 **取值范围**：1\~256个字符，字符组成不限制。 **默认取值**：不涉及。 | | logger_level | 是 | String | **参数解释**：输出日志级别，用于控制该类的日志输出级别。 **约束限制**：不涉及。 **取值范围**： - TRACE：跟踪。 - DEBUG：调试。 - INFO：信息。 - WARN：警告。 - ERROR：错误。 **默认取值**：不涉及。 | 表13FlinkLabel | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | key | 是 | String | **参数解释**：标签键。 **约束限制**：不涉及。 **取值范围**：1\~128个字符，不支持输入等号。 **默认取值**：不涉及。 | | value | 是 | String | **参数解释**：标签值。 **约束限制**：不涉及。 **取值范围**：1\~512个字符，字符组成不限制。 **默认取值**：不涉及。 | #### 响应参数 **状态码：201** 表14响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | job_id | String | **参数解释**：Flink作业ID。 **取值范围**：UUIDv7格式，固定36位，由英文小写字母、数字及中划线组成。 | **状态码：400** 表15响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**：错误码，用于标识具体的错误类型。 **取值范围**：长度为1\~256个字符。 | | error_msg | String | **参数解释**：错误描述信息，用于说明错误原因。 **取值范围**：长度为1\~1024个字符。 | | solution_msg | String | **参数解释**：解决建议，用于提供错误的解决方案。 **取值范围**：长度为0\~1024个字符。 | **状态码：401** 表16响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**：错误码，用于标识具体的错误类型。 **取值范围**：长度为1\~256个字符。 | | error_msg | String | **参数解释**：错误描述信息，用于说明错误原因。 **取值范围**：长度为1\~1024个字符。 | | solution_msg | String | **参数解释**：解决建议，用于提供错误的解决方案。 **取值范围**：长度为0\~1024个字符。 | **状态码：403** 表17响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**：错误码，用于标识具体的错误类型。 **取值范围**：长度为1\~256个字符。 | | error_msg | String | **参数解释**：错误描述信息，用于说明错误原因。 **取值范围**：长度为1\~1024个字符。 | | solution_msg | String | **参数解释**：解决建议，用于提供错误的解决方案。 **取值范围**：长度为0\~1024个字符。 | **状态码：404** 表18响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**：错误码，用于标识具体的错误类型。 **取值范围**：长度为1\~256个字符。 | | error_msg | String | **参数解释**：错误描述信息，用于说明错误原因。 **取值范围**：长度为1\~1024个字符。 | | solution_msg | String | **参数解释**：解决建议，用于提供错误的解决方案。 **取值范围**：长度为0\~1024个字符。 | **状态码：500** 表19响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**：错误码，用于标识具体的错误类型。 **取值范围**：长度为1\~256个字符。 | | error_msg | String | **参数解释**：错误描述信息，用于说明错误原因。 **取值范围**：长度为1\~1024个字符。 | | solution_msg | String | **参数解释**：解决建议，用于提供错误的解决方案。 **取值范围**：长度为0\~1024个字符。 | #### 请求示例 - 创建并启动一个Flink SQL作业，指定作业名称、端点、SQL脚本路径、资源配置等。 ``` POST /v2/workspaces/{workspace_id}/flink-jobs { "name" : "test-flink-job", "description" : "测试Flink SQL作业", "endpoint_name" : "test-endpoint", "job_agency" : "test-agency", "execution_mode" : "STREAMING", "job_config" : { "type" : "FLINK_SQL_JOB", "sql_script_file" : "obs://my-flink-bucket/path/to/script.sql", "dependency_jars" : [ "obs://my-flink-bucket/path/to/dep1.jar" ] }, "flink_config" : { "taskmanager.numberOfTaskSlots" : "1" }, "autoscaling_policy" : { "enabled" : true, "vertex_max_parallelism" : 1000, "quota_cpu" : 4000, "quota_memory" : 8192, "custom_config" : { "job.autoscaler.target.utilization" : "0.6", "job.autoscaler.target.catch-up.duration" : "10 min" } }, "resource_config" : { "parallelism" : 1, "jobmanager_resource_spec" : { "cpu" : 1000, "memory" : 4096 }, "taskmanager_resource_spec" : { "cpu" : 1000, "memory" : 4096 } } } ``` - 创建并启动一个Flink JAR作业，指定主JAR包、主类、入口参数等。 ``` POST /v2/workspaces/{workspace_id}/flink-jobs { "name" : "test-flink-jar-job", "description" : "测试Flink JAR作业", "endpoint_name" : "test-endpoint", "job_agency" : "test-agency", "execution_mode" : "STREAMING", "job_config" : { "type" : "FLINK_JAR_JOB", "main_jar" : "obs://my-flink-bucket/path/jars/WindowJoin.jar", "main_class" : "org.apache.flink.streaming.examples.join.WindowJoin", "main_args" : [ "--input", "obs://bucket/input/", "--output", "obs://bucket/output/" ], "dependency_jars" : [ "obs://my-flink-bucket/path/to/dep1.jar" ], "dependency_files" : [ "obs://my-flink-bucket/path/to/config.csv" ] }, "resource_config" : { "parallelism" : 1, "jobmanager_resource_spec" : { "cpu" : 1000, "memory" : 4096 }, "taskmanager_resource_spec" : { "cpu" : 1000, "memory" : 4096 } } } ``` #### 响应示例 **状态码：201** - 创建并启动一个Flink SQL作业，指定作业名称、端点、SQL脚本路径、资源配置等。 ``` { "job_id" : "019f609a-e90c-xxxx-xxxx-a4ec9018e7f2" } ``` - 创建并启动一个Flink JAR作业，指定主JAR包、主类、入口参数等。 ``` { "job_id" : "019f609a-e90c-xxxx-xxxx-b4ec9018e7f3" } ``` **状态码：400** ``` { "error_code" : "AIDataLake.01011001", "error_msg" : "Invalid parameter", "solution_msg" : "Please check the input parameters according to the documentation." } ``` **状态码：401** ``` { "error_code" : "AIDataLake.01011003", "error_msg" : "Auth Token not exists in header", "solution_msg" : "Please check if auth Token is included in the request header." } ``` **状态码：403** ``` { "error_code" : "AIDataLake.01011005", "error_msg" : "Current account has no permission", "solution_msg" : "Please connect administrators to add permission." } ``` **状态码：404** ``` { "error_code" : "AIDataLake.01051101", "error_msg" : "Flink savepoint 019f68a2-5e11-xxxx-xxxx-6e670d65ab03 does not exist", "solution_msg" : "Please check if Flink savepoint 019f68a2-5e11-xxxx-xxxx-6e670d65ab03 is entered correctly or has been deleted" } ``` **状态码：500** ``` { "error_code" : "AIDataLake.01010001", "error_msg" : "Internal system error", "solution_msg" : "Contact operations for analysis." } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 201 | 请求下发成功。 | | 400 | 请求参数错误。 | | 401 | 认证失败。 | | 403 | 权限不足。 | | 404 | Flink Savepoint不存在。 | | 500 | 系统内部错误。 |