通过Flink SQL Gateway提交作业
概述
Flink SQL Gateway是Flink提供的交互式SQL查询服务,以常驻服务形式运行在Flink引擎上,对外提供HTTP REST API。用户通过curl、Postman等工具调用API即可提交SQL语句并获取结果,无需安装Flink CLI或编写Java/Python代码。与普通Flink作业“提交即运行、运行完退出”不同,SQL Gateway常驻运行,支持随时打开会话、提交语句、获取结果。
前提条件
在创建Flink SQL Gateway作业前,请提前在对应工作空间中创建Flink类型的端点。操作详情请参见创建Flink引擎端点。
步骤一:创建Flink SQL Gateway作业获取job_id
- 使用须知
- SQL Gateway作业不支持自动调优和SavePoint。
- 取消SQL Gateway作业会直接停止其中运行的所有作业。
- 创建FlinkJob是异步接口,成功响应仅表示创建请求已被接收,响应体中的job_id是后续所有资源名的基准。作业创建后,请通过查看Flink作业详情接口轮询作业状态。
- 创建方法
POST /v2/workspaces/{workspace_id}/flink-jobs { "name" : "test-flink-job", "description" : "测试Flink SQL Gateway作业", "endpoint_name" : "Flink-endpoint-test", "job_agency" : "test-agencys", "execution_mode" : "STREAMING", "job_config" : { "type" : "FLINK_SQL_GATEWAY", "sql_gateway_token" : "xxxxxx", "idle_enabled" : true, "idle_timeout" : 10 }, "image_config": { "image_id": "dd877a59-5cbd-44c5-b8a7-dc464cca****", "image_version_id": "01ae8ee6-af8a-48a8-895b-8d4a70bf****" }, "flink_config" : { "taskmanager.numberOfTaskSlots" : "1" }, "resource_config" : { "parallelism": 2, "jobmanager_resource_spec" : { "cpu" : 1000, "memory" : 4096 }, "taskmanager_resource_spec" : { "cpu" : 1000, "memory" : 4096 }, "sql_gateway_resource_spec" : { "cpu" : 1000, "memory" : 4096 } } }表1 Flink SQL Gateway作业关键参数说明 参数名称
是否必填
说明
name
是
作业名称。
取值范围:1~128字符;须以字母或数字开头、以字母或数字结尾,中间可包含下划线和中划线。
endpoint_name
是
端点名称,用于指定SQL Gateway所连接的Flink端点。
取值范围:1~63字符;只能使用小写字母、数字和中划线,须以小写字母开头、以小写字母或数字结尾。
注意事项:含大写字母的名称(如Flink-endpoint-test)不符合规则,提交时会被参数校验拒绝。
job_config
是
作业配置结构,按作业类型选择对应结构。
提交Flink SQL Gateway作业时,type固定为FLINK_SQL_GATEWAY。
description
否
作业描述信息。
取值范围:1~512字符。
job_agency
否
自定义委托名称,用于授权作业访问OBS等外部资源
execution_mode
否
作业执行模式。
取值范围:STREAMING或BATCH。
默认值:STREAMING。
job_config.sql_gateway_token
否
SQL Gateway鉴权令牌。
调用网关接口时以Authorization: Bearer {token}方式携带。不配置时网关不做鉴权。
取值范围:1~256字符且不能全为空白字符。
job_config.idle_enabled
否
是否开启空闲自动释放。
空闲状态指SQL Gateway内部不存在非终态的作业;创建会话、查看血缘等不执行实际作业的操作不记为非空闲。
取值范围:true或false。
默认值:false。
job_config.idle_timeout
否
空闲超时时间,达到该时间后自动释放SQL Gateway资源。
取值范围:10~1440。
默认值:30。
单位:分钟。
image_config.image_id 与 image_config.image_version_id
否
镜像配置,用于指定作业运行的镜像ID及镜像版本ID。image_config可整体省略,省略时按端点配置自动选择默认镜像。
注意事项:一旦传入image_config,image_id与image_version_id两个字段均必填。
flink_config
否
Flink配置参数,以键值对形式提供。
取值范围:键值对数量不超过100个,单个值长度1~1024字符。
注意事项:不能配置execution.checkpointing.dir、execution.checkpointing.savepoint-dir、high-availability.storageDir等系统保留参数。SQL Gateway配置参数详情请参考SQL Gateway Configuration。
resource_config.parallelism
否
决定SQL Gateway上作业的并行度。
resource
否
SQL Gateway、JobManager和TaskManager的资源配置。
SQL Gateway与JobManager的资源上限为"两者之和"约束,不是分别独立判断。
- JobManager:CPU取值范围500~48000(毫核),默认1000;内存取值范围2048~393216(MB),默认4096。
- TaskManager:CPU与内存的取值范围同JobManager。
- SQL Gateway:CPU取值范围500~47500(毫核),默认1000;内存取值范围2048~391168(MB),默认4096。
- 约束:SQL Gateway与JobManager的CPU之和不超过48000毫核,内存之和不超过393216MB。示例中1000+1000=2000毫核、4096+4096=8192MB,均在限内。
- 确认作业运行状态
创建FlinkJob是异步接口,API返回成功仅表示创建请求已被接受,响应体中返回job_id,此时作业尚未进入运行状态。须通过查看Flink作业详情接口轮询作业状态,确认作业进入运行状态后才能继续步骤二:使用SQL Gateway。
轮询请求:
GET /v2/workspaces/{workspace_id}/flink-jobs/{job_id}响应体中status字段标识作业当前状态,常见取值如下:
表2 状态说明 status
含义
是否可继续后续操作
pending
创建中,资源正在分配
否,需继续轮询
running
运行中,SQL Gateway已就绪
是,可进入步骤二
failed
创建失败
否,需排查失败原因后重新创建
terminated
已终止
否
建议轮询间隔为10~30秒。当status返回running时,表示SQL Gateway服务已启动就绪,记录job_id,进入步骤二:使用SQL Gateway。
步骤二:使用SQL Gateway
作业创建成功并进入运行状态后,即可通过REST API访问SQL Gateway。
以下步骤为最小操作流程,步骤3~步骤6完整curl示例参见使用示例:SQL调试和使用示例:血缘分析,接口详情请参见接口参考。
- 获取访问地址:SQL Gateway以REST API形式对外暴露,完整访问地址由URL和请求头组成:
- URL:http://{入口IP}:{端口}/v3/sessions/...
- 请求头:Host: sql-gateway-{jobId};Authorization: Bearer {token}(未配置Token时可不传)
各参数说明及获取方式:
参数
说明
入口IP
网络接入后得到的VPC终端节点IP。您可以参考网络接入得到VPC终端节点IP地址。
- 通过ECS访问终端节点IP,此时终端节点IP即为入口IP,具体请参考通过节点IP或内网域名访问接口型终端节点。
- 通过绑定ELB间接访问终端节点IP,此时ELB访问地址即为入口IP。
- 添加TCP类型监听器。
- 监听器添加后端服务器组。
- 后端服务器组的“IP类型后端”中添加VPC终端节点IP。
- 为ELB绑定公网IP(可选)。
注意:ECS和ELB要和VPC终端节点在同一个VPC和子网下。
端口
- Flink端点开启SSL认证,使用https:34002
- Flink端点不开启SSL认证,使用http:34000
Host请求头
每次请求须携带Host: sql-gateway-{jobId},其中jobId为创建作业返回的job_id。缺失该头会返回default backend - 404。
Authorization
Token为创建作业时在job_config.sql_gateway_token中设置的值。
未配置Token时网关不做鉴权;配置了Token时,调用网关接口必须在请求头中携带Authorization: Bearer {token},Authorization的值必须精确等于"Bearer加一个空格再加Token明文",区分大小写且逐字节相等,不是"包含"关系,否则返回401。
- 配置客户端证书(仅SSL开启时):若创建端点时开启了SSL认证,客户端须配置客户端证书才能连接,否则连接会被拒绝。 若未开启SSL认证,跳过证书配置,使用http协议和34000端口访问即可。未配置Token时,去掉curl命令中的-H "Authorization: Bearer {token}"。
- 下载证书:在端点管理页面下载客户端证书包,包含ca.crt(CA证书)、client.key(客户端私钥)、client.crt(客户端证书)三个文件。证书下载参考网络接入。
- 上传证书:将证书包上传到执行curl请求的机器,记录证书文件所在目录路径。
- 配置证书:使用Postman等工具导入客户端证书发送请求,或在curl请求中通过以下参数携带客户端证书。
参数
示例
说明
--cacert
/path/to/cert/ca.crt
CA证书路径,用于校验服务端证书。取客户端证书包中的ca.crt。
--cert
/path/to/cert/client.crt
客户端证书路径。取客户端证书包中的client.crt。
--key
/path/to/cert/client.key
客户端私钥路径。取客户端证书包中的client.key。
SSL开启时curl请求示例:
curl -k -s https://100.95.156.172:34002/v3/info \ --cacert /path/to/cert/ca.crt \ --cert /path/to/cert/client.crt \ --key /path/to/cert/client.key \ -H "Host: sql-gateway-{jobId}" \ -H "Authorization: Bearer {token}"
- 创建会话:调用POST /v3/sessions打开会话,获取sessionHandle。
- 普通会话(交互式SQL执行)
curl -s -X POST http://{入口}/v3/sessions -H "Host: sql-gateway-{jobId}" -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d "{\"properties\":{}}"预期返回:{"sessionHandle":""}
- 血缘会话(血缘分析):
curl -s -X POST http://{入口}/v3/sessions -H "Host: sql-gateway-{jobId}" -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d "{\"properties\":{\"table.validate\":\"true\",\"table.lineage\":\"true\"}}"预期返回:{"sessionHandle":""}
- 普通会话(交互式SQL执行)
- 执行SQL:根据场景选择不同的执行方式。
- 普通会话:调用POST /v3/sessions/{sessionHandle}/statements执行DDL/DML语句,获取operationHandle。
curl -s -X POST http://{入口}/v3/sessions/{SID}/statements -H "Host: sql-gateway-{jobId}" -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d "{\"statement\":\"SELECT 1\"}"预期返回:{"operationHandle":""}
- 血缘分析:先调用statements建表,再调用verify-statements提交INSERT...SELECT语句进行血缘分析。
# 建表 curl -s -X POST http://{入口}/v3/sessions/{SID}/statements -H "Host: sql-gateway-{jobId}" -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d "{\"statement\":\"CREATE TABLE ...\"}" # 提交血缘分析 curl -s -X POST http://{入口}/v3/sessions/{SID}/verify-statements -H "Host: sql-gateway-{jobId}" -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d "{\"statement\":\"INSERT INTO ... SELECT ...\"}"
- 普通会话:调用POST /v3/sessions/{sessionHandle}/statements执行DDL/DML语句,获取operationHandle。
- 获取结果:调用GET /v3/sessions/{sessionHandle}/operations/{operationHandle}/result/0获取结果。
curl -s http://{入口}/v3/sessions/{SID}/operations/{OP}/result/0 -H "Host: sql-gateway-{jobId}" -H "Authorization: Bearer {token}"- 普通会话:获取查询数据。
- 血缘分析:获取血缘分析结果(含表级和列级血缘关系)。
- 关闭会话:调用DELETE /v3/sessions/{sessionHandle}关闭会话。
curl -s -X DELETE http://{入口}/v1/sessions/{SID} -H "Host: sql-gateway-{jobId}" -H "Authorization: Bearer {token}"
使用示例:SQL调试
- SQL调试
以下示例演示从打开会话到关闭会话的完整SQL调试流程:
# 连通性 curl -s http://{入口}/v3/info -H "Host: sql-gateway-{jobId}" -H "Authorization: Bearer {token}" # 打开会话 curl -s -X POST http://{入口}/v3/sessions -H "Host: sql-gateway-{jobId}" -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d "{\"properties\":{}}" 预期返回: {"sessionHandle":"<SID>"} # 执行SQL curl -s -X POST http://{入口}/v3/sessions/{SID}/statements -H "Host: sql-gateway-{jobId}" -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d "{\"statement\":\"SELECT 1\"}" 预期返回: {"operationHandle":"<OP>"} # 查询状态 / 获取结果 curl -s http://{入口}/v3/sessions/{SID}/operations/{OP}/status -H "Host: sql-gateway-{jobId}" -H "Authorization: Bearer {token}" curl -s http://{入口}/v3/sessions/{SID}/operations/{OP}/result/0 -H "Host: sql-gateway-{jobId}" -H "Authorization: Bearer {token}" # 关闭会话 curl -s -X DELETE http://{入口}/v1/sessions/{SID} -H "Host: sql-gateway-{jobId}" -H "Authorization: Bearer {token}"
未配置Token时,去掉上述每条命令中的-H "Authorization: Bearer {token}"即可。
使用示例:血缘分析
数据血缘分析是Flink SQL Gateway的核心能力之一,用于分析SQL语句中数据的来源与去向,产出表级和列级血缘关系。血缘分析采用"血缘会话 + verify-statements"两步,不会自动上报,需要显式调用。血缘会话不执行实际作业,仅做语法解析和血缘推导。
- 使用限制
- 一个血缘会话中只允许提交一个修改类语句(例如INSERT INTO)。如需多次修改请使用
EXECUTE STATEMENT SET BEGIN INSERT INTO dst1 SELECT … FROM source; INSERT INTO dst2 SELECT … FROM source; END
- 只执行DDL(例如建表)不会产生血缘关系。
- 血缘分析要求语句引用的表和列真实存在。
- 一个血缘会话中只允许提交一个修改类语句(例如INSERT INTO)。如需多次修改请使用
- 操作步骤
- 打开一个血缘会话:调用POST /v3/sessions,请求体中携带{"properties":{"table.validate":"true","table.lineage":"true"}}。
- 建表:调用POST /v3/sessions/{sessionHandle}/statements,请求体为{"statement":"CREATE TABLE ..."}。
- 提交血缘分析请求:调用POST /v3/sessions/{sessionHandle}/verify-statements,请求体为{"statement":"INSERT INTO ... SELECT ..."}。
table.validate与table.lineage这两个开关默认均为false,开启后会进入校验或血缘模式并跳过作业执行。因此在血缘会话中执行INSERT或SELECT会返回In validation mode, skip submit.,这是预期行为,不是故障。需要跑SQL取数据时请使用普通会话,需要做血缘分析时请使用血缘会话。
- 调用示例
# 打开血缘分析会话 curl -s -X POST http://{入口}/v3/sessions -H "Host: sql-gateway-{jobId}" -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d "{\"properties\":{\"table.validate\":\"true\",\"table.lineage\":\"true\"}}" # 建表 curl -s -X POST http://{入口}/v3/sessions/<SID>/statements -H "Host: sql-gateway-{jobId}" -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d "{\"statement\":\"CREATE TABLE s_o (o BIGINT, c BIGINT, a INT) WITH ('connector'='datagen','number-of-rows'='2')\"}" curl -s -X POST http://{入口}/v3/sessions/<SID>/statements -H "Host: sql-gateway-{jobId}" -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d "{\"statement\":\"CREATE TABLE d_s (cn STRING, a INT) WITH ('connector'='print')\"}" # 执行血缘分析 curl -s -X POST http://{入口}/v3/sessions/<SID>/verify-statements -H "Host: sql-gateway-{jobId}" -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d "{\"statement\":\"INSERT INTO d_s SELECT CAST(c AS STRING), a FROM s_o\"}" 预期返回: { "verifyResult": "Success", "verifyException": "{\"nodes\":{...},\"tableLineageInfos\":[{\"tableSource\":\"...\",\"tableDestination\":\"...\"}],\"columnLineageInfos\":[{\"tableSource\":\"...\",\"tableDestination\":\"...\",\"columnSource\":\"...\",\"columnDestination\":\"...\"}]}" }导入LakeFormation Catalog中已有表进行血缘分析
# 打开血缘分析会话 curl -s -X POST http://{入口}/v3/sessions -H "Host: sql-gateway-{jobId}" -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d "{\"properties\":{\"table.validate\":\"true\",\"table.lineage\":\"true\"}}" # 建立Catalog curl -s -X POST http://{入口}/v3/sessions/<SID>/statements -H "Host: sql-gateway-{jobId}" -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d "{\"statement\":\"CREATE CATALOG lf_flink_catalog WITH ('type'='paimon','metastore'='lakeformation')\"}" # 执行血缘分析 curl -s -X POST http://{入口}/v3/sessions/<SID>/verify-statements -H "Host: sql-gateway-{jobId}" -H "Authorization: Bearer {token}" -H "Content-Type: application/json" -d "{\"statement\":\"INSERT INTO lf_flink_catalog.lf_flink_db.table1 SELECT * FROM lf_flink_catalog.lf_flink_db.table2\"}" lf_flink_catalog.lf_flink_db.table是LakeFormation Catalog中已有表。建立Catalog,管理表具体操作,请参见管理Paimon Catalog和管理Iceberg Catalog。
返回字段说明
表3 血缘返回字段说明 字段
含义
verifyResult
Success表示成功;Failure表示失败,此时原因记录在verifyException中,内容为错误文字。
verifyException
血缘分析结果JSON字符串。
nodes
本语句涉及的表节点,包含列定义等信息。
tableLineageInfos
表级血缘,记录tableSource到tableDestination的对应关系。
columnLineageInfos
列级血缘,记录columnSource到columnDestination的对应关系。
接口参考
开源接口的完整说明请参见REST Endpoint | Apache Flink,血缘分析接口的用法参见使用示例:血缘分析。
| 用途 | 方法 + 路径 |
|---|---|
| 版本与连通性检查 | GET /v3/info |
| 打开会话 | POST /v3/sessions,请求体为{"properties":{}} |
| 打开血缘会话 | POST /v3/sessions,请求体为{"properties":{"table.validate":"true","table.lineage":"true"}} |
| 执行语句 | POST /v3/sessions/{sessionHandle}/statements,请求体为{"statement":"{SQL}"} |
| 查询语句状态 | GET /v3/sessions/{sessionHandle}/operations/{operationHandle}/status |
| 获取结果(第1页) | GET /v3/sessions/{sessionHandle}/operations/{operationHandle}/result/0 |
| 关闭会话 | DELETE /v3/sessions/{sessionHandle} |