执行SparkSql作业 - RunSparkSql

功能介绍

执行SparkSql作业，此接口为异步接口。接口调用成功后会返回作业ID（statement_id）,您可以通过查询作业状态接口查询作业执行结果，详情请参见查询SparkSql作业的状态。

调用方法

URI

POST /v2/workspaces/{workspace_id}/spark-sqls

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

请求参数

表2 请求Header参数
参数	是否必选	参数类型	描述
X-Auth-Token	是	String	参数解释：用户Token。约束限制：不涉及。取值范围：长度不超过65534个字符。默认取值：不涉及。
X-Client-Token	否	String	参数解释：服务事务ID，用于链路追踪和问题定位。约束限制：不涉及。取值范围：不涉及。默认取值：不涉及。

表3 请求Body参数
参数	是否必选	参数类型	描述
endpoint_name	是	String	参数解释：端点名称，用于指定SparkSql作业运行的计算引擎。可在控制台的端点管理页面查看，或通过查询端点列表接口获取。约束限制：不涉及。取值范围：只能以英文小写字母开头，由英文小写字母、数字及中划线组成，以英文小写字母或数字结尾，且长度为1~63个字符。默认取值：不涉及。
catalog_context	是	SparkSqlCatalogContext object	参数解释：Catalog上下文信息，用于指定作业使用的数据目录和数据库。约束限制：不涉及。
statement	是	String	参数解释：用户SQL语句，用于执行SparkSql作业。支持DDL、DCL、DQL、DML等多种SQL类型。约束限制：不涉及。取值范围：不超过500000个字符。默认取值：不涉及。
parameters	否	Array of SparkSqlParameter objects	参数解释：用户SQL语句中的占位符参数列表，用于SQL参数化执行。数组中的每个元素为SparkSqlParameter对象，包含占位符的键、值和类型信息。约束限制：占位符参数数量不能超过16条。
spark_config	否	Map<String,String>	参数解释：用户自定义Spark参数配置，用于优化作业性能。格式为key/value键值对，Key为参数名称，Value为参数值。例如：spark.executor.memory=4g。约束限制：参数配置项数量不能超过100条，每个参数值的长度不超过1024个字符。
timeout	否	SparkSqlTimeout object	参数解释：作业超时配置，用于设置作业排队和运行的超时时间。约束限制：不涉及。
labels	否	Array of SparkSqlLabel objects	参数解释：作业标签列表，用于标识和分类作业。数组中的每个元素为SparkSqlLabel对象，包含标签的键和值。约束限制：标签数量不能超过16条。

表4 SparkSqlCatalogContext
参数	是否必选	参数类型	描述
catalog_name	是	String	参数解释：Catalog名称，用于指定作业使用的数据目录。可在控制台的Catalog管理页面查看，或通过查询Catalog列表接口获取。约束限制：不涉及。取值范围：不超过128个字符。默认取值：不涉及。
database_name	否	String	参数解释：默认数据库名称，用于指定作业默认操作的数据库。如果未指定，则使用Catalog的默认数据库。约束限制：不涉及。取值范围：不超过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 SparkSqlTimeout
参数	是否必选	参数类型	描述
queued_timeout	否	Integer	参数解释：作业排队超时时间，单位为分钟。如果超过此时间作业仍未开始运行，则作业会被标记为排队超时并失败。取值范围：10~180分钟。
running_timeout	否	Integer	参数解释：作业运行超时时间，单位为分钟。如果超过此时间作业仍未运行结束，则作业会被取消并标记为运行超时。取值范围：10~720分钟。

表7 SparkSqlLabel
参数	是否必选	参数类型	描述
key	是	String	参数解释：标签的键，用于标识作业的分类维度。例如：env、project等。约束限制：不涉及。取值范围：长度为1~128个字符。默认取值：不涉及。
value	是	String	参数解释：标签的值，用于标识作业的具体分类。例如：production、data-analytics等。约束限制：不涉及。取值范围：长度为1~512个字符。默认取值：不涉及。

响应参数

状态码：201

表8 响应Body参数
参数	参数类型	描述
statement_id	String	参数解释：作业ID，用于唯一标识本次执行的SparkSql作业。可通过此ID查询作业状态和执行结果。取值范围：采用UUID格式，长度为36个字符，例如：6c98db52-cac2-4ff1-9a91-b7793e95557d。

状态码：400

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

状态码：401

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

状态码：403

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

状态码：500

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

请求示例

执行简单的SQL查询语句，端点名称为“spark-endpoint-01”，Catalog为“hive_catalog”，数据库为“default”，查询语句为“SELECT * FROM table_name LIMIT 100”，排队超时“180”秒，运行超时“720”秒。

POST /v2/workspaces/{workspace_id}/spark-sqls

{
  "endpoint_name" : "spark-endpoint-01",
  "catalog_context" : {
    "catalog_name" : "hive_catalog",
    "database_name" : "default"
  },
  "statement" : "SELECT * FROM table_name LIMIT 100",
  "timeout" : {
    "queued_timeout" : 180,
    "running_timeout" : 720
  }
}

执行带占位符参数的SQL语句，端点名称为“spark-endpoint-01”，Catalog为“hive_catalog”，数据库为“default”，查询语句包含“id_param”和“name_param”两个参数，标签有“env=production”和“project=data-analytics”，Spark配置“executor内存4g”、“executor核数2”，排队超时“180”秒，运行超时“720”秒。

POST /v2/workspaces/{workspace_id}/spark-sqls

{
  "endpoint_name" : "spark-endpoint-01",
  "catalog_context" : {
    "catalog_name" : "hive_catalog",
    "database_name" : "default"
  },
  "statement" : "SELECT * FROM table_name WHERE id = ${id_param} AND name = ${name_param}",
  "parameters" : [ {
    "key" : "id_param",
    "value" : "12345",
    "value_type" : "INTEGER"
  }, {
    "key" : "name_param",
    "value" : "test_table",
    "value_type" : "STRING"
  } ],
  "labels" : [ {
    "key" : "env",
    "value" : "production"
  }, {
    "key" : "project",
    "value" : "data-analytics"
  } ],
  "spark_config" : {
    "spark.executor.memory" : "4g",
    "spark.executor.cores" : "2"
  },
  "timeout" : {
    "queued_timeout" : 180,
    "running_timeout" : 720
  }
}

执行DDL语句创建表，端点名称为“spark-endpoint-01”，Catalog为“hive_catalog”，数据库为“default”，建表语句为“CREATE TABLE IF NOT EXISTS test_table”，排队超时“180”秒，运行超时“720”秒。

POST /v2/workspaces/{workspace_id}/spark-sqls

{
  "endpoint_name" : "spark-endpoint-01",
  "catalog_context" : {
    "catalog_name" : "hive_catalog",
    "database_name" : "default"
  },
  "statement" : "CREATE TABLE IF NOT EXISTS test_table (id INT, name STRING, age INT) USING PARQUET",
  "timeout" : {
    "queued_timeout" : 180,
    "running_timeout" : 720
  }
}

响应示例

状态码：201

创建成功。

{
  "statement_id" : "6c98db52-cac2-4ff1-9a91-b7793e95557d"
}

状态码：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."
}