nineinchnick/trino-rest

Trino RESTful API连接器镜像文档

镜像概述和主要用途

Trino RESTful API连接器镜像是一个专为Trino分布式SQL查询引擎设计的数据源连接器，用于实现Trino与RESTful API数据源的无缝集成。通过该连接器，用户可直接使用SQL语句查询、过滤、聚合RESTful API返回的数据，无需编写额外API调用代码，简化API数据的集成与分析流程。适用于需要将第三方API数据、内部服务API数据与其他数据源（如数据库、数据仓库）统一查询分析的场景。

核心功能和特性

核心功能

• RESTful API数据源连接：支持标准RESTful API（GET请求为主）的连接与数据获取。
• SQL查询兼容性：支持Trino SQL语法，可执行SELECT、条件过滤（WHERE）、排序（ORDER BY）、聚合（GROUP BY、COUNT、SUM等）操作。
• API认证支持：兼容多种API认证方式，包括API Key（请求头/参数）、Bearer Token、Basic Auth及OAuth 2.0（部分实现）。
• 自定义请求配置：允许配置请求头（Headers）、URL参数（Query Parameters）、超时时间等。

特性

• 配置驱动：通过配置文件定义API连接参数，无需修改代码即可适配不同API。
• 连接池管理：内置HTTP连接池，优化API请求性能。
• 数据类型映射：自动将API返回的JSON数据类型（如string、number、boolean）映射为Trino数据类型（VARCHAR、DOUBLE、BOOLEAN等）。
• 轻量级部署：基于Docker容器化部署，简化依赖管理与环境一致性。

使用场景和适用范围

典型使用场景

• 企业数据集成：将第三方服务API（如CRM、支付系统、物流平台）数据与内部数据库、数据仓库数据合并分析。
• 实时API数据分析：无需ETL流程，直接通过SQL查询实时API数据，支持动态数据分析需求。
• API数据报表生成：基于API返回数据生成业务报表（如用户活跃度、交易统计），无需提前同步数据至数据库。
• 微服务数据查询：在微服务架构中，通过Trino统一查询多个微服务的REST API数据，简化跨服务数据聚合。

适用范围

• 支持返回JSON格式响应的RESTful API（主流API接口格式）。
• 适用于Trino 360+版本（需确认兼容性）。
• 适合中小规模API数据查询（大规模数据建议结合缓存或批处理优化）。

使用方法和配置说明

前置条件

• 已安装Docker环境。
• 已部署Trino集群（独立部署或容器化部署均可）。
• 目标RESTful API的访问权限（包括认证信息、请求格式等）。

Docker部署

1. 获取镜像

bash
docker pull trino-rest-api-connector:latest  # 假设镜像名称为trino-rest-api-connector

2. 准备配置文件

创建连接器配置文件（如rest-api-connector.properties），放置于宿主机目录（如/path/to/config）：

properties
# 基础配置
connector.name=rest-api  # 连接器名称，需唯一
api.url=https://api.example.com/data  # RESTful API基础URL
api.method=GET  # 请求方法（目前仅支持GET）
api.response.json.path=data  # API返回JSON中数据数组的路径（如{"data": [{"id": 1},...]}则填"data"）

# 认证配置（根据API实际认证方式选择）
# 方式1: API Key（请求头）
api.auth.type=api-key
api.auth.header.key=X-API-Key
api.auth.header.value=your-api-key-here

# 方式2: Bearer Token
# api.auth.type=bearer-token
# api.auth.token=your-bearer-token-here

# 方式3: Basic Auth
# api.auth.type=basic-auth
# api.auth.username=your-username
# api.auth.password=your-password

# 连接池配置
http.client.connection.pool.size=10  # 连接池大小
http.client.timeout=30s  # 请求超时时间

# 数据类型映射配置（可选，默认自动映射）
# api.data.type.map=id:BIGINT, name:VARCHAR(255), value:DOUBLE

3. 启动容器（集成到Trino）

通过挂载配置文件启动连接器容器，并确保Trino集群可访问该连接器（通常需将连接器部署在Trino协调器或工作节点可访问的位置，或作为Trino插件集成）：

bash
docker run -d \
  --name trino-rest-api-connector \
  -v /path/to/config:/etc/trino/connector/rest-api \  # 挂载配置文件到容器内Trino连接器目录
  --network trino-network  # 加入Trino集群网络（确保网络互通）
  trino-rest-api-connector:latest

注：实际部署需根据Trino集群的插件管理方式调整（如将连接器JAR包及配置文件放置于Trino的plugin目录，容器化部署可通过卷挂载实现）。

配置参数说明

使用示例

1. 配置示例（连接公开测试API）

假设目标API为JSONPlaceholder的/posts接口（无需认证），配置文件rest-api-connector.properties：

properties
connector.name=rest-api-jsonplaceholder
api.url=https://jsonplaceholder.typicode.com/posts
api.method=GET
api.response.json.path=$  # 该API直接返回数组，无需指定子路径
api.auth.type=none
http.client.connection.pool.size=5
http.client.timeout=15

2. 部署并查询

将配置文件挂载到Trino集群的连接器目录后，重启Trino。通过Trino CLI连接集群，执行查询：

sql
-- 查询API数据
SELECT id, title, body FROM rest_api_jsonplaceholder.default.posts WHERE userId = 1;

说明：rest_api_jsonplaceholder为连接器名称（connector.name），default为默认schema，posts为API对应的表名（通常与API端点名称一致，或通过配置自定义）。

注意事项

• 部分API可能存在请求频率限制，需在配置中合理设置连接池和超时时间，避免触发限流。
• 复杂API响应（如嵌套JSON）可能需要通过api.response.json.path指定数据路径，或在SQL中使用JSON_EXTRACT等函数处理。
• 生产环境建议启用日志配置（通过Trino的日志系统），便于排查API连接或数据解析问题。