更新时间:2026-11-18 GMT+08:00
分享

通过Spark Connect提交作业

概述

Spark Connect是Spark 3.4引入的客户端-服务端架构,允许用户通过gRPC协议从远程客户端连接到Spark驱动程序,使用DataFrame API和Spark SQL执行交互式数据分析,而无需在本地安装完整的Spark运行环境。与普通Spark作业“提交即运行、运行完退出”不同,Spark Connect常驻运行,支持随时连接、提交查询、获取结果。客户端仅需pyspark和grpc依赖,无需部署完整Spark集群,适合在Notebook、IDE或脚本中快速接入。

图1 Spark Connect工作原理

步骤一:创建Spark Connect作业并获取作业ID

使用Postman等工具,调用创建SparkJob作业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"
        }
    ]
}
表1 Spark 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(客户端证书)三个文件。下载操作详情请参见网络接入。
    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作业管理常用接口速查表:

表4 Spark 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

相关文档