文档首页/数据湖探索 DLI/API参考/Spark作业相关API/创建批处理作业
更新时间：2025-12-30 GMT+08:00
在线调试
CLI示例
查看PDF
分享

创建批处理作业

功能介绍

该API用于在某个队列上创建批处理作业。

在Spark作业提交过程中，若长时间未能成功获取资源，作业状态将在持续等待3小时左右转变为“dead”状态。Spark作业状态请参考表7。

授权信息

账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。

  • 如果使用角色与策略授权，具体权限要求请参见权限及授权项说明。
  • 如果使用身份策略授权，需具备如下身份策略权限。

    授权项

    Action

    访问级别

    Access Level

    资源类型（*为必须）

    Resource Type (*: required)

    条件键

    Condition Key

    别名

    Alias

    依赖的授权项

    Dependencies

    dli:queue:submitJob

    write

    queue *

    -

    dli:catalog:get: 访问外部catalog（当使用外部catalog时）

    iam:agencies:pass: 使用委托权限（当配置了agency时）

URI

  • URI格式：

    POST /v2.0/{project_id}/batches

  • 参数说明
    表1 URI参数

    参数名称

    是否必选

    参数类型

    说明

    project_id

    是

    String

    参数解释：

    项目编号，用于资源隔离。获取方式请参考获取项目ID。

    示例: 48cc2c48765f481480c7db940d6409d1

    约束限制：

    无

    取值范围：

    只能由英文字母和数字组成，且长度为[1-64]个字符。

    默认取值：

    无

请求消息

表2 请求参数

参数名称

是否必选

参数类型

说明

file

是

String

参数解释：

用户已上传到DLI资源管理系统的类型为jar或pyFile的程序包名。

也支持指定OBS路径，例如：obs://桶名/包名。

约束限制：

Spark3.3.x及以上版本仅支持配置OBS路径下的程序包。

取值范围：

无

默认取值：

无

className

是

String

参数解释：

批处理作业的Java/Spark主类。

约束限制：

无

取值范围：

无

默认取值：

无

queue

否

String

参数解释：

用于指定队列，填写已创建DLI的队列名。必须为通用类型的队列。

约束限制：

  • 兼容“cluster_name”参数，即如果使用“cluster_name”指定队列仍然有效。
  • 推荐使用“queue”参数，“queue”参数与“cluster_name”两者同时存在时以“queue”参数值为准。

取值范围：

无

默认取值：

无

cluster_name

否

String

参数解释：

用于指定队列，填写已创建DLI队列的队列名称。

约束限制：

推荐使用“queue”参数，“queue”参数与“cluster_name”参数两者不能同时存在。

取值范围：

无

默认取值：

无

args

否

Array of Strings

参数解释：

传入主类的参数，即应用程序参数。

约束限制：

无

取值范围：

无

默认取值：

无

sc_type

否

String

参数解释：

计算资源类型，目前可接受参数A, B, C。如果不指定，则按最小类型创建。具体资源类型请参见表3。

约束限制：

无

取值范围：

无

默认取值：

无

jars

否

Array of Strings

参数解释：

用户已上传到DLI资源管理系统的类型为jar的程序包名。也支持指定OBS路径，例如：obs://桶名/包名。

约束限制：

无

取值范围：

无

默认取值：

无

pyFiles

否

Array of Strings

参数解释：

用户已上传到DLI资源管理系统的类型为pyFile的资源包名。也支持指定OBS路径，例如：obs://桶名/包名。

约束限制：

无

取值范围：

无

默认取值：

无

files

否

Array of Strings

参数解释：

用户已上传到DLI资源管理系统的类型为file的资源包名。也支持指定OBS路径，例如：obs://桶名/包名。

约束限制：

无

取值范围：

无

默认取值：

无

modules

否

Array of Strings

参数解释：

依赖的系统资源模块名，具体模块名可通过查询组内资源包（废弃）接口查看。

约束限制：

无

取值范围：

DLI系统提供了用于执行跨源作业的依赖模块，各个不同的服务对应的模块列表如下：
  • CloudTable/MRS HBase: sys.datasource.hbase
  • CloudTable/MRS OpenTSDB: sys.datasource.opentsdb
  • RDS MySQL: sys.datasource.rds
  • RDS PostGre: 不需要选
  • DWS: 不需要选
  • CSS: sys.datasource.css

默认取值：

无

resources

否

Array of Objects

参数解释：

JSON对象列表，填写用户已上传到队列的类型为JSON的资源包名和类型。具体请见表4。

约束限制：

Spark 3.3.x及以上版本不支持配置resources参数，请在jars、pyFiles、files中配置资源包信息。

取值范围：

无

默认取值：

无

groups

否

Array of Objects

参数解释：

JSON对象列表，填写用户组类型资源，格式详见请求示例。如果“resources”中的“name”未进行type校验，只要此分组中存在这个名字的包即可。具体请见表5。

约束限制：

Spark 3.3.x及以上版本不支持配置分组信息。

取值范围：

无

默认取值：

无

conf

否

Object

参数解释：

batch配置项，参考Spark Configuration。

约束限制：

无

取值范围：

无

默认取值：

无

name

否

String

参数解释：

创建时用户指定的批处理名称，不能超过128个字符。

约束限制：

无

取值范围：

无

默认取值：

无

driverMemory

否

String

参数解释：

Spark应用的Driver内存，参数配置例如2G, 2048M。该配置项会替换“sc_type”中对应的默认参数，使用时必须带单位，否则会启动失败。

约束限制：

无

取值范围：

无

默认取值：

无

driverCores

否

Integer

参数解释：

Spark应用Driver的CPU核数。该配置项会替换sc_type中对应的默认参数。

约束限制：

无

取值范围：

无

默认取值：

无

executorMemory

否

String

参数解释：

Spark应用的Executor内存，参数配置例如2G, 2048M。该配置项会替换“sc_type”中对应的默认参数，使用时必须带单位，否则会启动失败。

约束限制：

无

取值范围：

无

默认取值：

无

executorCores

否

Integer

参数解释：

Spark应用每个Executor的CPU核数。该配置项会替换sc_type中对应的默认参数。

约束限制：

无

取值范围：

无

默认取值：

无

numExecutors

否

Integer

参数解释：

Spark应用Executor的个数。该配置项会替换sc_type中对应的默认参数。

约束限制：

无

取值范围：

无

默认取值：

无

obs_bucket

否

String

参数解释：

保存Spark作业的obs桶名，需要保存作业时配置该参数。

约束限制：

无

取值范围：

无

默认取值：

无

auto_recovery

否

Boolean

参数解释：

是否开启重试功能，如果开启，可在Spark作业异常失败后自动重试。默认值为“false”。

约束限制：

无

取值范围：

无

默认取值：

false

max_retry_times

否

Integer

参数解释：

最大重试次数。最大值为“100”，默认值为“20”。

约束限制：

无

取值范围：

无

默认取值：

20

feature

否

String

参数解释：

作业特性。表示用户作业使用的Spark镜像类型。

约束限制：

无

取值范围：

  • custom：表示使用用户自定义的Spark镜像。

默认取值：

无

spark_version

否

String

参数解释：

作业使用Spark组件的版本号。

约束限制：

无

取值范围：

  • 如果当前Spark组件版本为2.3.2，则不填写该参数。

默认取值：

无

execution_agency_urn

否

String

参数解释：

授权给DLI的委托名。Spark3.3.1版本时支持配置该参数。

约束限制：

无

取值范围：

无

默认取值：

无

image

否

String

参数解释：

自定义镜像。格式为：组织名/镜像名:镜像版本。

约束限制：

当用户设置“feature”为“custom”时，该参数生效。用户可通过与“feature”参数配合使用，指定作业运行使用自定义的Spark镜像。关于如何使用自定义镜像，请参考《数据湖探索用户指南》。

取值范围：

无

默认取值：

无

catalog_name

否

String

参数解释：

访问元数据时，需要将该参数配置为dli。

约束限制：

无

取值范围：

无

默认取值：

无

表3 资源类型说明

资源类型

物理资源

driverCores

executorCores

driverMemory

executorMemory

numExecutor

A

8核32G内存

2

1

7G

4G

6

B

16核64G内存

2

2

7G

8G

7

C

32核128G内存

4

2

15G

8G

14

表4 resources参数说明

参数名称

是否必选

参数类型

说明

name

否

String

参数解释：

资源名称。也支持指定OBS路径，例如：obs://桶名/包名。

约束限制：

无

取值范围：

无

默认取值：

无

type

否

String

参数解释：

资源类型。

约束限制：

无

取值范围：

无

默认取值：

无

表5 groups参数说明

参数名称

是否必选

参数类型

说明

name

否

String

参数解释：

用户组名称。

约束限制：

无

取值范围：

无

默认取值：

无

resources

否

Array of Objects

参数解释：

用户组资源。具体请参考表4。

约束限制：

无

取值范围：

无

默认取值：

无

响应消息

表6 响应参数

参数名称

是否必选

参数类型

说明

id

否

String

参数解释：

批处理作业的ID。

取值范围：

无

appId

否

String

参数解释：

批处理作业的后台app ID。

取值范围：

无

name

否

String

参数解释：

创建时用户指定的批处理名称，不能超过128个字符。

取值范围：

无

owner

否

String

参数解释：

批处理作业所属用户。

取值范围：

无

proxyUser

否

String

参数解释：

批处理作业所属代理用户（资源租户）。

取值范围：

无

state

否

String

参数解释：

批处理作业的状态，详细说明请参见表7。

取值范围：

无

kind

否

String

参数解释：

批处理作业类型，只支持spark类型参数。

取值范围：

无

log

否

Array of strings

参数解释：

显示当前批处理作业的最后10条记录。

取值范围：

无

sc_type

否

String

参数解释：

计算资源类型。目前可接受参数A, B, C。用户自定义时返回CUSTOMIZED。

取值范围：

  • A：物理资源：8核32G内存，
    • driverCores：2；
    • executorCores：1；
    • driverMemory：7G；
    • executorMemory：4G；
    • numExecutor：6。
  • B：物理资源：16核64G内存
    • driverCores：2；
    • executorCores：2；
    • driverMemory：7G；
    • executorMemory：8G；
    • numExecutor：7。
  • C：物理资源：32核128G内存
    • driverCores：4；
    • executorCores：2；
    • driverMemory：15G；
    • executorMemory：8G；
    • numExecutor：14。

cluster_name

否

String

参数解释：

批处理作业所在队列。

取值范围：

无

queue

是

String

参数解释：

用于指定队列，填写已创建DLI的队列名。

  • 兼容“cluster_name”参数，即如果使用“cluster_name”指定队列仍然有效。
  • 推荐使用“queue”参数，“queue”参数与“cluster_name”参数两者不能同时存在。

取值范围：

无

image

否

String

参数解释：

自定义镜像。格式为：组织名/镜像名:镜像版本。

取值范围：

当用户设置“feature”为“custom”时，该参数生效。用户可通过与“feature”参数配合使用，指定作业运行使用自定义的Spark镜像。关于如何使用自定义镜像，请参考《数据湖探索用户指南》。

create_time

否

Long

参数解释：

批处理作业的创建时间。是单位为“毫秒”的时间戳。

取值范围：

无

update_time

否

Long

参数解释：

批处理作业的更新时间。是单位为“毫秒”的时间戳。

取值范围：

无

duration

否

Long

参数解释：

作业运行时长，单位毫秒。

取值范围：

无

表7 批处理作业状态说明

参数名称

参数类型

说明

starting

String

批处理作业正在启动。

running

String

批处理作业正在执行任务。

dead

String

批处理作业已退出。

success

String

批处理作业执行成功。

recovering

String

批处理作业正在恢复。

请求示例

创建Spark作业，作业的Spark主类为“org.apache.spark.examples.SparkPi”，指定程序包batchTest/spark-examples_2.11-2.1.0.luxor.jar，并加载上传到DLI类型为jar的程序号和类型为files的资源包。

{
    "file": "batchTest/spark-examples_2.11-2.1.0.luxor.jar",
    "className": "org.apache.spark.examples.SparkPi",
    "sc_type": "A",
    "jars": ["demo-1.0.0.jar"],
    "files": ["count.txt"],
    "resources":[
                   {"name": "groupTest/testJar.jar", "type": "jar"},
                   {"name": "kafka-clients-0.10.0.0.jar", "type": "jar"}],
    "groups": [
                   {"name": "groupTestJar", "resources": [{"name": "testJar.jar", "type": "jar"}, {"name": "testJar1.jar", "type": "jar"}]}, 
                   {"name": "batchTest", "resources":  [{"name": "luxor.jar", "type": "jar"}]}],
    "queue": " test",
    "name": "TestDemo4",
    "feature": "basic",
    "execution_agency_urn": "myAgencyName",
    "spark_version": "2.3.2"
}

其中“batchTest/spark-examples_2.11-2.1.0.luxor.jar”已提前通过上传分组资源（废弃）接口上传。

响应示例

{
  "id": "07a3e4e6-9a28-4e92-8d3f-9c538621a166",
  "appId": "",
  "name": "",
  "owner": "test1",
  "proxyUser": "",
  "state": "starting",
  "kind": "",
  "log": [],
  "sc_type": "CUSTOMIZED",
  "cluster_name": "aaa",
  "queue": "aaa",  "create_time": 1607589874156,
  "update_time": 1607589874156
}

状态码

状态码如表8所示。

表8 状态码

状态码

描述

200

创建成功。

400

请求错误。

500

内部服务器错误。

错误码

调用接口出错后，将不会返回上述结果，而是返回错误码和错误信息，更多介绍请参见错误码。