Updating a Flink Jar Job

Function

This API is used to update custom jobs, which currently support the JAR format and run in dedicated queues.

Authorization

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see the required permissions in Introduction.
If you are using identity policy-based authorization, the following identity policy-based permissions are required.
Action

Access Level

Resource Type (*: required)

Condition Key

Alias

Dependencies
dli:jobs:update

write

jobs *

g:ResourceTag/<tag-key>

-

-

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
dli:jobs:update	write	jobs *	g:ResourceTag/<tag-key>	-	-

URI

URI format
PUT /v1.0/{project_id}/streaming/flink-jobs/{job_id}

Parameter descriptions

**Table 1** URI parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID, which is used for resource isolation. For details about how to obtain a project ID, see Obtaining a Project ID.
job_id	Yes	Long	Job ID. Refer to Creating a Flink Jar Job to obtain the value.

Request Parameters

**Table 2** Parameter descriptions
Parameter	Mandatory	Type	Description
name	No	String	Job name. Length range: 0 to 57 characters.
desc	No	String	Job description. Length range: 0 to 512 characters.
queue_name	No	String	Queue name. Length range: 1 to 128 characters.
cu_number	No	Integer	Number of CUs selected for a job. The default value is 2.
manager_cu_number	No	Integer	Number of CUs on the management node selected by the user for a job, which corresponds to the number of Flink job managers. The default value is 1.
parallel_number	No	Integer	Number of parallel operations selected for a job. The default value is 1.
checkpoint_enabled	No	Boolean	Whether to enable automatic job snapshots. Options: true: Enable this function. false: Do not enable this function. Default value: false.
checkpoint_mode	No	Integer	Snapshot mode. Options: 1: ExactlyOnce, meaning data is consumed only once. 2: AtLeastOnce, meaning data is consumed at least once. Default value: 1.
checkpoint_interval	No	Integer	Snapshot interval. The unit is second. The default value is 10.
log_enabled	No	Boolean	Whether to enable job logging. Options: true: Enable this function. false: Do not enable this function. Default value: false.
obs_bucket	No	String	OBS bucket where users are authorized to save logs when log_enabled is set to true.
smn_topic	No	String	SMN topic. If a job fails, the system will send a message to users subscribed to this SMN topic.
main_class	No	String	Job entry class.
entrypoint_args	No	String	Job entry parameter. Multiple parameters are separated by spaces.
restart_when_exception	No	Boolean	Whether to enable restart on exceptions. The default value is false.
entrypoint	No	String	Name of the package that has been uploaded to the DLI resource management system. This parameter is used to customize the JAR file where the job main class is located. For Flink 1.15 or later, you can only select packages from OBS, instead of DLI. Example: obs://bucket_name/test.jar
dependency_jars	No	Array of strings	Name of the package that has been uploaded to the DLI resource management system. This parameter is used to customize other dependency packages. For Flink 1.15 or later, you can only select packages from OBS, instead of DLI. Example: obs://bucket_name/test1.jar, obs://bucket_name/test2.jar
dependency_files	No	Array of strings	Name of the resource package that has been uploaded to the DLI resource management system. This parameter is used to customize dependency files. For Flink 1.15 or later, you can only select packages from OBS, instead of DLI. Example: [obs://bucket_name/file1, obs://bucket_name/file2]
tm_cus	No	Integer	Number of CUs for each TaskManager. The default value is 1.
tm_slot_num	No	Integer	Number of slots in each TaskManager. The default value is *(parallel_numbertm_cus)/(cu_number-manager_cu_number)**.
feature	No	String	Job feature. Type of the Flink image used by a job. basic: indicates that the basic Flink image provided by DLI is used. custom: indicates that the user-defined Flink image is used.
flink_version	No	String	Flink version. This parameter is valid only when feature is set to basic. You can use this parameter with the feature parameter to specify the version of the DLI basic Flink image used for job running.
execution_agency_urn	No	String	Name of the agency authorized to DLI. This parameter is configurable in Flink 1.15.
image	No	String	Custom image. The format is Organization name/Image name:Image version. This parameter is valid only when feature is set to custom. You can use this parameter with the feature parameter to specify a user-defined Flink image for job running. For details about how to use custom images, see Data Lake Insight User Guide.
resume_checkpoint	No	Boolean	Whether the abnormal restart is recovered from the checkpoint.
resume_max_num	No	Integer	Maximum number of retry times upon exceptions. The unit is times/hour. Value range: -1 or greater than 0. The default value is -1, indicating that the number of times is unlimited.
checkpoint_path	No	String	Storage address of the checkpoint in the JAR file of the user. The path must be unique.
runtime_config	No	String	Customizes optimization parameters when a Flink job is running.
job_type	No	String	Job type. Options: flink_jar_job: User-defined Flink job
resource_config_version	No	String	Resource configuration version. The value can be v1 or v2. The default value is v1. Compared with the v1 template, the v2 template does not support the setting of the number of CUs. The v2 template supports the setting of Job Manager Memory and Task Manager Memory. v1: applicable to Flink 1.12 and 1.15. v2: applicable to Flink 1.15 and 1.17. You are advised to use the parameter settings of v2.
resource_config	No	Object	Resource configuration of a Flink job. For detailed parameter descriptions, refer to Table 3. When the resource configuration version is v2, the configuration takes effect; when the resource configuration version is v1, the configuration is invalid.
flink_log_config	No	String	Definition Configuration logs and status. This parameter is supported in Flink 1.15 or later. Range root_logger_level and loggers_level_of_class For details about the log levels, see Table 6. root_logger_level The log level determines the importance and urgency of log messages. The root log level serves as a global setting, providing a default log level for the entire application. If no specific log level is configured for a particular logger or class, the root log level will be applied. For example, if the root log level is set to INFO, all loggers without individual configurations will output logs at the INFO level or higher. Log levels are prioritized from low to high as follows: TRACE < DEBUG < INFO < WARN < ERROR < FATAL. In practice, log levels can be used to filter and display log information effectively. Example: During development, TRACE and DEBUG levels may be enabled for detailed insights. In production environments, only INFO, WARN, and ERROR levels are typically enabled to reduce log file size and improve performance. loggers_level_of_class A class log level refers to a log level specifically assigned to a particular class or package. It enables finer-grained control over logging for different classes or packages. By configuring a class log level, you can obtain more detailed logs for specific classes or packages without affecting other parts of the system. For example, during debugging, you might set the log level of a critical class to DEBUG to gather additional debugging information. Configuration example {"root_logger_level":"INFO","loggers_level_of_class":{"org.apache.flink":"WARN","org.apache.kafka.clients.consumer.KafkaConsumer":"DEBUG","com.mycompany.job.MainFunction":"TRACE"}}

**Table 3** resource_config parameters
Parameter	Mandatory	Type	Description
max_slot	No	Integer	Number of parallel tasks that a single TaskManager can support. Each task slot can execute one task in parallel. Increasing task slots enhances the parallel processing capacity of the TaskManager but also increases resource consumption. The number of task slots is linked to the CPU count of the TaskManager since each CPU can offer one task slot. By default, a single TM slot is set to 1. The minimum parallelism must not be less than 1.
parallel_number	No	Integer	Number of tasks concurrently executed by each operator in a job. The default value is 1.
jobmanager_resource_spec	No	Object	JobManager resource specifications. For details about the parameters, see Table 4.
taskmanager_resource_spec	No	Object	TaskManager resource specifications. For details about the parameters, see Table 5.

**Table 4** jobmanager_resource_spec parameters
Parameter	Mandatory	Type	Description
cpu	No	Double	Number of CPU cores available for JobManager. The default value is 1.0 CPU core, with a minimum of no less than 0.5 CPU cores. If the current job is running on a basic edition elastic resource pool (16–64 CUs), it is recommended that the JobManager's CPU value not exceed 2 to avoid resource scheduling failures during job execution.
memory	No	String	Memory that can be used by JobManager, in MB or GB. The default unit is GB. The default value is 4 GB, and the minimum value is 2 GB.

**Table 5** taskmanager_resource_spec parameters
Parameter	Mandatory	Type	Description
cpu	No	Double	Number of CPU cores available for TaskManager. The default value is 1.0 CPU core, with a minimum of no less than 0.5 CPU cores. If the current job is running on a basic edition elastic resource pool (16–64 CUs), it is recommended that the TaskManager's CPU value not exceed 2 to avoid resource scheduling failures during job execution.
memory	No	String	Memory that can be used by TaskManager, in MB or GB. The default unit is GB. The default value is 4 GB, and the minimum value is 2 GB.

**Table 6** Root log levels
Level	Description	Use Case
TRACE	The most granular level of logging, typically used during development and debugging. It captures all operational details, including variable values and function calls.	Primarily for the development phase to help developers understand code execution flow and state.
DEBUG	Less detailed than TRACE, intended for debugging purposes. It logs program runtime states and key variable values but omits exhaustive detail.	Mainly used during development and testing phases to assist developers in identifying issues.
INFO	Records important information during normal operations, useful for system operators and maintainers without impacting system functionality.	Tracks major system operations and statuses, such as startup, shutdown, and configuration changes.
WARN	Potential issues or anomalies that do not disrupt system operation but warrant attention from developers or operators.	Logs situations that may affect system performance or functionality, serving as a warning for possible problems.
ERROR	Highlights critical issues or exceptions that impair system functionality and require immediate resolution.	Captures errors and exceptions during system operation, enabling developers to quickly identify and address them.

Response Parameters

**Table 7** Response parameters
Parameter	Mandatory	Type	Description
is_success	No	String	Whether the request was successfully executed. true indicates that the request was successfully executed.
message	No	String	Message content.
job	No	Object	Information about job update. For details, see Table 8.

**Table 8** job parameter
Parameter	Mandatory	Type	Description
update_time	No	Long	Time when a job is updated. The unit is millisecond.

Example Request

Update the Flink Jar job information. After the update, the job name is test1, the job execution queue is testQueue, and the job log function is disabled.

{
    "name": "test1",
    "desc": "job for test",
    "job_type": "flink_jar_job",
    "queue_name": "testQueue",
    "manager_cu_number": 1,
    "cu_number": 2,
    "parallel_number": 1,
    "log_enabled": false,
    "main_class": "org.apache.flink.examples.streaming.JavaQueueStream",
    "restart_when_exception": false,
    "entrypoint": "FemaleInfoCollec.jar",
    "dependency_jars": [
        "myGroup/test.jar",
        "myGroup/test1.jar"
    ],
    "execution_agency_urn": "myAgencyName",
    "dependency_files": [
        "myGroup/test.csv",
        "myGroup/test1.csv"
    ]
}

Example Response

{ 
  "is_success": "true",
  "message": "The Flink job is updated successfully.",
  "job": { 
     "update_time": 1516952770835 
  } 
}

Status Codes

Table 9 describes status codes.

**Table 9** Status codes
Status Code	Description
200	The custom Flink job is updated successfully.
400	The input parameter is invalid.

Error Codes

If an error occurs when this API is called, the system does not return the result similar to the preceding example, but returns an error code and error message. For details, see Error Codes.

Parent topic: Flink Job-related APIs

Previous topic: Creating a Flink Jar Job

Next topic: Batch Running Jobs

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

For any further questions, feel free to contact us through the chatbot.

Chatbot