# 通过Spark Connect提交作业
#### 概述
Spark Connect是Spark 3.4引入的客户端-服务端架构，允许用户通过gRPC协议从远程客户端连接到Spark驱动程序，使用DataFrame API和Spark SQL执行交互式数据分析，而无需在本地安装完整的Spark运行环境。与普通Spark作业"提交即运行、运行完退出"不同，Spark Connect常驻运行，支持随时连接、提交查询、获取结果。客户端仅需pyspark和grpc依赖，无需部署完整Spark集群，适合在Notebook、IDE或脚本中快速接入。
图1Spark Connect工作原理   
![](https://support.huaweicloud.com/usermanual-aidatalake/zh-cn_image_0000002810957873.png "点击放大")
#### 步骤一：创建Spark Connect作业并获取作业ID
使用Postman等工具，调用[创建SparkJob作业](https://support.huaweicloud.com/api-aidatalake/RunSparkJob.html)API接口创建并启动一个Spark Connect作业，代码示例如下。
```
POST /v2/workspaces/{workspace_id}/spark-jobs
{
    "name": "sparkconnect_test",
    "catalog_name": "demo_db",
    "job_agency": "spark",
    "description": "Spark Connect Server 长期运行服务",
    "endpoint_name": "spark-job-test",
    "spark_version": "4.0.0",
    "job_config": {
        "type": "spark_jar_job",
        "main_args": [],
        "main_class": "org.apache.spark.sql.connect.service.SparkConnectServer",
        "main_jar": "spark-internal"
    },
    "resource_config": {
        "executor_number": 3,
        "driver_resource_spec": {
            "cpu": 1000,
            "memory": 1024,
            "disk": 20
        },
        "executor_resource_spec": {
            "cpu": 1000,
            "memory": 1024,
            "disk": 10
        }
    },
    "spark_config": {
        "spark.connect.authenticate.token": "test2"
    },
    "labels": [
        {
            "key": "environment",
            "value": "dev"
        }
    ]
}
```
表1Spark Connect作业关键参数说明 
| 参数                  | 是否必填 | 说明                                                                                                                                                                                                                                                                                                                                                                                                |
|:---|:---|:---|
| name                 | 是    | 作业名称。                                                                                                                                                                                                                                                                                                                                                                                           |
| endpoint_name        | 是    | Spark类型endpoint的名称。                                                                                                                                                                                                                                                                                                                                                                               |
| job_agency           | 否      | 委托名称，须为当前租户已存在的委托。不指定时使用端点配置的作业委托。                                                                                                                                                                                                                                                                                                                                                               |
| job_config.type      | 是     | 固定为spark_jar_job。                                                                                                                                                                                                                                                                                                                                                                               |
| job_config.main_class | 是    | 固定为org.apache.spark.sql.connect.service.SparkConnectServer，即Spark Connect服务端入口类，指定后作业将启动Spark Connect的gRPC服务而非执行用户业务代码。                                                                                                                                                                                                                                                                          |
| job_config.main_jar | 是   | 固定为spark-internal。                                                                                                                                                                                                                                                                                                                                                                               |
| spark_config        | 否      | Spark配置参数。 - 通过spark.connect.authenticate.token设置鉴权Token，客户端连接时以authorization=Bearer \\{token\\}携带。不配置时服务端不做鉴权。  - 通过spark.connect.server.idleTimeout设置空闲超时时间，实例在无客户端连接超过该时长时自动关闭。不设置则长期运行。   |
| resource_config      | 否   | 资源配置，包含executor_number、driver_resource_spec和executor_resource_spec，各含cpu、memory和disk字段。                                                                                                                                                                                                                                                                                                            |
   
#### 步骤二：客户端连接配置
作业创建成功并进入运行状态后，即可配置客户端连接。
1. **获取访问地址** ：Spark Connect通过gRPC协议连接，完整连接地址由URL和通道选项组成：
   - **URL**：sc://{入口IP}:{端口}/;authorization=Bearer%20{token}
   
   - **通道选项**：grpc.default_authority: {jobId}.spark-connect
   
   
   表2各参数说明及获取方式 
   | 参数                      | 说明                                                                                                            |
   |:---|:---|
   | 入口IP                    | 网络接入后得到的VPC终端节点IP或ELB公网IP。                                                                                    |
   | 端口                     | 34002（开启SSL认证）或34000（不开启SSL认证）。                                                                                 |
   | token                    | 创建作业时在spark_config.spark.connect.authenticate.token中设置的值。未配置Token时，URL中去掉;authorization=Bearer%20\\{token\\}部分。 |
   | grpc.default_authority | gRPC通道选项（channelOptions），格式为{jobId}.spark-connect，其中jobId为创建作业返回的job_id，后缀固定为.spark-connect。所有场景均需配置。         |
      
   
2. **配置客户端证书** （仅SSL开启时）：若创建端点时开启了SSL认证，客户端须配置客户端证书才能连接，否则连接会被拒绝。按以下步骤操作：
   1. **下载证书** ：下载客户端证书包，包含ca.crt（CA证书）、client.key（客户端私钥）、client.crt（客户端证书）三个文件。下载操作详情请参见[网络接入](https://support.huaweicloud.com/usermanual-aidatalake/aidatalake_01_0025.html)。
   
   2. **上传证书**：将证书包上传到客户端运行环境（如Notebook环境或Python脚本所在机器），记录证书文件所在目录路径。
   
   3. **配置证书** ：在连接代码中通过grpc.ssl_channel_credentials加载证书，相关参数说明如下：
      表3证书参数说明 
      | 参数                           | 示例                         | 说明                                                                |
      |:---|:---|:---|
      | root_certificates          | /path/to/cert/ca.crt      | CA证书路径，用于校验服务端证书。取客户端证书包中的ca.crt。                                  |
      | private_key                | /path/to/cert/client.key | 客户端私钥路径。取客户端证书包中的client.key。                                     |
      | certificate_chain             | /path/to/cert/client.crt | 客户端证书路径。取客户端证书包中的client.crt。                                      |
      | grpc.ssl_target_name_override | 127.0.0.1                | 服务端证书校验名，通过grpc.secure_channel的options参数传入。当前服务端证书SAN固定为127.0.0.1。 |
         
      配置代码示例：
      ```
      import grpc
      from pyspark.sql.connect.client import DefaultChannelBuilder
      from pyspark.sql.connect.session import SparkSession
      # 构建连接通道（连接URL + 通道选项）
      channel_builder = DefaultChannelBuilder(
          "sc://10.10.10.10:80/;authorization=Bearer%20test2",
          channelOptions=[
              ("grpc.default_authority", "{jobId}.spark-connect")
          ],
      )
      # 加载客户端证书
      # 将 /path/to/cert 替换为您上传的客户端证书所在目录
      credentials = grpc.ssl_channel_credentials(
          root_certificates=open("/path/to/cert/ca.crt", "rb").read(),
          private_key=open("/path/to/cert/client.key", "rb").read(),
          certificate_chain=open("/path/to/cert/client.crt", "rb").read(),
      )
      # 使用带证书的通道建立连接
      channel_builder.toChannel = lambda: grpc.secure_channel(
          channel_builder.endpoint,
          credentials,
          options=channel_builder._channel_options + [("grpc.ssl_target_name_override", "127.0.0.1")],
      )
      # 创建SparkSession
      spark = SparkSession.builder.channelBuilder(channel_builder).getOrCreate()
      print(spark.version)
      ```
      
    
3. **连接与使用** ：使用PySpark客户端创建SparkSession连接Spark Connect服务端，执行DataFrame API和SQL交互式查询。完整代码示例参见[使用场景]。
4. **关闭连接**：使用完成后调用spark.stop()关闭SparkSession，释放连接。如需释放服务端资源，调用取消作业接口停止Spark Connect实例。
 
 #### 使用场景
- **通过Notebook连接**
  在Notebook中通过PySpark客户端连接Spark Connect服务端，进行交互式数据分析。
  **前置条件**：
  - 已创建Spark Connect作业并进入运行状态，已获得接入IP和端口（网络接入方法请参考前提条件中网络接入说明）。
  
  - 已获取连接信息（接入地址、端口、认证Token、SparkJob ID）。
  
  - 本地已安装Python 3.8+和JupyterLab。
  
  
  **环境准备**：
  ```
  # 创建虚拟环境
  python -m venv spark40-notebook
  # 激活虚拟环境
  # Linux/macOS: source spark40-notebook/bin/activate
  # Windows:     .\spark40-notebook\Scripts\activate
  # 安装依赖
  pip install jupyterlab pyspark==4.0.0
  # 启动JupyterLab
  jupyter lab
  ```
  **连接与使用**：
  根据是否开启SSL认证选择对应的连接方式。连接成功后即可执行交互式查询。
  - **SSL认证关闭时** ：
    ```
    from pyspark.sql.connect.client import DefaultChannelBuilder
    from pyspark.sql.connect.session import SparkSession
    # 构建连接通道
    # 将 10.10.10.10:80 替换为您创建网络接入的地址和端口
    # 将 test2 替换为您创建Spark Connect时在spark_config中设置的token
    channel_builder = DefaultChannelBuilder(
        "sc://10.10.10.10:80/;authorization=Bearer%20test2",
        channelOptions=[
            # 将 019eca36-2e6e-7ec2-82f0-649fc2b48dcb 替换为您的SparkJob ID
            ("grpc.default_authority", "019eca36-2e6e-7ec2-82f0-649fc2b48dcb.spark-connect")
        ],
    )
    # 创建SparkSession
    spark = SparkSession.builder.channelBuilder(channel_builder).getOrCreate()
    # 执行交互式查询
    spark.sql("SELECT 1 AS test").show()
    # 创建DataFrame
    df = spark.range(10)
    df.show()
    # 查看Spark版本
    print(spark.version)
    # 关闭连接
    spark.stop()
    ```
    
  
  - **SSL认证开启时** ：
    ```
    import grpc
    from pyspark.sql.connect.client import DefaultChannelBuilder
    from pyspark.sql.connect.session import SparkSession
    # 构建连接通道
    # 将 10.10.10.10:80 替换为您创建网络接入的地址和端口
    # 将 test2 替换为您创建Spark Connect时在spark_config中设置的token
    channel_builder = DefaultChannelBuilder(
        "sc://10.10.10.10:80/;authorization=Bearer%20test2",
        channelOptions=[
            # 将 019eca36-2e6e-7ec2-82f0-649fc2b48dcb 替换为您的SparkJob ID
            ("grpc.default_authority", "019eca36-2e6e-7ec2-82f0-649fc2b48dcb.spark-connect")
        ],
    )
    # 加载客户端证书
    # 将 /path/to/cert 替换为您上传的客户端证书所在目录
    credentials = grpc.ssl_channel_credentials(
        root_certificates=open("/path/to/cert/ca.crt", "rb").read(),
        private_key=open("/path/to/cert/client.key", "rb").read(),
        certificate_chain=open("/path/to/cert/client.crt", "rb").read(),
    )
    # 使用带证书的通道建立连接
    channel_builder.toChannel = lambda: grpc.secure_channel(
        channel_builder.endpoint,
        credentials,
        options=channel_builder._channel_options + [("grpc.ssl_target_name_override", "127.0.0.1")],
    )
    # 创建SparkSession
    spark = SparkSession.builder.channelBuilder(channel_builder).getOrCreate()
    # 执行交互式查询
    spark.sql("SELECT 1 AS test").show()
    df = spark.range(10)
    df.show()
    print(spark.version)
    # 关闭连接
    spark.stop()
    ```
    
    
- **通过Python脚本连接**
  创建Python脚本文件（如spark_connect_job.py），编写连接代码并执行数据分析操作。
  **前置条件**：
  - 已创建Spark Connect作业并进入运行状态，已获得接入IP和端口（网络接入方法请参考前提条件中网络接入说明）。
  
  - 已获取连接信息（接入地址、端口、认证Token、SparkJob ID）。
  
  - 本地已安装Python 3.8+和PySpark 4.0.x。
  
  
  **注意事项**
  - 运行脚本前须安装pyspark和grpcio依赖：pip install pyspark grpcio。
  
  - 如需连接多个Spark Connect实例，分别使用各实例的接入地址、Token和SparkJob ID构建不同的SparkSession，使用完成后逐个调用spark.stop()关闭。
  
  
  **示例脚本**：
  以下脚本同时适配SSL开启和关闭场景，通过SSL_ENABLED参数切换。SSL开启时须将CERT_DIR替换为实际的客户端证书目录。
  ```
  import grpc
  from pyspark.sql.connect.client import DefaultChannelBuilder
  from pyspark.sql.connect.session import SparkSession
  # ========== 连接配置 ==========
  # 将以下参数替换为您的实际值
  ADDRESS = "10.10.10.10"       # 网络接入地址
  PORT = "80"                    # 网络接入端口
  TOKEN = "test2"               # spark_config中设置的spark.connect.authenticate.token（未配置时设为None）
  JOB_ID = "019eca36-2e6e-7ec2-82f0-649fc2b48dcb"  # SparkJob ID
  # SSL配置（开启SSL认证时使用）
  SSL_ENABLED = False
  CERT_DIR = "/path/to/cert"    # 客户端证书目录
  # ========== 构建连接 ==========
  url = f"sc://{ADDRESS}:{PORT}/"
  if TOKEN:
      url += f";authorization=Bearer%20{TOKEN}"
  channel_builder = DefaultChannelBuilder(
      url,
      channelOptions=[
          ("grpc.default_authority", f"{JOB_ID}.spark-connect")
      ],
  )
  if SSL_ENABLED:
      credentials = grpc.ssl_channel_credentials(
          root_certificates=open(f"{CERT_DIR}/ca.crt", "rb").read(),
          private_key=open(f"{CERT_DIR}/client.key", "rb").read(),
          certificate_chain=open(f"{CERT_DIR}/client.crt", "rb").read(),
      )
      channel_builder.toChannel = lambda: grpc.secure_channel(
          channel_builder.endpoint,
          credentials,
          options=channel_builder._channel_options + [("grpc.ssl_target_name_override", "127.0.0.1")],
      )
  # ========== 创建SparkSession并执行查询 ==========
  spark = SparkSession.builder.channelBuilder(channel_builder).getOrCreate()
  # 验证连接
  print(f"Spark version: {spark.version}")
  # 执行SQL查询
  spark.sql("CREATE TABLE IF NOT EXISTS test_table (id INT, name STRING) USING json")
  spark.sql("INSERT INTO test_table VALUES (1, 'Alice'), (2, 'Bob')")
  df = spark.sql("SELECT * FROM test_table WHERE id > 0")
  df.show()
  # 停止SparkSession
  spark.stop()
  ```
  
 
#### 接口参考
以下为Spark Connect作业管理常用接口速查表：
表4Spark Connect常用管理接口 
| 用途                  | 方法 + 路径                                                                      |
|:---|:---|
| 创建Spark Connect作业   | POST /v2/workspaces/\\{workspace\\_id\\}/spark-jobs                       |
| 查看Spark作业详情       | GET /v2/workspaces/\\{workspace\\_id\\}/spark-jobs/\\{job\\_id\\}          |
| 停止Spark Connect实例 | POST /v2/workspaces/\\{workspace\\_id\\}/spark-jobs/\\{job\\_id\\}/cancel |
   
