SeaTunnel Python SDK 实战:用 Python 驱动 Zeta 引擎的作业提交、管理与集群监控

原创2026-09-17 21:16:462,207 阅读
文章标签:数据集成ETL大数据数据同步变更数据捕获流处理批处理

SeaTunnel Python SDK 实战:用 Python 驱动 Zeta 引擎的作业提交、管理与集群监控

导读

SeaTunnel Python SDK 是 Apache SeaTunnel 为开发者提供的 Python 客户端库,它围绕 SeaTunnel Engine(Zeta)的 REST API 封装了作业提交、作业管理和集群监控能力。本文以 docs/en/engines/zeta/python-sdk.md 为主体,结合 tools/seatunnel-python-sdk 下的源码与测试,完整讲解 SDK 的安装方式、Client 与 Jobs/Cluster 等 API 的使用方法、参数语义与底层 REST 契约,帮助读者在已有 Zeta 引擎集群的前提下,快速用 Python 实现数据任务的自动化编排与运维。

一、SDK 概述与适用场景

SeaTunnel Python SDK 是一层轻量的 REST 封装:它以 SeaTunnelClient 为核心入口,将 SeaTunnel Engine 暴露的 HTTP 接口转换为 Python 方法调用。从源码结构看,SDK 划分为四组端点(tools/seatunnel-python-sdk/seatunnel/endpoints):

  • JobsApi:作业生命周期管理(提交、批量提交、停止、查询);
  • ClusterApi:集群概览、指标、日志;
  • ConfigApi:配置加密;
  • SystemApi:系统监控信息。

典型适用场景包括:用 Python 脚本批量提交多个 SeaTunnel 作业、基于作业状态做自动化告警与重试、将 SeaTunnel 任务编排进 Python 数据平台或调度系统中。

二、安装

SDK 目前尚未发布到 PyPI,需要从 SeaTunnel 源码树直接安装,要求 Python 3.9 及以上版本:

git clone https://github.com/apache/seatunnel.git
cd seatunnel
python -m pip install ./tools/seatunnel-python-sdk

SDK 的运行时依赖非常简单,仅要求 httpx(HTTP 客户端),构建与发布依赖 setuptools、wheel、twine,见 requirements.txt。例如在开发环境可直接执行:

python -m pip install ./tools/seatunnel-python-sdk
python -c "import seatunnel; print(seatunnel.__file__)"

三、快速上手:第一个提交任务

使用 SDK 前需要有一个正在运行的 SeaTunnel Engine 实例。Zeta 引擎的 REST 服务默认监听 8080 端口,可通过 config/seatunnel.yaml 中的 http 段配置:

http:
  enable-http: true
  port: 8080
  enable-dynamic-port: false
  # Uncomment the following lines to enable basic authentication for web UI
  # enable-basic-auth: true
  # basic-auth-username: admin
  # basic-auth-password: admin

下面的示例演示用 Python 提交一个批处理作业(FakeSource 生成 100 条数据写入 Console):

from seatunnel import SeaTunnelClient, SubmitJobQueryParams

config = """
env {
  job.mode = "batch"
}
source {
  FakeSource {
    plugin_output = "fake"
    row.num = 100
    schema = {
      fields {
        name = "string"
        age = "int"
      }
    }
  }
}
transform {}
sink {
  Console {}
}
"""
with SeaTunnelClient(base_url="http://localhost:8080") as client:
  query_params = SubmitJobQueryParams()
  response = client.jobs.submit_job(conf=config, params=query_params)
  print(response)

3.1 上下文管理器自动释放连接

SeaTunnelClient 实现了上下文管理器协议(见 client.py):进入 with 块时返回自身,退出时调用 close() 关闭底层 httpx.Client 会话。test_context_manager_closes_underlying_session 测试(test_sdk.py)验证了退出后底层会话确实被关闭,因此推荐始终以 with 方式使用客户端,避免连接泄漏。

3.2 提交作业的底层实现

submit_job 实际是向 POST /submit-job 发送请求,配置字符串作为请求体(content),查询参数来自 SubmitJobQueryParams(见 jobs.py):

return self.client.request(
    HttpMethod.POST, "/submit-job", content=conf, params=params.__dict__
)

SubmitJobQueryParams 是一个 dataclass(queryParams.py),其字段与 Zeta REST 服务的查询参数一一对应:

字段 类型 默认值 说明
jobId Optional[int] None 指定作业 ID(如从 SavePoint 恢复时使用)
jobName `Optional[str] None 作业名称
isStartWithSavePoint Optional[bool] None 是否从 SavePoint 启动
format str "hocon" 配置格式,默认 HOCON

上述查询键(jobId、jobName、isStartWithSavePoint、format)在服务端 RestConstant.java 中均有对应常量定义。测试 test_submit_job_sends_body_and_query_params 验证了提交时会同时携带配置内容、jobName 与 format=hocon 参数,返回结果中包含 jobId。

四、作业管理(Jobs API)

client.jobs 提供完整的作业生命周期管理能力,其 URL 契约与 RestConstant 中定义的服务端路径一一对应。

4.1 从配置文件提交

除了直接传配置字符串,还可以提交本地配置文件(上传方式),SDK 以 multipart 形式把文件内容发送到 POST /submit-job/upload:

from seatunnel import SeaTunnelClient, SubmitJobFileQueryParams

with SeaTunnelClient(base_url="http://localhost:8080") as client:
  params = SubmitJobFileQueryParams(jobName="my-job")
  response = client.jobs.submit_job_from_file(filePath="./job.conf", params=params)
  print(response)

SubmitJobFileQueryParams 支持 jobId、jobName、isStartWithSavePoint 三个可选字段(无 format 字段),与字符串提交的参数面略有差异。

4.2 批量提交作业

将多个 HOCON 配置拼接后一次性提交到 POST /submit-jobs:

with SeaTunnelClient(base_url="http://localhost:8080") as client:
  confs = """
  env { job.mode = "batch" }
  source { FakeSource { plugin_output = "fake" row.num = 10 schema = { fields { id = "int" } } } }
  transform {}
  sink { Console {} }

  env { job.mode = "batch" }
  source { FakeSource { plugin_output = "fake2" row.num = 20 schema = { fields { id = "int" } } } }
  transform {}
  sink { Console {} }
  """
  response = client.jobs.submit_jobs(confs=confs)
  print(response)

4.3 停止作业

停止单个作业需要 StopJobQueryParams,其中 jobId 与 isStartWithSavePoint 均为必填字段(见 queryParams.py):

from seatunnel import SeaTunnelClient, StopJobQueryParams

with SeaTunnelClient(base_url="http://localhost:8080") as client:
  params = StopJobQueryParams(jobId=12345, isStartWithSavePoint=False)
  response = client.jobs.stop_job(params=params)
  print(response)

停止多个作业时传入 StopJobQueryParams 列表,SDK 会将其序列化为 JSON 数组发送到 POST /stop-jobs:

params_list = [
  StopJobQueryParams(jobId=12345, isStartWithSavePoint=False),
  StopJobQueryParams(jobId=12346, isStartWithSavePoint=True),
]
response = client.jobs.stop_jobs(params=params_list)

4.4 查询作业状态与详情

  • 查看运行中的作业:GET /running-jobs,返回所有作业的概览与状态:
with SeaTunnelClient(base_url="http://localhost:8080") as client:
  running_jobs = client.jobs.get_running_jobs()
  print(running_jobs)
  • 查看作业详情:GET /job-info/{jobId},返回指定作业的详细信息:
with SeaTunnelClient(base_url="http://localhost:8080") as client:
  job_id = 12345  # Replace with actual Job ID
  job_details = client.jobs.get_job_details(jobId=job_id)
  print(job_details)
  • 查看已结束作业:GET /finished-jobs/{jobStatus},可按状态过滤。state 参数为 JobStatus 枚举(jobStatus.py),可选值包括:
枚举值 字符串值 含义
FINISHED "FINISHED" 作业正常完成
CANCELED "CANCELED" 作业被取消
FAILED "FAILED" 作业失败
SAVEPOINT_DONE "SAVEPOINT_DONE" SavePoint 完成
UNKNOWABLE "UNKNOWABLE" 状态未知
from seatunnel import SeaTunnelClient, JobStatus

with SeaTunnelClient(base_url="http://localhost:8080") as client:
  finished = client.jobs.get_finished_jobs_info(state=JobStatus.FINISHED)
  print(finished)

不传 state 时,SDK 会请求 GET /finished-jobs/,返回所有已结束作业的信息(jobs.py)。

五、集群监控(Cluster API)

client.cluster 提供集群维度的监控能力,对应 ClusterApi(cluster.py)。

5.1 集群概览

with SeaTunnelClient(base_url="http://localhost:8080") as client:
  overview = client.cluster.get_overview({"jobId": "12345"})
  print(overview)

get_overview 的 params 是一个可选的字典,会被原样转发为 GET /overview 的查询参数。REST API 支持任意 tag 键值对作为过滤条件,例如按 jobId、pipelineId 过滤。测试 test_overview_forwards_filter_query_params 验证了 {"jobId": "12345", "pipelineId": "daily"} 会完整透传为查询参数。服务端对应的 OverviewServlet 位于 seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/rest/servlet/OverviewServlet.java。

5.2 集群指标

get_metrics() 请求 GET /openmetrics,返回 Prometheus 格式的节点指标:

with SeaTunnelClient(base_url="http://localhost:8080") as client:
  metrics = client.cluster.get_metrics()
  print(metrics)

注意该方法返回的是文本格式(Content-Type: text/plain),SDK 会根据响应头判断:仅当 Content-Type 包含 application/json 时才解析为 JSON,否则原样返回文本(见 client.py)。

5.3 日志查询

  • 单节点日志:get_log() 请求 GET /log,返回单个节点的日志内容。
  • 全节点日志:get_logs(jobId=None) 请求 GET /logs;传入 jobId 时改为请求 GET /logs/{jobId},并对所有请求附加 format=json 参数(cluster.py):
with SeaTunnelClient(base_url="http://localhost:8080") as client:
  all_logs = client.cluster.get_logs()                      # GET /logs?format=json
  job_logs = client.cluster.get_logs(jobId=12345)           # GET /logs/12345?format=json

测试 test_get_logs_with_job_id_uses_path_segment_contract 专门验证了带 jobId 时使用路径段而非查询参数的契约。

六、扩展 API:配置加密与系统信息

除文档列出的 Jobs/Cluster 之外,SDK 还封装了两组端点(未写入官方文档,但从源码可确认):

  • 配置加密(client.config):encrypt_config(conf) 发送 POST /encrypt-config,将配置字符串中的敏感信息(如密码)加密,对应服务端 REST_URL_ENCRYPT_CONFIG:
with SeaTunnelClient(base_url="http://localhost:8080") as client:
  encrypted = client.config.encrypt_config(config)
  print(encrypted)
  • 系统监控信息(client.system):get_system_info() 请求 GET /system-monitoring-information,返回系统监控信息:
with SeaTunnelClient(base_url="http://localhost:8080") as client:
  info = client.system.get_system_info()
  print(info)

七、错误处理与连接管理

SDK 在 Client.request 中统一处理了传输层与 HTTP 层的错误(client.py),定义了两类异常:

  • SeaTunnelConnectionError:网络连接失败(httpx.RequestError),错误信息中包含目标 URL。
  • SeaTunnelAPIError:服务端返回 4xx/5xx,携带 status_code 与 message 属性。SDK 会优先尝试从响应 JSON 中提取 message 字段,提取失败则回退到原始响应文本。
from seatunnel import SeaTunnelClient, SubmitJobQueryParams
from seatunnel.client import SeaTunnelAPIError, SeaTunnelConnectionError

with SeaTunnelClient(base_url="http://localhost:8080") as client:
  try:
    resp = client.jobs.submit_job("env {}", SubmitJobQueryParams())
  except SeaTunnelAPIError as e:
    print(f"API error: status={e.status_code}, message={e.message}")
  except SeaTunnelConnectionError as e:
    print(f"Connection error: {e}")

相关测试 test_http_status_error_uses_response_message_and_preserves_cause 与 test_request_error_is_wrapped_as_connection_error 分别验证了两种异常的行为。

八、API 参考速查

Client

SeaTunnelClient(base_url: str)

  • base_url:SeaTunnel Engine 的地址,例如 http://127.0.0.1:8080(默认端口由 config/seatunnel.yaml 的 http.port 决定)。

Jobs(client.jobs)

方法 底层端点 说明
submit_job(conf, params) POST /submit-job 用配置字符串提交作业
submit_job_from_file(filePath, params) POST /submit-job/upload 用配置文件上传提交作业
submit_jobs(confs) POST /submit-jobs 批量提交作业
stop_job(params) POST /stop-job 停止单个作业
stop_jobs(params: list) POST /stop-jobs 批量停止作业
get_running_jobs() GET /running-jobs 获取运行中的作业列表
get_job_details(jobId) GET /job-info/{jobId} 获取指定作业详情
get_finished_jobs_info(state=None) GET /finished-jobs/{jobStatus} 获取已结束作业,可按状态过滤

Cluster(client.cluster)

方法 底层端点 说明
get_overview(params=None) GET /overview 集群概览,字典参数原样作为查询参数透传
get_metrics() GET /openmetrics 获取集群节点指标
get_log() GET /log 获取单个节点的日志
get_logs(jobId=None) GET /logs 或 GET /logs/{jobId} 获取所有节点日志,可按作业 ID 过滤

Helper 类

  • SubmitJobQueryParams:jobId / jobName / isStartWithSavePoint(均可选),format 默认 "hocon";
  • SubmitJobFileQueryParams:jobId / jobName / isStartWithSavePoint(均可选),用于文件上传提交;
  • StopJobQueryParams:jobId(必填)、isStartWithSavePoint(必填);
  • JobStatus:FINISHED / CANCELED / FAILED / SAVEPOINT_DONE / UNKNOWABLE。

九、小结

SeaTunnel Python SDK 以极小的学习成本把 Zeta 引擎的 REST 能力带给了 Python 生态:一条 with SeaTunnelClient(...) as client 即可完成作业提交、状态轮询、批量停止与集群监控,配合 SDK 自带的 SeaTunnelAPIError / SeaTunnelConnectionError 异常体系,可以可靠地集成进 Python 调度与自动化平台。上述所有方法与参数语义均有 tools/seatunnel-python-sdk 源码及 test_sdk.py 测试用例支撑,服务端 URL 契约可在 RestConstant.java 中交叉核对,便于读者深入源码继续探索。

登录后查看全文
seatunnel