# 查询SparkSql作业列表 - ListSparkSqls #### 功能介绍 查询工作空间下SparkSql作业列表，此接口为同步接口。支持按作业状态、创建时间、SQL片段等条件进行过滤查询，调用成功后直接返回作业列表数据。可通过[查看SparkSql作业详情](https://support.huaweicloud.com/api-aidatalake/ShowSparkSql.html)接口查看作业详细信息。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-aidatalake/aidatalake_02_0003.html)。 #### URI GET /v2/workspaces/{workspace_id}/spark-sqls 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | workspace_id | 是 | String | **参数解释**：工作空间ID，用于资源隔离。可在控制台的工作空间页面查看。 **约束限制**：不涉及。 **取值范围**：只能由英文字母、数字及中划线组成，且长度为32\~36个字符。 **默认取值**：不涉及。 | 表2Query参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | marker | 否 | String | **参数解释**：作业ID游标位置，用于分页查询。 **约束限制**：不涉及。 **取值范围**：采用UUID格式，长度为36个字符。 **默认取值**：首次查询可不传或传空字符串，后续查询传入上次返回的next_marker值。 | | limit | 否 | Integer | **参数解释**：查询记录数，用于指定返回的作业数量。 **约束限制**：不涉及。 **取值范围**：1\~100。 **默认取值**：10。 | | page_reverse | 否 | Boolean | **参数解释**：是否反向分页查询。默认为false，表示正向分页查询。 当设置为true时，表示查询上一页数据，需要配合marker参数使用。 | | endpoint_name | 否 | String | **参数解释**：端点名称，用于指定查询的SparkSql执行环境。 **约束限制**：不涉及。 **取值范围**：只能由英文小写字母、数字及中划线组成，以英文小写字母开头，以英文小写字母或数字结尾，且长度为1\~63个字符。 **默认取值**：不涉及。 | | statement | 否 | String | **参数解释**：SQL片段，用于模糊查询包含指定SQL片段的作业。 **约束限制**：不涉及。 **取值范围**：长度为1\~128个字符。 **默认取值**：不涉及。 | | create_time_after | 否 | Long | **参数解释**：用于查询创建时间在该时间点之后的作业。 **约束限制**：不涉及。 **取值范围**：采用unix时间戳格式，单位为毫秒，最小值为1764061598000。 **默认取值**：不涉及。 | | create_time_before | 否 | Long | **参数解释**：用于查询创建时间在该时间点之前的作业。 **约束限制**：不涉及。 **取值范围**：采用unix时间戳格式，单位为毫秒，最小值为1764061598000。 **默认取值**：不涉及。 | | states | 否 | Array of strings | **参数解释**：SparkSql作业的状态列表，用于按状态过滤作业。 **约束限制**：数组元素数量不能超过10个。 | | statement_types | 否 | Array of strings | **参数解释**：作业类型列表，用于按作业类型过滤作业。 **约束限制**：数组元素数量不能超过4个。 | | statement_id | 否 | String | **参数解释**：SparkSql作业ID，用于查询指定作业。 **约束限制**：不涉及。 **取值范围**：只能由英文字母（不区分大小写）、数字、下划线及中划线组成，且长度为1\~64个字符。 **默认取值**：不涉及。 | | create_user_id | 否 | String | **参数解释**：作业创建者ID，用于按创建者过滤作业。 **约束限制**：不涉及。 **取值范围**：长度为1\~256个字符。 **默认取值**：不涉及。 | | create_user_name | 否 | String | **参数解释**：作业创建者名称，用于按创建者精确过滤作业。 **约束限制**：不涉及。 **取值范围**：长度为1\~256个字符。 **默认取值**：不涉及。 | | labels | 否 | String | **参数解释**：作业标签，用于按标签过滤作业。格式为"key=value"，其中"="需要URL编码为"%3D"。 **约束限制**：不涉及。 **取值范围**：长度为1\~1024个字符。 **默认取值**：不涉及。 | #### 请求参数 表3请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Auth-Token | 是 | String | **参数解释**：用户Token。 **约束限制**：不涉及。 **取值范围**：长度不超过65534个字符。 **默认取值**：不涉及。 | #### 响应参数 **状态码：200** 表4响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | page_info | [SparkMarkerPageInfo] object | **参数解释**：分页游标信息，用于标识分页查询的位置和数量。 | | statements | Array of [ListSparkSqlResItem] objects | **参数解释**：详细的SparkSql作业列表，包含作业ID、状态、SQL内容等信息。 | 表5SparkMarkerPageInfo | 参数 | 参数类型 | 描述 | |:---|:---|:---| | next_marker | String | **参数解释**：下一页游标，用于标识下一页数据的起始位置。为空表示没有更多数据。 **取值范围**：采用UUID格式，长度为36个字符，例如：6c98db52-cac2-4ff1-9a91-b7793e95557d。 | | previous_marker | String | **参数解释**：上一页游标，用于标识上一页数据的起始位置。为空表示当前页是第一页。 **取值范围**：采用UUID格式，长度为36个字符。 | | current_count | Integer | **参数解释**：当前页数据条数，用于标识当前返回的数据数量。 **取值范围**：大于等于0的整数，最大不超过100。 | 表6ListSparkSqlResItem | 参数 | 参数类型 | 描述 | |:---|:---|:---| | statement_id | String | **参数解释**：SparkSql作业的ID，用于唯一标识一次SparkSql作业执行。 **取值范围**：采用UUID格式，长度为36个字符，例如：80ceaaff-3cfc-4162-a56f-70031ea4fa91。 | | client_token | String | **参数解释**：SparkSql作业事务ID，用于防止重复提交。 **取值范围**：采用UUID格式，长度为36个字符，例如：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx。 | | endpoint_name | String | **参数解释**：端点名称，用于指定SparkSql执行环境。 **取值范围**：只能由英文小写字母、数字及中划线组成，以英文小写字母开头，以英文小写字母或数字结尾，且长度为1\~63个字符。 | | catalog_context | [SparkSqlCatalogContextResponse] object | **参数解释**：Catalog上下文信息，用于指定作业使用的数据目录和数据库。 | | statement | String | **参数解释**：用户SQL语句，用于执行数据查询、数据操作等任务。 **取值范围**：长度不超过500000个字符。 | | parameters | Array of [SparkSqlParameter] objects | **参数解释**：用户SQL内容的占位符参数列表，用于动态替换SQL中的参数。 | | state | String | **参数解释**：SparkSql作业的状态，用于标识作业的执行状态。 **取值范围**： - QUEUED：排队中。 - RUNNING：运行中。 - CANCELING：取消中。 - CANCELED：已取消。 - FAILED：运行失败。 - QUEUED_TIMEOUT：排队超时。 - RUNNING_TIMEOUT：运行超时。 - SUCCEED：运行成功。 | | statement_type | String | **参数解释**：SQL作业类型，用于标识作业的类型。 **取值范围**： - DDL：创建修改删除元数据类型的作业、DESC/SHOW等语句。 - DCL：权限授权与回收类型的作业。 - DQL：查询语句SELECT。 - DML：向表追加、删除、更新新数据类型的作业。 | | error | [SparkSqlErrorDto] object | **参数解释**：SparkSql作业错误详情，包含错误描述、错误码等信息。 | | result | [SparkSqlResultResponse] object | **参数解释**：SparkSql作业结果信息，包含查询结果的格式和路径等。 | | metric_statistics | [SparkSqlMetricStatisticsResponse] object | **参数解释**：SparkSql作业的指标统计信息，包含读取数据量、输出数据量、计算资源使用情况等。 | | log_url | String | **参数解释**：日志OBS归档路径，用于存储作业执行日志。 **取值范围**：采用OBS路径格式，例如：obs://bucket/path/log。 | | create_time | Long | **参数解释**：作业创建时间，采用unix时间戳格式。 **取值范围**：单位为毫秒。 | | start_time | Long | **参数解释**：作业开始运行时间，采用unix时间戳格式。 **取值范围**：单位为毫秒。 | | end_time | Long | **参数解释**：作业结束时间，采用unix时间戳格式。 **取值范围**：单位为毫秒。 | | create_user | [SparkCreateUser] object | **参数解释**：创建作业的用户信息。 | 表7SparkSqlCatalogContextResponse | 参数 | 参数类型 | 描述 | |:---|:---|:---| | catalog_name | String | **参数解释**：Catalog名称，用于指定作业使用的数据目录。 **取值范围**：长度不超过128个字符。 | | database_name | String | **参数解释**：默认数据库名称，用于指定作业使用的数据库。 **取值范围**：长度不超过128个字符。 | 表8SparkSqlParameter | 参数 | 参数类型 | 描述 | |:---|:---|:---| | key | String | **参数解释**：占位符的键，用于在SQL语句中标识参数位置。例如：SQL语句中的${key}。 **取值范围**：长度为1\~128个字符。 | | value | String | **参数解释**：占位符的值，用于替换SQL语句中的占位符。根据value_type的不同，值的格式也不同。 - STRING：字符串，例如："xxx"。 - DECIMAL：定点数，例如："12.1"。 - INTEGER：整数，例如："13"。 - DATE：日期时间戳，例如："1779188276372"。 - TIMESTAMP：时间戳，例如："1779188276372"。 **取值范围**：长度为1\~512个字符。 | | value_type | String | **参数解释**：占位符类型，用于标识占位符值的数据类型。 **取值范围**： - STRING：字符串类型。 - DECIMAL：定点数类型。 - INTEGER：整型类型。 - DATE：日期类型。 - TIMESTAMP：时间类型。 | 表9SparkSqlErrorDto | 参数 | 参数类型 | 描述 | |:---|:---|:---| | message | String | **参数解释**：SparkSql错误描述，用于说明错误的具体原因。 **取值范围**：长度为1\~1024个字符，例如：表不存在。 | | sql_state | String | **参数解释**：SparkSql错误码，用于标识错误的类型。 **取值范围**：采用标准SQL错误码格式，例如：42P01。 | | error_class | String | **参数解释**：SparkSql错误类型，用于标识错误的分类。 **取值范围**：长度为1\~128个字符，例如：SCHEMA_ALREADY_EXISTS。 | | line | Integer | **参数解释**：报错行号，用于定位SQL语句中的错误位置。 **取值范围**：大于0的整数，例如：2。 | | start_position | Integer | **参数解释**：报错起始位置，用于定位SQL语句中错误的起始字符位置。 **取值范围**：大于0的整数，例如：2。 | 表10SparkSqlResultResponse | 参数 | 参数类型 | 描述 | |:---|:---|:---| | result_format | String | **参数解释**：查询类SQL结果格式，用于指定结果的存储格式。 **取值范围**：csv、arrow。 | | result_path | String | **参数解释**：查询类SQL结果的OBS路径，用于存储SQL查询的结果数据。 **取值范围**：采用OBS路径格式，例如：obs://bucket/path/result。 | | result_records | Long | **参数解释**：查询结果行数，表示SQL查询返回的数据行数。 | | result_bytes | Long | **参数解释**：查询结果字节数，表示SQL查询返回的数据大小。 | | execution_profile_path | String | **参数解释**：作业执行计划的存储路径，用于存储作业的执行计划信息。 **取值范围**：采用OBS路径格式，例如：obs://bucket/path/profile。 | 表11SparkSqlMetricStatisticsResponse | 参数 | 参数类型 | 描述 | |:---|:---|:---| | bad_records | Long | **参数解释**：脏数据行数，用于标识处理过程中发现的错误数据行数。 **取值范围**：大于等于0的整数。 | | input_bytes | Long | **参数解释**：读取数据字节数，用于标识作业读取的数据量。 **取值范围**：大于等于0的整数，单位为字节。 | | input_records | Long | **参数解释**：读取数据行数，用于标识作业读取的数据记录数。 **取值范围**：大于等于0的整数。 | | output_bytes | Long | **参数解释**：输出数据字节数，用于标识作业输出的数据量。 **取值范围**：大于等于0的整数，单位为字节。 | | output_records | Long | **参数解释**：输出数据行数，用于标识作业输出的数据记录数。 **取值范围**：大于等于0的整数。 | | cpu_time | Long | **参数解释**：计算使用CPU秒数，用于标识作业消耗的计算资源。 **取值范围**：大于等于0的整数，单位为秒。 | 表12SparkCreateUser | 参数 | 参数类型 | 描述 | |:---|:---|:---| | user_id | String | **参数解释**：创建作业的用户ID，用于标识作业创建者。 **取值范围**：长度为1\~256个字符。 | | user_name | String | **参数解释**：创建作业的用户名称，用于标识作业创建者。 **取值范围**：长度为1\~256个字符。 | **状态码：400** 表13响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**：错误码，用于标识具体的错误类型。 **取值范围**：长度为0\~64个字符。 | | error_msg | String | **参数解释**：错误描述信息，用于说明错误原因。 **取值范围**：长度为0\~512个字符。 | | solution_msg | String | **参数解释**：解决方案描述。 **取值范围**：长度为0\~4096个字符。 | **状态码：401** 表14响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**：错误码，用于标识具体的错误类型。 **取值范围**：长度为0\~64个字符。 | | error_msg | String | **参数解释**：错误描述信息，用于说明错误原因。 **取值范围**：长度为0\~512个字符。 | | solution_msg | String | **参数解释**：解决方案描述。 **取值范围**：长度为0\~4096个字符。 | **状态码：403** 表15响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | error_code | String | **参数解释**：错误码，用于标识具体的错误类型。 **取值范围**：长度为0\~64个字符。 | | error_msg | String | **参数解释**：错误描述信息，用于说明错误原因。 **取值范围**：长度为0\~512个字符。 | | solution_msg | String | **参数解释**：解决方案描述。 **取值范围**：长度为0\~4096个字符。 | **状态码：500** 表16响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | - | String | 错误信息。 | #### 请求示例 查询工作空间下所有处于运行中或已成功状态的SparkSql作业，每页查询2条，状态过滤为"RUNNING"和"SUCCEED"。 ``` GET /v2/workspaces/{workspace_id}/spark-sqls?limit=2&states=RUNNING&states=SUCCEED ``` #### 响应示例 **状态码：200** 查询SparkSql作业列表成功。 ``` { "page_info" : { "next_marker" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "current_count" : 2 }, "statements" : [ { "statement_id" : "6c98db52-cac2-4ff1-9a91-b7793e95557d", "client_token" : "019f2601-c9b5-7d94-80f1-b9d3185433fe", "endpoint_name" : "spark-endpoint-01", "statement_type" : "DQL", "state" : "RUNNING", "catalog_context" : { "catalog_name" : "hive_catalog", "database_name" : "default" }, "statement" : "SELECT * FROM table_name LIMIT 100", "log_url" : "obs://db1/aidatalake/workspace_xxx/spark/endpoint_xxx/jobs/logs/2026_06_01/sql-engine-xxx/", "create_time" : 1698776400000, "start_time" : 1698776500000, "create_user" : { "user_id" : "user123", "user_name" : "admin" } }, { "statement_id" : "01928d08-b98a-73ce-91df-a7a0dc984207", "client_token" : "01928d08-b96b-71fb-95ce-cce0789db8de", "endpoint_name" : "spark-sql-01", "statement_type" : "UNRESOLVED", "state" : "RUNNING", "catalog_context" : { "catalog_name" : "hive_catalog", "database_name" : "db01" }, "statement" : "select * from inventory limit 10", "log_url" : "obs://db1/aidatalake/workspace_xxx/spark/endpoint_xxx/jobs/logs/2026_06_01/sql-engine-xxx/", "create_time" : 1782898538890, "start_time" : 1782898615461, "create_user" : { "user_id" : "user456", "user_name" : "admin" } } ] } ``` **状态码：400** 请求参数错误。 ``` { "error_code" : "AIDataLake.01011001", "error_msg" : "Invalid parameter statement", "solution_msg" : "Please check the input parameters according to the documentation(statement for spark sql)." } ``` **状态码：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." } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 200 | 查询SparkSql作业列表成功。 | | 400 | 请求参数错误。 | | 401 | 认证失败。 | | 403 | 权限不足。 | | 500 | 服务内部错误。 |