# 通过Flink SQL Gateway提交作业
#### 概述
Flink SQL Gateway是Flink提供的交互式SQL查询服务，以常驻服务形式运行在Flink引擎上，对外提供HTTP REST API。用户通过curl、Postman等工具调用API即可提交SQL语句并获取结果，无需安装Flink CLI或编写Java/Python代码。与普通Flink作业"提交即运行、运行完退出"不同，SQL Gateway常驻运行，支持随时打开会话、提交语句、获取结果。
图1Flink SQL Gateway工作原理   
![](https://support.huaweicloud.com/usermanual-aidatalake/zh-cn_image_0000002810627529.png "点击放大")
#### 前提条件
在创建Flink SQL Gateway作业前，请提前在对应工作空间中创建Flink类型的端点。操作详情请参见[创建Flink引擎端点](https://support.huaweicloud.com/usermanual-aidatalake/aidatalake_01_0129.html)。
#### 步骤一：创建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
      }
    }
  }
  ```
  表1Flink 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](https://nightlies.apache.org/flink/flink-docs-release-1.20/docs/dev/table/sql-gateway/overview/#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作业详情](https://support.huaweicloud.com/api-aidatalake/ShowFlinkJob.html)接口轮询作业状态，确认作业进入运行状态后才能继续[步骤二：使用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调试]和[使用示例：血缘分析]，接口详情请参见[接口参考]。
1. **获取访问地址** ：SQL Gateway以REST API形式对外暴露，完整访问地址由URL和请求头组成：
   - **URL**：http://{入口IP}:{端口}/v3/sessions/...
   
   - **请求头**：Host: sql-gateway-{jobId}；Authorization: Bearer {token}（未配置Token时可不传）
   
   
   各参数说明及获取方式：
   
   | 参数             | 说明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
   |:---|:---|
   | 入口IP            | 网络接入后得到的VPC终端节点IP。您可以参考[网络接入](https://support.huaweicloud.com/usermanual-aidatalake/aidatalake_01_0025.html)得到VPC终端节点IP地址。 - 通过ECS访问终端节点IP，此时终端节点IP即为入口IP，具体请参考[通过节点IP或内网域名访问接口型终端节点](https://support.huaweicloud.com/usermanual-vpcep/vpcep_03_0202.html)。  - 通过绑定ELB间接访问终端节点IP，此时ELB访问地址即为入口IP。 1. 添加TCP类型监听器。  2. 监听器添加后端服务器组。  3. 后端服务器组的"IP类型后端"中添加VPC终端节点IP。  4. 为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。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
      
   
2. **配置客户端证书** （仅SSL开启时）：若创建端点时开启了SSL认证，客户端须配置客户端证书才能连接，否则连接会被拒绝。
   若未开启SSL认证，跳过证书配置，使用http协议和34000端口访问即可。未配置Token时，去掉curl命令中的-H "Authorization: Bearer {token}"。
   1. **下载证书** ：在端点管理页面下载客户端证书包，包含ca.crt（CA证书）、client.key（客户端私钥）、client.crt（客户端证书）三个文件。证书下载参考[网络接入](https://support.huaweicloud.com/usermanual-aidatalake/aidatalake_01_0025.html)。
   
   2. **上传证书**：将证书包上传到执行curl请求的机器，记录证书文件所在目录路径。
   
   3. **配置证书** ：使用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}"
      ```
      
     
3. **创建会话** ：调用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":""}
     
    
4. **执行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 ...\"}"
     ```
     
    
5. **获取结果** ：调用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}"
   ```
   - 普通会话：获取查询数据。
   
   - 血缘分析：获取血缘分析结果（含表级和列级血缘关系）。
     
6. **关闭会话** ：调用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}"
  ```
  ![](https://support.huaweicloud.com/usermanual-aidatalake/public_sys-resources/note_3.0-zh-cn.png)
  未配置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（例如建表）不会产生血缘关系。
  
  - 血缘分析要求语句引用的表和列真实存在。
   
- **操作步骤**
  1. 打开一个血缘会话：调用POST /v3/sessions，请求体中携带{"properties":{"table.validate":"true","table.lineage":"true"}}。
  
  2. 建表：调用POST /v3/sessions/{sessionHandle}/statements，请求体为{"statement":"CREATE TABLE ..."}。
  
  3. 提交血缘分析请求：调用POST /v3/sessions/{sessionHandle}/verify-statements，请求体为{"statement":"INSERT INTO ... SELECT ..."}。
  
  
  ![](https://support.huaweicloud.com/usermanual-aidatalake/public_sys-resources/note_3.0-zh-cn.png)
  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](https://support.huaweicloud.com/devg-aidatalake/aidatalake_05_0111.html)和[管理Iceberg Catalog](https://support.huaweicloud.com/devg-aidatalake/aidatalake_05_0105.html)。
  **返回字段说明**
  表3血缘返回字段说明 
  | 字段                 | 含义                                                       |
  |:---|:---|
  | verifyResult       | Success表示成功；Failure表示失败，此时原因记录在verifyException中，内容为错误文字。 |
  | verifyException    | 血缘分析结果JSON字符串。                                           |
  | nodes              | 本语句涉及的表节点，包含列定义等信息。                                      |
  | tableLineageInfos  | 表级血缘，记录tableSource到tableDestination的对应关系。                |
  | columnLineageInfos | 列级血缘，记录columnSource到columnDestination的对应关系。              |
     
  
 
 #### 接口参考
开源接口的完整说明请参见[REST Endpoint \| Apache Flink](https://nightlies.apache.org/flink/flink-docs-release-1.20/docs/dev/table/sql-gateway/rest/)，血缘分析接口的用法参见[使用示例：血缘分析]。
表4SQL Gateway常用接口 
| 用途         | 方法 + 路径                                                                               |
|:---|:---|
| 版本与连通性检查   | 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}                                                  |
   
