SeaTunnel Python SDK 实战:用 Python 驱动 Zeta 引擎的作业提交、管理与集群监控
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 中交叉核对,便于读者深入源码继续探索。