启动Spark作业 - RunSparkJob

功能介绍

启动Spark作业，此接口为异步接口。支持Spark Jar作业、Python作业和SQL Script作业。调用该接口后，作业将提交到队列等待执行，返回作业ID后需通过查询作业状态接口确认作业是否成功启动。查询作业状态请参见查询Spark作业的状态。

调用方法

请参见如何调用API。

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<String,String>	参数解释：用户自定义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个字符。默认取值：不涉及。

表4 SparkJarParameter
参数	是否必选	参数类型	描述
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个。

表5 SparkPyParameter
参数	是否必选	参数类型	描述
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个。

表6 SparkSqlScriptParameter
参数	是否必选	参数类型	描述
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。默认取值：不涉及。

表7 SparkJobSqlScriptParameter
参数	是否必选	参数类型	描述
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。

表8 SparkResourceConfig
参数	是否必选	参数类型	描述
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、内存、磁盘等资源。约束限制：不涉及。

表9 ResourceSpec
参数	是否必选	参数类型	描述
cpu	否	Integer	参数解释：CPU核数，单位为毫核，用于指定作业运行所需的CPU资源。约束限制：不涉及。取值范围：最小值为1000，最大值为64000。默认取值：1000。
memory	否	Integer	参数解释：内存大小，单位为MB，用于指定作业运行所需的内存资源。约束限制：不涉及。取值范围：最小值为1024，最大值为524288。默认取值：4096。
disk	否	Integer	参数解释：本地磁盘大小，用于指定Spark作业Driver和Executor的本地磁盘资源。约束限制：不涉及。取值范围：单位为GB，最小值为0，最大值为994。默认取值：不涉及。

**表10** SparkJobImageConfig
参数	是否必选	参数类型	描述
image_id	是	String	参数解释：镜像ID，用于指定Spark作业运行所需的镜像。约束限制：不涉及。取值范围：长度为2~64个字符。默认取值：不涉及。
image_version_id	是	String	参数解释：镜像版本，用于指定Spark作业运行所需的镜像版本。约束限制：不涉及。取值范围：长度为2~64个字符。默认取值：不涉及。

**表11** SparkLoggingConfig
参数	是否必选	参数类型	描述
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个类的日志级别。

**表12** SparkClassLoggerLevel
参数	是否必选	参数类型	描述
logger_name	否	String	参数解释：日志类名称，用于指定需要配置日志级别的类名。约束限制：不涉及。取值范围：长度为1~256个字符。默认取值：不涉及。
logger_level	否	String	参数解释：日志级别，用于控制该类的日志输出详细程度。约束限制：不涉及。

**表13** SparkRestoreStrategy
参数	是否必选	参数类型	描述
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。默认取值：不涉及。

**表14** SparkJobLabel
参数	是否必选	参数类型	描述
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."
}