# 执行SparkSql作业 - RunSparkSql #### 功能介绍 执行SparkSql作业，此接口为异步接口。接口调用成功后会返回作业ID（statement_id）,您可以通过查询作业状态接口查询作业执行结果，详情请参见[查询SparkSql作业的状态](https://support.huaweicloud.com/api-aidatalake/ShowSparkSqlState.html)。 #### 调用方法 请参见[如何调用API](https://support.huaweicloud.com/api-aidatalake/aidatalake_02_0003.html)。 #### 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\ | **参数解释**：用户自定义Spark参数配置，用于优化作业性能。格式为key/value键值对，Key为参数名称，Value为参数值。例如：spark.executor.memory=4g。 **约束限制**：参数配置项数量不能超过100条，每个参数值的长度不超过1024个字符。 | | timeout | 否 | [SparkSqlTimeout] object | **参数解释**：作业超时配置，用于设置作业排队和运行的超时时间。 **约束限制**：不涉及。 | | labels | 否 | Array of [SparkSqlLabel] objects | **参数解释**：作业标签列表，用于标识和分类作业。数组中的每个元素为SparkSqlLabel对象，包含标签的键和值。 **约束限制**：标签数量不能超过16条。 | 表4SparkSqlCatalogContext | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | catalog_name | 是 | String | **参数解释**：Catalog名称，用于指定作业使用的数据目录。可在控制台的Catalog管理页面查看，或通过查询Catalog列表接口获取。 **约束限制**：不涉及。 **取值范围**：不超过128个字符。 **默认取值**：不涉及。 | | database_name | 否 | String | **参数解释**：默认数据库名称，用于指定作业默认操作的数据库。如果未指定，则使用Catalog的默认数据库。 **约束限制**：不涉及。 **取值范围**：不超过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：时间类型。 **默认取值**：STRING。 | 表6SparkSqlTimeout | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | queued_timeout | 否 | Integer | **参数解释**：作业排队超时时间，单位为分钟。如果超过此时间作业仍未开始运行，则作业会被标记为排队超时并失败。 **取值范围**：10\~180分钟。 | | running_timeout | 否 | Integer | **参数解释**：作业运行超时时间，单位为分钟。如果超过此时间作业仍未运行结束，则作业会被取消并标记为运行超时。 **取值范围**：10\~720分钟。 | 表7SparkSqlLabel | 参数 | 是否必选 | 参数类型 | 描述 | |:---|:---|:---|:---| | 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." } ``` #### 状态码 | 状态码 | 描述 | |:---|:---| | 201 | 创建成功。 | | 400 | 请求参数错误。 | | 401 | 认证失败。 | | 403 | 权限不足。 | | 500 | 服务内部错误。 |