查看SparkSql作业详情 - ShowSparkSql

功能介绍

查看SparkSql作业的详细信息，此接口为同步接口。包括作业状态、SQL内容、执行参数等，调用成功后直接返回作业详细信息。可通过执行SparkSql作业接口创建作业，通过查询SparkSql作业列表接口查询作业列表。

调用方法

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<String,String>	参数解释：用户自定义Spark参数配置，用于配置作业执行时的Spark参数。
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对象，包含标签的键和值。

表4 SparkSqlCatalogContextResponse
参数	参数类型	描述
catalog_name	String	参数解释：Catalog名称，用于指定作业使用的数据目录。取值范围：长度不超过128个字符。
database_name	String	参数解释：默认数据库名称，用于指定作业使用的数据库。取值范围：长度不超过128个字符。

表5 SparkSqlParameter
参数	参数类型	描述
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：时间类型。默认取值：STRING。

表6 SparkSqlErrorDto
参数	参数类型	描述
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。

表7 SparkSqlResultResponse
参数	参数类型	描述
result_format	String	参数解释：查询类SQL结果格式，用于指定结果的存储格式。取值范围：csv、arrow。
result_path	String	参数解释：查询类SQL结果的OBS路径，用于存储SQL查询的结果数据。取值范围：采用OBS路径格式，例如：obs://bucket/path/result。
execution_profile_path	String	参数解释：作业执行计划的存储路径，用于存储作业的执行计划信息。取值范围：采用OBS路径格式，例如：obs://bucket/path/profile。

表8 SparkSqlMetricStatisticsResponse
参数	参数类型	描述
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的整数，单位为秒。

表9 SparkSqlTimeout
参数	参数类型	描述
queued_timeout	Integer	参数解释：作业排队超时时间，单位为分钟。如果超过此时间作业仍未开始运行，则作业会被标记为排队超时并失败。取值范围：10~180分钟。
running_timeout	Integer	参数解释：作业运行超时时间，单位为分钟。如果超过此时间作业仍未运行结束，则作业会被取消并标记为运行超时。取值范围：10~720分钟。

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

**表11** SparkSqlLabelRes
参数	参数类型	描述
key	String	参数解释：标签的键，用于标识标签的类型或类别。取值范围：长度为1~128个字符。
value	String	参数解释：标签的值，用于标识标签的具体内容或属性。取值范围：长度为1~128个字符。

状态码：400

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

状态码：401

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

状态码：403

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

状态码：500

**表15** 响应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."
}