查询Spark作业列表 - ListSparkJobs

功能介绍

查询工作空间下Spark作业列表，此接口为同步接口。支持按作业ID、作业名称、作业状态、作业类型、创建时间等条件过滤查询，支持分页查询，调用成功后直接返回作业列表数据。

调用方法

URI

GET /v2/workspaces/{workspace_id}/spark-jobs

表1 路径参数
参数	是否必选	参数类型	描述
workspace_id	是	String	参数解释：工作空间ID，用于资源隔离。可在控制台的工作空间管理页面查看。约束限制：不涉及。取值范围：只能由英文字母、数字及中划线组成，且长度为32~36个字符。默认取值：不涉及。

表2 Query参数
参数	是否必选	参数类型	描述
marker	否	String	参数解释：作业ID游标位置，用于分页查询。约束限制：首次查询可不传或传空字符串，后续查询传入上次返回的next_marker值。取值范围：采用UUID格式，长度为36个字符，只能由英文大写字母、英文小写字母、数字及下划线和横线组成。默认取值：不涉及。
limit	否	Integer	参数解释：查询记录数，用于分页查询。约束限制：不涉及。取值范围：1~100之间的整数。默认取值：10。
name	否	String	参数解释：作业名称，用于模糊查询作业。约束限制：不涉及。取值范围：长度为0~128个字符。默认取值：不涉及。
create_time_after	否	Long	参数解释：用于查询创建时间在该时间点之后的作业。约束限制：不涉及。取值范围：unix时间戳，单位为毫秒，最小值为1764061598000。默认取值：不涉及。
create_time_before	否	Long	参数解释：用于查询创建时间在该时间点之前的作业。约束限制：不涉及。取值范围：unix时间戳，单位为毫秒，最小值为1764061598000。默认取值：不涉及。
endpoint_name	否	String	参数解释：端点名称，用于指定Spark作业执行环境。约束限制：不涉及。取值范围：只能由英文小写字母、数字及中划线组成，以英文小写字母开头，以英文小写字母或数字结尾，且长度为1~63个字符。默认取值：不涉及。
states	否	Array of strings	参数解释：Spark作业状态列表，用于过滤查询指定状态的作业。约束限制：最多支持查询10种状态。取值范围： PENDING：启动中。 QUEUED：排队中。 RUNNING：运行中。 CANCELING：取消中。 CANCELED：已取消。 FAILED：运行失败。 SUCCEED：运行成功。 QUEUED_TIMEOUT：排队超时。 RUNNING_TIMEOUT：运行超时。
job_type	否	String	参数解释：作业类型，用于过滤查询指定类型的作业。约束限制：不涉及。取值范围： spark_jar_job：Spark jar作业。 spark_python_job：Python Spark作业。 spark_sql_scripting_job：SQL脚本作业（预留类型）。默认取值：不涉及。
job_id	否	String	参数解释：Spark作业ID，用于精确查询指定作业。约束限制：不涉及。取值范围：只能由英文大写字母、英文小写字母、数字及下划线和横线组成，且长度为1~64个字符。默认取值：不涉及。
create_user_id	否	String	参数解释：Spark作业创建者ID，用于过滤查询指定用户创建的作业。约束限制：不涉及。取值范围：长度为1~256个字符。默认取值：不涉及。
labels	否	String	参数解释：作业标签，用于按标签过滤查询作业。支持多标签过滤，格式为“key=value”，多个标签用逗号分隔。约束限制：URL中“=”需要转义为“%3D”。例如：labels=k1%3Dv1，k2%3Dv2。取值范围：长度为1~1024个字符。默认取值：不涉及。

请求参数

表3 请求Header参数
参数	是否必选	参数类型	描述
X-Auth-Token	是	String	参数解释：用户Token。约束限制：不涉及。取值范围：长度不超过65534个字符。默认取值：不涉及。

响应参数

状态码：200

表4 响应Body参数
参数	参数类型	描述
page_info	SparkMarkerPageInfo object	参数解释：分页信息，包含下一页游标和当前页记录数。
jobs	Array of ListSparkJobResponseDto objects	参数解释：Spark作业列表，包含作业详细信息。

表5 SparkMarkerPageInfo
参数	参数类型	描述
next_marker	String	参数解释：下一页游标，用于标识下一页数据的起始位置。为空表示没有更多数据。取值范围：采用UUID格式，长度为36个字符，例如：6c98db52-cac2-4ff1-9a91-b7793e95557d。
current_count	Integer	参数解释：当前页数据条数，用于标识当前返回的数据数量。取值范围：大于等于0的整数，最大不超过100。

表6 ListSparkJobResponseDto
参数	参数类型	描述
job_id	String	参数解释：Spark作业ID，用于唯一标识该作业。取值范围：采用UUID格式，长度为36个字符，例如：80ceaaff-3cfc-4162-a56f-70031ea4fa91。
client_token	String	参数解释：Spark作业事务ID，用于防止重复提交。取值范围：采用UUID格式，长度为36个字符，例如：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx。
name	String	参数解释：Spark作业名称，用于标识作业。取值范围：长度为1~128个字符。
endpoint_name	String	参数解释：端点名称，用于指定Spark作业执行环境。取值范围：只能由英文小写字母、数字及中划线组成，以英文小写字母开头，以英文小写字母或数字结尾，且长度为1~63个字符。
job_type	String	参数解释：作业类型，用于标识作业的类型。取值范围： spark_jar_job：Spark jar作业。 spark_python_job：Python Spark作业。 spark_sql_scripting_job：SQL脚本作业（预留类型）。
state	String	参数解释：Spark作业状态，用于标识作业当前执行状态。取值范围： PENDING：启动中。 QUEUED：排队中。 RUNNING：运行中。 CANCELING：取消中。 CANCELED：已取消。 FAILED：运行失败。 SUCCEED：运行成功。 QUEUED_TIMEOUT：排队超时。 RUNNING_TIMEOUT：运行超时。
state_message	String	参数解释：作业状态消息，当作业异常结束时显示相关信息。取值范围：长度为0~512个字符。
retry_times	Integer	参数解释：作业重试次数，用于记录作业失败后的重试次数。取值范围：最小值为0。
create_time	Long	参数解释：作业创建时间，用于记录作业提交时间。取值范围：unix时间戳，单位为毫秒。
start_time	Long	参数解释：作业开始运行时间，用于记录作业实际开始执行的时间。取值范围：unix时间戳，单位为毫秒。
end_time	Long	参数解释：作业结束时间，用于记录作业执行完成的时间。取值范围：unix时间戳，单位为毫秒。
create_user	SparkCreateUser object	参数解释：创建作业的用户信息。
log_url	String	参数解释：日志归档路径OBS URL，用于查看作业执行日志。取值范围：OBS URL格式，长度为1~1024个字符。

表7 SparkCreateUser
参数	参数类型	描述
user_id	String	参数解释：创建作业的用户ID，用于标识作业创建者。取值范围：长度为1~256个字符。
user_name	String	参数解释：创建作业的用户名称，用于标识作业创建者。取值范围：长度为1~256个字符。

状态码：400

表8 响应Body参数
参数	参数类型	描述
error_code	String	参数解释：错误码，用于标识具体的错误类型。取值范围：长度为0~64个字符。
error_msg	String	参数解释：错误描述信息，用于说明错误原因。取值范围：长度为0~512个字符。
solution_msg	String	参数解释：解决方案描述。取值范围：长度为0~4096个字符。

状态码：401

表9 响应Body参数
参数	参数类型	描述
error_code	String	参数解释：错误码，用于标识具体的错误类型。取值范围：长度为0~64个字符。
error_msg	String	参数解释：错误描述信息，用于说明错误原因。取值范围：长度为0~512个字符。
solution_msg	String	参数解释：解决方案描述。取值范围：长度为0~4096个字符。

状态码：403

**表10** 响应Body参数
参数	参数类型	描述
error_code	String	参数解释：错误码，用于标识具体的错误类型。取值范围：长度为0~64个字符。
error_msg	String	参数解释：错误描述信息，用于说明错误原因。取值范围：长度为0~512个字符。
solution_msg	String	参数解释：解决方案描述。取值范围：长度为0~4096个字符。

状态码：500

**表11** 响应Body参数
参数	参数类型	描述
-	String	错误信息。

请求示例

按作业状态过滤查询处于已成功(“SUCCEED”)状态的Spark作业，每页查询2条。

GET /v2/workspaces/{workspace_id}/spark-jobs?limit=2&states=SUCCEED

响应示例

状态码：200

查询Spark作业列表成功。

{
  "page_info" : {
    "next_marker" : "1ee7d9db-90ec-4b71-89b8-0de936dade77",
    "current_count" : 2
  },
  "jobs" : [ {
    "job_id" : "80ceaaff-3cfc-4162-a56f-70031ea4fa91",
    "client_token" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "name" : "spark-job-example",
    "endpoint_name" : "my-spark-endpoint",
    "state" : "SUCCEED",
    "job_type" : "spark_jar_job",
    "retry_times" : 1,
    "create_time" : 1698776400000,
    "start_time" : 1698776450000,
    "end_time" : 1698776700000,
    "create_user" : {
      "user_id" : "user123",
      "user_name" : "admin"
    },
    "log_url" : "https://obs.example.com/logs/spark-job.log"
  }, {
    "job_id" : "1ee7d9db-90ec-4b71-89b8-0de936dade77",
    "client_token" : "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
    "name" : "spark-python-job",
    "endpoint_name" : "my-spark-endpoint",
    "state" : "SUCCEED",
    "job_type" : "spark_python_job",
    "retry_times" : 1,
    "create_time" : 1698776500000,
    "start_time" : 1698776550000,
    "end_time" : 1698776700000,
    "create_user" : {
      "user_id" : "user456",
      "user_name" : "developer"
    },
    "log_url" : "https://obs.example.com/logs/spark-python-job.log"
  } ]
}

状态码：400

请求参数错误。

{
  "error_code" : "AIDataLake.01011001",
  "error_msg" : "Invalid parameter name",
  "solution_msg" : "Please check the input parameters according to the documentation(name for spark 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."
}