# 新建Flink Jar作业 - CreateFlinkJarJob
#### 功能介绍
该API用于创建用户自定义的作业，目前支持jar格式，运行在独享队列中。
#### 调试
您可以在[API Explorer](https://apiexplorer.developer.huaweicloud.com/apiexplorer/doc?product=DLI&api=CreateFlinkJarJob)中调试该接口。
#### 授权信息
账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。
- 如果使用角色与策略授权，具体权限要求请参见[权限及授权项说明](https://support.huaweicloud.com/api-dli/dli_02_0375.html)。
- 如果使用身份策略授权，需具备如下身份策略权限。
  
  | 授权项 Action | 访问级别 Access Level | 资源类型（\*为必须） Resource Type (\*: required) | 条件键 Condition Key                                                                                                                                                                                                                                                                                             | 别名 Alias | 依赖的授权项 Dependencies |
  |:---|:---|:---|:---|:---|:---|
  | dli:jobs:create                         | write                                           | jobs \*                                                                | -                                                                                                                                                                                                                                                                                                                                          | -                                      | -                                                 |
  | dli:jobs:create                         | write                                           | -                                                                      | - [g:RequestTag/\<tag-key\>](https://support.huaweicloud.com/usermanual-iam5/iam_01_1287.html)  - [g:TagKeys](https://support.huaweicloud.com/usermanual-iam5/iam_01_1287.html)   | -                                      | -                                                 |
     
  
 
#### URI
- URI格式 POST /v1.0/{project_id}/streaming/flink-jobs
  
- 参数说明
  表1URI参数说明 
  | 参数名称       | 是否必选 | 参数类型   | 说明                                                                                     |
  |:---|:---|:---|:---|
  | project_id | 是    | String | 项目编号，用于资源隔离。获取方式请参考[获取项目ID](https://support.huaweicloud.com/api-dli/dli_02_0183.html)。 |
     
  
 
#### 请求消息
表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镜像。 关于如何使用自定义镜像，请参考《[数据湖探索用户指南](https://support.huaweicloud.com/usermanual-dli/dli_01_0494.html)》。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| 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"时，配置无效。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| 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"}} ```    |
   
 表3tags参数 
| 参数名称  | 是否必选 | 参数类型   | 说明                                                                                                                                          |
|:---|:---|:---|:---|
| key   | 是    | String | 标签的键。 说明： 标签的键的最大长度为128个字符，标签的键可以包含任意语种字母、数字、空格和_ . : =+-@ ,但首尾不能含有空格，不能以_sys_开头。 |
| value | 是    | String | 标签的值。 说明： 标签值的最大长度为255个字符，标签的值可以包含任意语种字母、数字、空格和_ . : =+-@ ,但首尾不能含有空格。             |
   
 表4resource_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]。                                                                                                                                                                                      |
   
 表5jobmanager_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。                                                                                                      |
   
 表6taskmanager_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]。 |
   
 表9job参数说明 
| 参数名称        | 是否必选 | 参数类型   | 说明                  |
|:---|:---|:---|:---|
| 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": ""
  }
}
```
#### 状态码
状态码如[表10]所示。
 表10状态码 
| 状态码 | 描述              |
|:---|:---|
| 200 | 新建Flink自定义作业成功。 |
| 400 | 输入参数无效。         |
   
#### 错误码
调用接口出错后，将不会返回上述结果，而是返回错误码和错误信息，更多介绍请参见[错误码](https://support.huaweicloud.com/api-dli/dli_02_0056.html)。