# 查看SparkSql作业详情 - ShowSparkSql #### 功能介绍 查看SparkSql作业的详细信息，此接口为同步接口。包括作业状态、SQL内容、执行参数等，调用成功后直接返回作业详细信息。可通过[执行SparkSql作业](https://support.huaweicloud.com/api-aidatalake/RunSparkSql.html)接口创建作业，通过[查询SparkSql作业列表](https://support.huaweicloud.com/api-aidatalake/ListSparkSqls.html)接口查询作业列表。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-aidatalake/aidatalake_02_0003.html)。 #### URI GET /v2/workspaces/{workspace_id}/spark-sqls/{statement_id} 表1路径参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | workspace_id | 是 | String | **参数解释**：工作空间ID，用于资源隔离。可在控制台的工作空间页面查看。 **约束限制**：不涉及。 **取值范围**：只能由英文字母、数字及中划线组成，且长度为32\~36个字符。 **默认取值**：不涉及。 | | statement_id | 是 | String | **参数解释**：SparkSql作业ID，用于唯一标识一次SparkSql作业执行。 **约束限制**：不涉及。 **取值范围**：只能由英文字母、数字、下划线和中划线组成，且长度为1\~64个字符。 **默认取值**：不涉及。 | #### 请求参数 表2请求Header参数 | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | X-Auth-Token | 是 | String | **参数解释**：用户Token。 **约束限制**：不涉及。 **取值范围**：长度不超过65534个字符。 **默认取值**：不涉及。 | #### 响应参数 **状态码：200** 表3响应Body参数 | 参数 | 参数类型 | 描述 | |:---|:---|:---| | endpoint_name | String | **参数解释**：端点名称，用于指定SparkSql执行环境。 **取值范围**：只能由英文小写字母、数字及中划线组成，以英文小写字母开头，以英文小写字母或数字结尾，且长度为1\~63个字符。 | | client_token | String | **参数解释**：SparkSql作业事务ID，用于防止重复提交。 **取值范围**：采用UUID格式，长度为36个字符，例如：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx。 | | catalog_context | [SparkSqlCatalogContextResponse] object | **参数解释**：Catalog上下文信息，用于指定作业使用的数据目录和数据库。 | | statement | String | **参数解释**：用户SQL语句，用于执行数据查询、数据操作等任务。 **取值范围**：长度不超过500000个字符。 | | parameters | Array of [SparkSqlParameter] objects | **参数解释**：用户SQL内容的占位符参数列表，用于动态替换SQL中的参数。数组中的每个元素为SparkSqlParameter对象，包含占位符的键和值。 | | statement_type | String | **参数解释**：SQL作业类型，用于标识作业的类型。 **取值范围**： - DDL：创建修改删除元数据类型的作业、DESC/SHOW等语句。 - DCL：权限授权与回收类型的作业。 - DQL：查询语句SELECT。 - DML：向表追加、删除、更新新数据类型的作业。 | | statement_id | String | **参数解释**：SparkSql作业的ID，用于唯一标识一次SparkSql作业执行。 **取值范围**：采用UUID格式，长度为36个字符，例如：80ceaaff-3cfc-4162-a56f-70031ea4fa91。 | | state | String | **参数解释**：SparkSql作业的状态，用于标识作业的执行状态。 **取值范围**： - QUEUED：排队中。 - RUNNING：运行中。 - CANCELING：取消中。 - CANCELED：已取消。 - FAILED：运行失败。 - QUEUED_TIMEOUT：排队超时。 - RUNNING_TIMEOUT：运行超时。 - SUCCEED：运行成功。 | | error | [SparkSqlErrorDto] object | **参数解释**：SparkSql作业错误详情，包含错误描述、错误码等信息。 | | spark_config | Map\ | **参数解释**：用户自定义Spark参数配置，用于配置作业执行时的Spark参数。 | | image | [ShowSparkSqlImageConfigResponse] object | **参数解释**：镜像配置信息，包含镜像ID和版本信息。 | | result | [SparkSqlResultResponse] object | **参数解释**：SparkSql作业结果信息，包含查询结果的格式和路径等。 | | metric_statistics | [SparkSqlMetricStatisticsResponse] object | **参数解释**：SparkSql作业的指标统计信息，包含读取数据量、输出数据量、计算资源使用情况等。 | | timeout | [SparkSqlTimeout] object | **参数解释**：SparkSql作业超时配置信息，包含排队超时和运行超时时间。 | | log_url | String | **参数解释**：日志OBS归档路径，用于存储作业执行的日志信息。包括：result（sql运行结果）、metric_statistics（SQL运行指标统计）、timeout（sql超时时间）、error（错误信息）。 **取值范围**：采用OBS路径格式，例如：obs://bucket/path/log。 | | create_time | Long | **参数解释**：作业创建时间，用于标识作业的创建时间戳。 **取值范围**：大于等于0的整数，单位为毫秒。 | | start_time | Long | **参数解释**：作业开始运行时间，用于标识作业开始执行的时间戳。 **取值范围**：大于等于0的整数，单位为毫秒。 | | end_time | Long | **参数解释**：作业结束时间，用于标识作业完成执行的时间戳。 **取值范围**：大于等于0的整数，单位为毫秒。 | | create_user | [SparkCreateUser] object | **参数解释**：创建作业的用户信息。 | | labels | Array of [SparkSqlLabelRes] objects | **参数解释**：作业标签列表，用于标识和分类作业。数组中的每个元素为SparkSqlLabelRes对象，包含标签的键和值。 | 表4SparkSqlCatalogContextResponse | 参数 | 参数类型 | 描述 | |:---|:---|:---| | catalog_name | String | **参数解释**：Catalog名称，用于指定作业使用的数据目录。 **取值范围**：长度不超过128个字符。 | | database_name | String | **参数解释**：默认数据库名称，用于指定作业使用的数据库。 **取值范围**：长度不超过128个字符。 | 表5SparkSqlParameter | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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：时间类型。 | 表6SparkSqlErrorDto | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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。 | 表7ShowSparkSqlImageConfigResponse | 参数 | 参数类型 | 描述 | |:---|:---|:---| | release_version | String | **参数解释**：SparkSql集群的版本信息(AIDalake.xxx(Sparkx.xx.x,JRExx.x))。 **取值范围**：长度为1\~512个字符。 | | image_version_type | String | **参数解释**：SparkSql集群使用的镜像版本类型。 **取值范围**： - STABLE：稳定。 - RECOMMEND：推荐。 - BETA：测试。 | 表8SparkSqlResultResponse | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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。 | 表9SparkSqlMetricStatisticsResponse | 参数 | 参数类型 | 描述 | |:---|:---|:---| | 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的整数，单位为秒。 | 表10SparkSqlTimeout | 参数 | 参数类型 | 描述 | |:---|:---|:---| | queued_timeout | Integer | **参数解释**：作业排队超时时间，单位为分钟。如果超过此时间作业仍未开始运行，则作业会被标记为排队超时并失败。 **取值范围**：10\~180分钟。 | | running_timeout | Integer | **参数解释**：作业运行超时时间，单位为分钟。如果超过此时间作业仍未运行结束，则作业会被取消并标记为运行超时。 **取值范围**：10\~720分钟。 | 表11SparkCreateUser | 参数 | 参数类型 | 描述 | |:---|:---|:---| | user_id | String | **参数解释**：创建作业的用户ID，用于标识作业创建者。 **取值范围**：长度为1\~256个字符。 | | user_name | String | **参数解释**：创建作业的用户名称，用于标识作业创建者。 **取值范围**：长度为1\~256个字符。 | 表12SparkSqlLabelRes | 参数 | 参数类型 | 描述 | |:---|:---|:---| | key | String | **参数解释**：标签的键，用于标识标签的类型或类别。 **取值范围**：长度为1\~128个字符。 | | value | String | **参数解释**：标签的值，用于标识标签的具体内容或属性。 **取值范围**：长度为1\~128个字符。 | **状态码：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作业的完整详细信息，包括SQL内容、执行参数和状态。 ``` GET /v2/workspaces/{workspace_id}/spark-sqls/{statement_id} ``` #### 响应示例 **状态码：200** 查看SparkSql作业详情成功。 ``` { "statement_id" : "6c98db52-cac2-4ff1-9a91-b7793e95557d", "client_token" : "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "endpoint_name" : "spark-endpoint-01", "catalog_context" : { "catalog_name" : "hive_catalog", "database_name" : "default" }, "statement" : "SELECT * FROM table_name LIMIT 100", "parameters" : [ { "key" : "id_param", "value" : "12345", "value_type" : "INTEGER" } ], "state" : "SUCCEED", "statement_type" : "DQL", "spark_config" : { "spark.executor.memory" : "4g", "spark.executor.cores" : "2" }, "result" : { "result_format" : "csv", "result_path" : "obs://my-bucket/results/6c98db52/result.csv", "execution_profile_path" : "obs://my-bucket/profiles/6c98db52/profile" }, "metric_statistics" : { "bad_records" : 0, "input_bytes" : 1048576, "input_records" : 1000, "output_bytes" : 524288, "output_records" : 500, "cpu_time" : 3000 }, "timeout" : { "queued_timeout" : 180, "running_timeout" : 720 }, "log_url" : "https://obs.example.com/logs/spark-sql.log", "create_time" : 1698776400000, "start_time" : 1698776450000, "end_time" : 1698776700000, "create_user" : { "user_id" : "user123", "user_name" : "admin" }, "labels" : [ { "key" : "env", "value" : "production" } ] } ``` **状态码：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 | 服务内部错误。 |