# 启动Spark作业 - RunSparkJob #### 功能介绍 启动Spark作业，此接口为异步接口。支持Spark Jar作业、Python作业和SQL Script作业。调用该接口后，作业将提交到队列等待执行，返回作业ID后需通过查询作业状态接口确认作业是否成功启动。查询作业状态请参见[查询Spark作业的状态](https://support.huaweicloud.com/api-aidatalake/ShowSparkJobState.html)。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-aidatalake/aidatalake_02_0003.html)。 #### URI POST /v2/workspaces/{workspace_id}/spark-jobs 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | workspace_id | 是 | String | **参数解释**：工作空间ID，用于资源隔离。可在控制台的工作空间页面查看。 **约束限制**：不涉及。 **取值范围**：只能由英文字母、数字及中划线组成，且长度为32\~36个字符。 **默认取值**：不涉及。 | #### 请求参数 表2请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Auth-Token | 是 | String | **参数解释**：用户Token。 **约束限制**：不涉及。 **取值范围**：长度不超过65534个字符。 **默认取值**：不涉及。 | | X-Client-Token | 否 | String | **参数解释**：服务事务ID，用于链路追踪和防止重复提交。 **约束限制**：不涉及。 **取值范围**：采用UUID格式，长度为36个字符。 **默认取值**：不涉及。 | 表3请求Body参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | name | 是 | String | **参数解释**：Spark作业名称，用于标识作业。 **约束限制**：不涉及。 **取值范围**：长度为1\~128个字符。 **默认取值**：不涉及。 | | endpoint_name | 是 | String | **参数解释**：端点名称，用于指定Spark作业执行环境。 **约束限制**：不涉及。 **取值范围**：只能由英文小写字母、数字及中划线组成，以英文小写字母开头，以英文小写字母或数字结尾，且长度为1\~63个字符。 **默认取值**：不涉及。 | | job_config | 是 | One of: - [SparkJarParameter] object - [SparkPyParameter] object - [SparkSqlScriptParameter] object | **参数解释**：作业配置参数，用于指定Spark作业的类型和执行参数。根据作业类型自动选择对应的参数结构：spark_jar_job对应SparkJarParameter，spark_python_job对应SparkPyParameter，spark_sql_scripting_job对应SparkSqlScriptParameter。 **约束限制**：不涉及。 | | catalog_name | 否 | String | **参数解释**：Catalog名称，用于指定作业使用的数据目录。 **约束限制**：不涉及。 **取值范围**：长度不超过128个字符。 **默认取值**：不涉及。 | | job_agency | 否 | String | **参数解释**：自定义委托名称，用于作业操作OBS对象、转储日志、访问DLI元数据等。 **约束限制**：不涉及。 **取值范围**：长度为1\~64个字符。 **默认取值**：不涉及。 | | resource_config | 否 | [SparkResourceConfig] object | **参数解释**：Spark作业资源配置，用于配置Driver和Executor的资源规格和数量。 **约束限制**：不涉及。 | | spark_config | 否 | Map\ | **参数解释**：用户自定义Spark参数配置，用于优化Spark作业性能。 **约束限制**：最多支持100个参数。 | | image | 否 | [SparkJobImageConfig] object | **参数解释**：Spark镜像配置，用于指定Spark作业运行所需的镜像信息。 **约束限制**：不涉及。 | | logging_config | 否 | [SparkLoggingConfig] object | **参数解释**：Spark作业日志配置，用于配置Driver和Executor的日志级别。 **约束限制**：不涉及。 | | restore_strategy | 否 | [SparkRestoreStrategy] object | **参数解释**：作业恢复策略配置，用于定义作业失败后的重试机制和超时控制。 **约束限制**：不涉及。 | | labels | 否 | Array of [SparkJobLabel] objects | **参数解释**：作业标签列表，用于标识和分类作业。 **约束限制**：标签数量不能超过16条。 | | description | 否 | String | **参数解释**：Spark作业描述信息，用于说明作业用途。 **约束限制**：不涉及。 **取值范围**：长度为1\~512个字符。 **默认取值**：不涉及。 | 表4SparkJarParameter | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | main_class | 否 | String | **参数解释**：主类名称，用于指定Spark Jar作业的入口类。 **约束限制**：不涉及。 **取值范围**：长度为1\~512个字符。 **默认取值**：不涉及。 | | main_args | 否 | Array of strings | **参数解释**：主类参数列表，用于传递给Spark Jar作业入口类的参数。多个参数之间空格分隔。 **约束限制**：参数数量不能超过100个。 | | main_jar | 否 | String | **参数解释**：主Jar包路径，用于指定Spark Jar作业主类所在Jar包的OBS路径。当作业类型为"spark_jar_job"时，此参数必填。 **约束限制**：不涉及。 **取值范围**：长度为1\~512个字符，格式为OBS路径，例如："obs://bucket_name/path/to/jar.jar"。 **默认取值**：不涉及。 | | dependency_jars | 否 | Array of strings | **参数解释**：依赖Jar包列表，用于指定Spark作业依赖的Jar包OBS路径。 **约束限制**：依赖Jar包数量不能超过100个。 | | dependency_files | 否 | Array of strings | **参数解释**：依赖文件列表，用于指定Spark作业依赖的文件OBS路径。 **约束限制**：依赖文件数量不能超过100个。 | | dependency_archives | 否 | Array of strings | **参数解释**：依赖归档包列表，用于指定Spark作业依赖的归档包OBS路径。 **约束限制**：依赖归档包数量不能超过100个。 | | dependency_py_files | 否 | Array of strings | **参数解释**：依赖Python文件列表，用于指定Spark作业依赖的Python包OBS路径。 **约束限制**：依赖Python文件数量不能超过100个。 | 表5SparkPyParameter | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | main_python_file | 是 | String | **参数解释**：主Python文件路径，用于指定Python Spark作业的主文件OBS路径。 **约束限制**：不涉及。 **取值范围**：长度为1\~512个字符，格式为OBS路径，例如："obs://bucket/pyspark/pySpark_udf_python.py"。 **默认取值**：不涉及。 | | main_args | 否 | Array of strings | **参数解释**：主类参数列表，用于传递给Python Spark作业的参数。多个参数之间空格分隔。 **约束限制**：参数数量不能超过100个。 | | dependency_jars | 否 | Array of strings | **参数解释**：依赖Jar包列表，用于指定Spark作业依赖的Jar包OBS路径。 **约束限制**：依赖Jar包数量不能超过100个。 | | dependency_files | 否 | Array of strings | **参数解释**：依赖文件列表，用于指定Spark作业依赖的文件OBS路径。 **约束限制**：依赖文件数量不能超过100个。 | | dependency_archives | 否 | Array of strings | **参数解释**：依赖归档包列表，用于指定Spark作业依赖的归档包OBS路径。 **约束限制**：依赖归档包数量不能超过100个。 | | dependency_py_files | 否 | Array of strings | **参数解释**：依赖Python文件列表，用于指定Spark作业依赖的Python包OBS路径。 **约束限制**：依赖Python文件数量不能超过100个。 | 表6SparkSqlScriptParameter | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | sql_scripting_file | 是 | String | **参数解释**：SQL脚本文件路径，用于指定Spark Script SQL作业的脚本文件OBS路径。 **约束限制**：不涉及。 **取值范围**：长度为1\~512个字符，格式为OBS路径，例如："obs://bucket/sparksqlscript/script.sql"。 **默认取值**：不涉及。 | | sql_scripting_parameters | 否 | Array of [SparkJobSqlScriptParameter] objects | **参数解释**：SQL脚本占位符参数列表，用于配置SQL脚本中的参数化变量。数组中的每个元素为SparkJobSqlScriptParameter对象，包含占位符的键、值和类型信息。 **约束限制**：占位符参数数量不能超过16条。 | | dependency_jars | 否 | Array of strings | **参数解释**：依赖Jar包列表，用于指定Spark作业依赖的Jar包OBS路径。 **约束限制**：依赖Jar包数量不能超过100个。 | | sql_scripting_result_to_obs | 否 | Boolean | **参数解释**：结果写入OBS标识，用于控制SQL脚本作业的执行结果是否写入OBS。 **约束限制**：不涉及。 **取值范围**： - true：结果写入OBS。 - false：结果不写入OBS。 **默认取值**：不涉及。 | 表7SparkJobSqlScriptParameter | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | key | 是 | String | **参数解释**：占位符的键，用于标识SQL脚本中的参数名称。 **取值范围**：长度为1\~128个字符。 | | value | 是 | String | **参数解释**：占位符的值，用于传递给SQL脚本的实际参数值。不同类型的数据格式如下： - STRING：字符串，例如："xxx"。 - DECIMAL：定点数，例如："12.1"。 - INTEGER：整数，例如："13"。 - DATE：日期时间戳，例如："1779188276372"。 - TIMESTAMP：时间戳，例如："1779188276372"。 **取值范围**：长度为1\~512个字符。 | | value_type | 否 | String | **参数解释**：占位符类型，用于标识占位符值的数据类型。 **约束限制**：不涉及。 **取值范围**： - STRING：字符串类型。 - DECIMAL：定点数类型。 - INTEGER：整型类型。 - DATE：日期类型。 - TIMESTAMP：时间类型。 **默认取值**：STRING。 | 表8SparkResourceConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | driver_resource_spec | 否 | [ResourceSpec] object | **参数解释**：Driver资源规格，用于配置Driver的CPU、内存、磁盘等资源。 **约束限制**：不涉及。 | | executor_number | 否 | Integer | **参数解释**：Executor数量，用于指定Spark作业的最大Executor个数。如果配置此参数，则表示启用动态资源分配，动态资源分配最小Executor数为1，初始Executor数为1，最大Executor数为配置值。 **约束限制**：不涉及。 **取值范围**：0\~65535。 **默认取值**：不涉及。 | | executor_resource_spec | 否 | [ResourceSpec] object | **参数解释**：Executor资源规格，用于配置Executor的CPU、内存、磁盘等资源。 **约束限制**：不涉及。 | 表9ResourceSpec | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | cpu | 否 | Integer | **参数解释**：CPU核数，单位为毫核，用于指定作业运行所需的CPU资源。 **约束限制**：不涉及。 **取值范围**：最小值为1000，最大值为64000。 **默认取值**：1000。 | | memory | 否 | Integer | **参数解释**：内存大小，单位为MB，用于指定作业运行所需的内存资源。 **约束限制**：不涉及。 **取值范围**：最小值为1024，最大值为524288。 **默认取值**：4096。 | | disk | 否 | Integer | **参数解释**：本地磁盘大小，用于指定Spark作业Driver和Executor的本地磁盘资源。 **约束限制**：不涉及。 **取值范围**：单位为GB，最小值为0，最大值为994。 **默认取值**：不涉及。 | 表10SparkJobImageConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | image_id | 是 | String | **参数解释**：镜像ID，用于指定Spark作业运行所需的镜像。 **约束限制**：不涉及。 **取值范围**：长度为2\~64个字符。 **默认取值**：不涉及。 | | image_version_id | 是 | String | **参数解释**：镜像版本，用于指定Spark作业运行所需的镜像版本。 **约束限制**：不涉及。 **取值范围**：长度为2\~64个字符。 **默认取值**：不涉及。 | 表11SparkLoggingConfig | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | driver_root_logger_level | 否 | String | **参数解释**：Driver根日志级别，用于控制Driver输出的整体日志级别。 **约束限制**：不涉及。 | | driver_loggers_level_of_class | 否 | Array of [SparkClassLoggerLevel] objects | **参数解释**：Driver类级别日志配置列表，用于配置指定类的日志级别。数组中的每个元素为SparkClassLoggerLevel对象，包含类名和日志级别。 **约束限制**：最多配置20个类的日志级别。 | | executor_root_logger_level | 否 | String | **参数解释**：Executor根日志级别，用于控制Executor输出的整体日志级别。 **约束限制**：不涉及。 | | executor_loggers_level_of_class | 否 | Array of [SparkClassLoggerLevel] objects | **参数解释**：Executor类级别日志配置列表，用于配置指定类的日志级别。数组中的每个元素为SparkClassLoggerLevel对象，包含类名和日志级别。 **约束限制**：最多配置20个类的日志级别。 | 表12SparkClassLoggerLevel | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | logger_name | 否 | String | **参数解释**：日志类名称，用于指定需要配置日志级别的类名。 **约束限制**：不涉及。 **取值范围**：长度为1\~256个字符。 **默认取值**：不涉及。 | | logger_level | 否 | String | **参数解释**：日志级别，用于控制该类的日志输出详细程度。 **约束限制**：不涉及。 | 表13SparkRestoreStrategy | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | max_retry | 否 | Integer | **参数解释**：最大重试次数，用于控制作业失败后的自动重试次数。如果配置的值大于0，则自动开启失败重试；如果不配置或者配置为0，则不开启作业失败重试。 **约束限制**：不涉及。 **取值范围**：0\~65535。 **默认取值**：0。 | | retry_delay | 否 | Integer | **参数解释**：重试间隔时间，用于指定作业失败重试机制中每次重试的时间间隔，单位为秒。 **约束限制**：不涉及。 **取值范围**：1\~3600。 **默认取值**：30。 | | queued_timeout | 否 | Integer | **参数解释**：排队超时时间，用于指定作业提交后等待运行的最长时间，单位为分钟。如果超过此时间作业仍未运行，则作业失败。 **约束限制**：不涉及。 **取值范围**：10\~180。 **默认取值**：180。 | | running_timeout | 否 | Integer | **参数解释**：运行超时时间，用于指定作业运行的最大时长，单位为分钟。如果超过此时间作业还未运行结束，则作业会取消运行并标记为运行超时。 **约束限制**：不涉及。 **取值范围**：10\~525600。 **默认取值**：不涉及。 | 表14SparkJobLabel | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | key | 是 | String | **参数解释**：标签键，用于标识标签的唯一键名。 **约束限制**：不涉及。 **取值范围**：长度为1\~128个字符。 **默认取值**：不涉及。 | | value | 是 | String | **参数解释**：标签值，用于标识标签的具体值。 **约束限制**：不涉及。 **取值范围**：长度为1\~512个字符。 **默认取值**：不涉及。 | #### 响应参数 **状态码：201** 表15响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | job_id | String | **参数解释**：Spark作业ID，用于唯一标识本次启动的Spark作业。 **取值范围**：只能由十六进制字符、中划线及下划线组成，长度为1\~64个字符，例如：1ee7d9db-90ec-4b71-89b8-0de936dade77。 | **状态码：400** 表16响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**：错误码，用于标识具体的错误类型。 **取值范围**：长度为0\~64个字符。 | | error_msg | String | **参数解释**：错误描述信息，用于说明错误原因。 **取值范围**：长度为0\~512个字符。 | | solution_msg | String | **参数解释**：解决方案描述。 **取值范围**：长度为0\~4096个字符。 | **状态码：401** 表17响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**：错误码，用于标识具体的错误类型。 **取值范围**：长度为0\~64个字符。 | | error_msg | String | **参数解释**：错误描述信息，用于说明错误原因。 **取值范围**：长度为0\~512个字符。 | | solution_msg | String | **参数解释**：解决方案描述。 **取值范围**：长度为0\~4096个字符。 | **状态码：403** 表18响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**：错误码，用于标识具体的错误类型。 **取值范围**：长度为0\~64个字符。 | | error_msg | String | **参数解释**：错误描述信息，用于说明错误原因。 **取值范围**：长度为0\~512个字符。 | | solution_msg | String | **参数解释**：解决方案描述。 **取值范围**：长度为0\~4096个字符。 | **状态码：500** 表19响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | - | String | 错误信息。 | #### 请求示例 - 启动Spark Jar作业，其名称为"spark-jar-job-example"，端点名称为"spark-endpoint"，作业类型为"spark_jar_job"，Jar路径为"obs://bucket/path/job.jar"，入口参数为"--input obs://bucket/input --output obs://bucket/output"，执行器数量为"2"，Driver资源为"2核4GB"，Executor资源为"2核4GB"。 ``` POST /v2/workspaces/{workspace_id}/spark-jobs { "name" : "spark-jar-job-example", "endpoint_name" : "spark-endpoint", "job_config" : { "type" : "spark_jar_job", "main_class" : "com.example.SparkJobDriver", "main_jar" : "obs://bucket/path/job.jar", "main_args" : [ "--input", "obs://bucket/input", "--output", "obs://bucket/output" ] }, "resource_config" : { "executor_number" : 2, "driver_resource_spec" : { "cpu" : 2000, "memory" : 4096 }, "executor_resource_spec" : { "cpu" : 2000, "memory" : 4096 } } } ``` - 启动Python作业，其名称为"python-job-example"，端点名称为"spark-endpoint"，作业类型为"spark_python_job"，Python路径为"obs://bucket/path/job.py"，入口参数为"--input-path obs://bucket/input"，执行器数量为"2"，Driver资源为"2核4GB"，Executor资源为"2核4GB"。 ``` POST /v2/workspaces/{workspace_id}/spark-jobs { "name" : "python-job-example", "endpoint_name" : "spark-endpoint", "job_config" : { "type" : "spark_python_job", "main_python_file" : "obs://bucket/path/job.py", "main_args" : [ "--input-path", "obs://bucket/input" ] }, "resource_config" : { "executor_number" : 2, "driver_resource_spec" : { "cpu" : 2000, "memory" : 4096 }, "executor_resource_spec" : { "cpu" : 2000, "memory" : 4096 } } } ``` #### 响应示例 **状态码：201** 启动成功。 ``` { "job_id" : "1ee7d9db-90ec-4b71-89b8-0de936dade77" } ``` **状态码：400** 请求参数错误。 ``` { "error_code" : "AIDataLake.01011001", "error_msg" : "Invalid parameter main_jar", "solution_msg" : "Please check the input parameters according to the documentation(main_jar for jar job)." } ``` **状态码：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." } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 201 | 启动成功。 | | 400 | 请求参数错误。 | | 401 | 认证失败。 | | 403 | 权限不足。 | | 500 | 服务内部错误。 |