OpenMetadata SSRS 连接器实战指南：从 REST API 接入配置到报表元数据与血缘提取

OpenMetadata SSRS 连接器实战指南：从 REST API 接入配置到报表元数据与血缘提取

【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata

本文基于 OpenMetadata 仓库中的 SSRS（SQL Server Reporting Services）连接器文档与源码，系统讲解如何在 OpenMetadata 中接入 SSRS 报表服务器：涵盖权限前置要求、完整的连接参数说明（Host/Port、域账号、SSL 校验等）、底层 REST API 调用机制（NTLM 认证、OData 分页、RDL 解析），以及如何通过元数据摄取流水线将 SSRS 报表、图表、数据集与血缘关系同步到 OpenMetadata。读完本文，你将能够独立完成 SSRS 服务的连接配置、连通性测试，并理解摄取过程的内部原理，便于排查问题与二次开发。

SSRS 连接器能做什么

SSRS 是微软提供的本地化（on-premises）报表服务，用于创建、部署和管理分页报表。OpenMetadata 的 SSRS 连接器通过报表服务器的 REST API v2.0 读取目录信息，将报表与文件夹以标准化的元数据实体导入 OpenMetadata：

• Dashboard（报表）：每个 SSRS 报表作为一个 Dashboard 实体，包含名称、描述、路径、访问 URL 与所有者信息；
• Chart（图表）：每个报表同时生成一个 Chart 实体（ChartType.Other），便于在图表维度统一检索；
• Dashboard Data Model（数据集）：解析报表 RDL 定义中的 DataSet，生成SsrsDataModel类型的数据模型，包含查询 SQL 与字段（SSRS Field）列；
• Lineage（血缘）：解析数据集查询语句，与 OpenMetadata 中已登记的数据库表建立「表 → 报表/数据模型」的血缘关系。

上述行为可在摄取源码 ingestion/src/metadata/ingestion/source/dashboard/ssrs/metadata.py 中得到印证：yield_dashboard、yield_dashboard_chart、yield_datamodel与yield_dashboard_lineage_details分别对应这四类实体的产出逻辑。

接入前置要求（Requirements）

要访问 SSRS REST API 并将报表导入 OpenMetadata，需要准备一个在 SSRS 实例上具有相应权限的服务账号：

• 该账号在 SSRS 门户上至少需要Browser（浏览者）角色，才能列出报表与文件夹；
• 若希望完整提取元数据（包括数据源信息），建议授予Content Manager（内容管理员）角色；
• 报表服务器必须启用SSRS REST API v2.0（SSRS 2017 及更高版本提供）。

关于权限要求的细节，同时可以在 openmetadata-ui/src/main/resources/ui/public/locales/en-US/Dashboard/Ssrs.md 中查看。

从源码看，客户端在test_access中请求/Folders、在test_get_reports中请求/Reports端点（见 client.py），因此该账号至少需要能访问这两个 OData 资源，否则连接测试会直接失败。

连接参数详解（Connection Details）

SSRS 连接的所有配置项定义在 JSON Schema ssrsConnection.json 中。其中hostPort、username、password为必填项（required数组），其余参数可选。下面逐一说明。

Host and Port（hostPort）

SSRS 报表服务器实例的基础 URL，格式为 URI，例如：

http://ssrs.example.com/reports https://ssrs.example.com/Reports

客户端会基于该地址拼接 REST API 路径：{hostPort}/api/v2.0（源码常量API_VERSION = "api/v2.0"）。报表的访问 URL 则形如{hostPort}/report{report.path}。

Username（username）

用于连接 SSRS 的用户名。SSRS 通常使用 Windows 身份验证，因此：

• 域账号格式：DOMAIN\username（如CORP\report_user）；
• 本地账号格式：直接写username。

该账号需要有报表服务器上的相应权限（见上文 Requirements）。从源码 client.py 可见，客户端使用requests_ntlm的HttpNtlmAuth(username, password)进行 NTLM 身份认证，这正是 Windows 域集成认证的标准做法。

Password（password）

连接所用用户账号的密码。在 JSON Schema 中该字段类型为password，在 OpenMetadata UI 与 API 中均会作为敏感信息加密存储，配置时不会明文展示。

Verify SSL（verifySSL）

控制连接 SSRS 时是否校验 SSL 证书，可选值如下：

该枚举在 verifySSLConfig.json 中统一定义，no-ssl为默认值。在摄取端，connection.py 通过get_verify_ssl_fn(verifySSL)获取对应的校验函数，并将结果作为verify参数传入 requests 会话——即该配置最终映射为 Pythonrequests的证书校验行为。

SSL Config（sslConfig）

当连接启用 SSL 的 SSRS 实例时的客户端 SSL 配置。Schema 中sslConfig类型为oneOf引用validateSSLClientConfig，即启用后需要进一步提供客户端证书相关文件（见下三个参数）。注意sslConfig在 Schema 中标记为mask: true，属于敏感配置。

SSL CA（caCertificate）

用于 SSL 校验的 CA 证书（PEM 格式内容）。配置后，客户端将以该 CA 作为信任链根来验证报表服务器证书，对应validate模式的推荐做法。

SSL Certificate（sslCertificate）

用于客户端认证的 SSL 证书。当 SSRS 服务器要求双向 TLS（mTLS）时，需要同时提供客户端证书与私钥。

SSL Key（sslKey）

与 SSL 证书关联的私钥。私钥必须与sslCertificate中的证书匹配，否则 TLS 握手会失败。

过滤模式（Filter Patterns）

在 UI 文档之外，Schema 还提供了三类过滤参数，用于控制摄取范围（均引用 filterPattern.json 中的filterPattern定义，支持正则表达式包含/排除）：

• dashboardFilterPattern：按正则包含或排除符合模式的报表；
• chartFilterPattern：按正则包含或排除符合模式的图表；
• projectFilterPattern：按正则包含或排除符合条件的项目（SSRS 中对应文件夹路径，见下文「项目名解析」）。

连接与认证的底层机制

了解了配置项之后，再看客户端如何真正建立连接。核心实现位于 ingestion/src/metadata/ingestion/source/dashboard/ssrs/client.py，要点如下：

• NTLM 认证：使用requests_ntlm.HttpNtlmAuth处理 Windows 集成认证，因此账号必须属于报表服务器所在域或本地账号体系；
• OData 分页：/Folders与/Reports均按$top=100、$skip递增方式分页拉取，$orderby=Id保证顺序稳定；报表列表通过$select仅取Id,Name,Path,Description,Type,Hidden,HasDataSources,CreatedBy字段，文件夹取Id,Name,Path；
• 超时与重试：连接超时 10 秒、读超时 120 秒；对500/502/503/504状态码最多重试 2 次，退避因子为 1，仅对 GET 请求生效；
• 隐藏报表处理：摄取时若Hidden=true，该报表会被过滤并记录状态（见 metadata.py 中get_dashboards_list）；
• RDL 内容获取：依次尝试/Reports({id})/Content/$value与/CatalogItems({id})/Content两个路径拉取报表定义；仅 404 会静默降级，其余错误（401/403/5xx）抛出异常，避免在 SSRS 瞬时故障时误删实体；同时通过 Content-Length 预检与流式读取限制，单个 RDL 超过 50 MB 会被跳过，防止内存溢出。

连接测试在 connection.py 中定义了两个步骤：

元数据摄取流程与实体映射

摄取端入口在 ingestion/src/metadata/ingestion/source/dashboard/ssrs/service_spec.py：ServiceSpec = BaseSpec(metadata_source_class=SsrsSource, connection_class=SsrsConnection)，将连接类与元数据源类绑定为「SSRS」服务类型。整体流程如下：

1. Prepare：调用get_folders()拉取全部文件夹，构建{folder.path: folder.name}映射，用于后续项目名解析；
2. 列表提取：get_dashboards_list()遍历/Reports，过滤隐藏报表；
3. 报表实体：yield_dashboard以报表Id作为实体名，displayName使用报表Name，sourceUrl拼接为{hostPort}/report{path}；报表CreatedBy（形如DOMAIN\user）会被归一化为 OpenMetadata 用户并尝试解析为所有者（includeOwners开启时）；
4. 图表实体：yield_dashboard_chart为每个报表生成一个名为{reportId}_chart的 Chart 实体，类型为Other；
5. 数据模型：yield_datamodel在includeDataModels开启时解析报表 RDL，为每个 DataSet 生成名为{reportId}.{datasetName}的SsrsDataModel实体，包含查询 SQL（跳过StoredProcedure与Expression两种 CommandType）以及字段列（dataType=UNKNOWN，显示为SSRS Field）；
6. 血缘：yield_dashboard_lineage_details基于数据集CommandText使用LineageParser解析出源表，通过 ES FQN 搜索在任意数据库服务中定位表实体，再建立「表 → 数据模型/报表」的血缘边。血缘方言由数据库服务类型或 RDL 中 DataProvider 推断（SQL→TSQL、ORACLE、MYSQL、POSTGRESQL等映射见 metadata.py 的DATA_PROVIDER_DIALECT），缺省回退为 TSQL。

项目名（Project）解析

SSRS 报表的Path形如/Sales/Region/ReportA，get_project_name会取路径的父目录（如/Sales/Region）去folder_path_map中查找对应文件夹名，作为报表的 project 归属——这就是projectFilterPattern过滤与 UI 中「Project」字段的来源。

RDL 解析的安全与兼容设计

RDL（Report Definition Language）是报表定义的 XML 文档，解析实现在 ingestion/src/metadata/ingestion/source/dashboard/ssrs/rdl_parser.py。该模块有两个值得注意的设计：

• 跨版本兼容：不同 SSRS 版本的 RDL 命名空间不同（2008/2010/2016+），解析器按元素「局部名（local name）」遍历，忽略命名空间前缀差异；
• 安全防护：解析前会检查文档中是否包含<!doctype或<!entity声明，一旦存在直接拒绝解析，防止「billion laughs」实体扩展攻击（Python 标准库 ElementTree 会解析内部实体，因此需要显式拦截）；单个报表 RDL 解析失败（ValueError）仅跳过该报表并告警，不会中断整个摄取任务。

端到端配置示例

在 OpenMetadata 中新建 SSRS 服务的连接配置（YAML 形式，等价于 UI 表单填写内容）如下：

source: type: ssrs serviceName: ssrs_prod serviceConnection: config: type: Ssrs hostPort: http://ssrs.example.com/reports username: DOMAIN\report_reader password: <secret> verifySSL: validate sslConfig: certificateAuthority: | -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE----- # dashboardFilterPattern: # excludes: # - ".*archived.*" # chartFilterPattern: # includes: # - ".*" sourceConfig: config: type: DashboardMetadata includeOwners: true includeDataModels: true dbServiceNames: - mssql_warehouse sink: type: metadata-rest config: {} workflowConfig: openMetadataServerConfig: hostPort: http://localhost:8585/api authProvider: openmetadata securityConfig: jwtToken: <token>

该配置与单元测试 ingestion/tests/unit/topology/dashboard/test_ssrs.py 中的 mock 配置结构一致（type: ssrs、hostPort、username、password、DashboardMetadata源类型），可作为排查问题时的对照基准。要点说明：

• verifySSL在生产环境建议validate并配置 CA；仅开发联调时才使用ignore或no-ssl；
• includeDataModels控制是否解析 RDL 生成数据集模型，includeOwners控制是否尝试将报表CreatedBy映射为所有者；
• dbServiceNames用于血缘解析时限定查询的数据库服务范围，帮助定位源表。

常见问题与排查建议

• 连接测试失败（CheckAccess）：优先检查账号是否为域账号、密码是否正确、账号是否具备 Browser 及以上角色，以及hostPort是否可达且开启了 REST API v2.0（SSRS 2017+）；
• 报表列表为空：确认账号能访问/Reports资源；若报表设置了 Hidden，摄取会按设计跳过，可在运行状态中看到 "Hidden report" 过滤记录；
• 数据模型缺失：检查是否开启了includeDataModels，以及报表 RDL 是否包含 DataSet（无数据源/共享数据集的报表不会产出模型）；
• 血缘未生成：SSRS 侧数据集必须包含CommandText且CommandType不是StoredProcedure/Expression，数据提供方不是 MDX 系列（OLEDB-MD/ADOMD/SAPBW），且查询引用的源表需已存在于 OpenMetadata 中并可通过 FQN 搜索到；
• SSL 相关报错：validate模式下需确保 CA 证书正确；自签名证书环境可先使用ignore验证连通性，再切换回validate补齐证书配置。

需要进一步参考的仓库资源：SSRS 连接 Schema、SSRS 客户端实现、SSRS 摄取源、RDL 解析器 以及 SSRS 单元测试。

【免费下载链接】OpenMetadataThe Open Context Layer for Data and AI , OpenMetadata is the open platform for building trusted data context and business semantics for humans, AI assistants, and agents.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMetadata