企业官网建设流程全解析

OpenMetadata Mode 仪表盘连接器接入指南：配置、元数据映射与血缘原理

【免费下载链接】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 中 Mode 仪表盘（Dashboard）连接器的完整接入指南，涵盖前置要求、元数据映射规则、连接参数详解、凭据获取、连接测试以及基于源码的底层实现原理。读完本文，你将能够在 OpenMetadata 中完成 Mode 服务的创建与配置，理解报告、图表、查询数据模型与血缘的对应关系，并掌握filterQueryParam等关键参数的实战含义。

前置要求：Mode Business Workspace

OpenMetadata 的 Mode 连接器完全依赖 Mode 官方 API，而该 API仅对 Mode Business Workspace 的成员开放。这意味着：

• 只有归属于 Mode Business Workspace 的资源才能通过 API 被访问和采集；
• 如果你的 Mode 账号属于非 Business 类型的 Workspace，将无法使用本连接器完成元数据采集；
• 采集范围受 API Token 可见性约束——连接器只能采集 Token 所属工作区成员可见的 spaces（空间）、reports（报告）、queries（查询）、charts（图表）和 data sources（数据源）。

因此在创建连接器之前，请先确认你的 Mode 实例满足 Business Workspace 条件，并准备好一个对该工作区拥有充分访问权限的 API Token。

元数据映射：Mode 对象如何进入 OpenMetadata

Mode 连接器的核心工作是将其领域模型翻译为 OpenMetadata 的实体模型。根据 Mode.md 文档与 mode/metadata.py 的实现，映射关系如下：

关于血缘链路有一个值得注意的降级逻辑：如果数据模型采集被禁用（includeDataModels=false），或者某个查询数据模型被过滤规则排除，血缘会直接从底层表指向报告仪表盘，跳过了数据模型这一跳。这一逻辑在_resolve_lineage_target方法中实现：优先解析数据模型，解析失败或未启用时回退到 Dashboard 本身。

从源码结构可以确认，Mode 源通过ModeSource(DashboardServiceSource)继承通用仪表盘采集框架，逐项产出仪表盘、图表、数据模型与血缘请求，其工作流入口注册在 mode/service_spec.py 中。

连接参数详解

Mode 连接的完整参数定义在 JSON Schema modeConnection.json 中。其中accessToken、accessTokenPassword、workspaceName为必填项，其余为可选项。

Host Port（hostPort）

指定 Mode 服务器的地址与端口，以 URI 字符串形式填写，格式为https://app.mode.com。Schema 中该字段的默认值即为https://app.mode.com，对于自托管或私有化部署的 Mode 实例，请替换为实际的访问地址。OpenMetadata 在构造客户端时会通过clean_uri对地址做规范化处理（见 client.py），并以其为基准拼接后续所有 API 路径。

Access Token（accessToken）与 Access Token Password（accessTokenPassword）

这两个字段是 Mode API 的认证凭据，生成步骤如下：

1. 登录 Mode 实例首页；
2. 点击左上角你的名字，进入My Account；
3. 在左侧菜单中选择API Tokens；
4. 输入 Token 名称，点击Create token生成新的 API Token 与密码；
5. 复制生成的 Access Token 与对应的密码。

从源码可以看到，ModeApiClient 在构造时会将accessToken与accessTokenPassword以冒号拼接后做 Base64 编码，再以 HTTP Basic 认证方式（auth_token_mode="Basic"）注入Authorization请求头。这意味着：

• Access Token 相当于 Basic Auth 中的用户名，Access Token Password 相当于密码，两者必须配对使用；
• 在 OpenMetadata UI 中accessTokenPassword以密码字段（format: "password"）存储，录入与展示时会受到加密与脱敏保护。

Workspace Name（workspaceName）

Mode 工作区名称，用于在 API 路径中定位具体工作区。Mode 的所有资源（spaces、reports、queries、data sources）都隶属于某个工作区，OpenMetadata 的采集请求路径形如/{workspace_name}/spaces、/{workspace_name}/reports/{report_token}/queries等，因此该字段必须与 API Token 所属的工作区一致，否则会因权限或路径不存在而采集失败。连接测试步骤CheckDashboards正是通过调用get_workspace(workspaceName)来验证该字段的有效性（见 mode/connection.py）。

Filter Query Param（filterQueryParam）

该值会作为filter查询参数传递给 Mode 的 spaces API，用于在发现报告时对空间列表进行过滤。支持的取值为：

• all：获取所有空间（默认值）；
• custom：仅获取自定义空间。

如果该字段留空，OpenMetadata 会默认使用all。这一默认行为在 metadata.py 的get_dashboards_list方法中实现：filter_param = "all" if not self.filter_query_param else self.filter_query_param。同时，client.py 的fetch_all_reports会对取值做校验，一旦传入除custom、all之外的值，会抛出ValueError，提示期望的合法取值。

过滤模式（Filter Patterns）

除上述参数外，连接配置还支持四类正则过滤模式，用于控制采集范围（均定义在 modeConnection.json）：

• dashboardFilterPattern：按名称正则包含/排除要采集的仪表盘；
• chartFilterPattern：按名称正则包含/排除图表；
• dataModelFilterPattern：按名称正则包含/排除查询数据模型；
• projectFilterPattern：按名称正则包含/排除项目。

其中dataModelFilterPattern对血缘链路有直接影响：被过滤掉的查询数据模型不会生成实体，其血缘目标会按前述降级逻辑回退到报告仪表盘。图表与数据模型的过滤判定分别发生在yield_dashboard_chart与yield_datamodel中，命中过滤规则时会在采集状态（status）中记录 "Chart Pattern not Allowed" 或 "Data model filtered out"。

完整连接配置示例

以下是一个可直接使用的 Mode 服务配置（YAML）示例，字段结构依据 modeConnection.json 整理：

source: type: mode serviceName: mode_prod serviceConnection: config: type: Mode hostPort: https://app.mode.com accessToken: <你的 Access Token> accessTokenPassword: <你的 Token 密码> workspaceName: my-company-workspace filterQueryParam: all # 可选：all / custom，留空默认 all # dashboardFilterPattern: # includes: [".*"] # excludes: ["temp_.*"] # chartFilterPattern: # includes: [".*"] # excludes: [] # dataModelFilterPattern: # includes: [".*"] # excludes: [] # projectFilterPattern: # includes: [".*"] # excludes: [] sourceConfig: config: type: DashboardMetadata includeDataModels: true # 关闭后查询将不再生成为数据模型 includeCharts: true includeOwners: true sink: type: metadata-rest config: {} workflowConfig: openMetadataServerConfig: hostPort: http://localhost:8585/api authProvider: openmetadata securityConfig: jwtToken: <服务账号 JWT Token>

实际使用中，在 OpenMetadata UI 的 Settings → Services → Dashboard 中新建 Mode 服务并逐项填写上述字段即可，平台会自动生成等价的配置。

连接测试与底层实现

创建服务或配置自动化工作流时，OpenMetadata 会执行连接测试。Mode 的测试逻辑集中在 mode/connection.py：

• ModeConnection继承通用BaseConnection[ModeConnectionConfig, ModeApiClient]，_get_client负责基于连接配置构造ModeApiClient；
• test_connection通过test_connection_steps执行名为CheckDashboards的单一测试步骤，其函数体为client.get_workspace(service_connection.workspaceName)；
• 测试超时默认设置为 3 分钟（THREE_MIN）。

也就是说，连接测试本质上就是调用一次/{workspace_name}接口，验证 Token、密码、工作区名三者的组合是否有效。对应地，test_connection.py 中的单元测试覆盖了ModeConnection继承关系、客户端构建以及测试步骤的执行路径。

连接成功后，采集阶段会调用以下 API 端点（见 client.py）：

采集报告时采用分页策略：每页固定请求 30 条报告（REPORTS_PAGE_SIZE = 30），当返回条数小于 30 时认为该空间遍历完毕；若连续两页返回相同内容，会抛出 "Mode returned the same report page twice" 异常以防御死循环。这些行为均有对应的单元测试验证，见 test_client.py（如 "paginates every space"、"requests page after exactly thirty results" 等用例）。

血缘解析原理

Mode 连接器的血缘采集是整套实现中最有技术含量的部分，其链路为：底层数据表 → 查询数据模型 → 报告仪表盘。整个流程在 metadata.py 的yield_dashboard_lineage_details中完成，大致分为以下步骤：

1. 解析数据源：从每条查询中取出data_source_id，在get_all_data_sources预取的数据源字典中定位对应的数据库名称（database字段）；
2. 解析 SQL：使用LineageParser对查询的raw_query做 SQL 解析，提取source_tables源表集合；
3. 限定搜索范围：将数据源的数据库名、查询解析出的 schema/table 名与可选的数据库服务前缀（db_service_prefix）组合，通过build_es_fqn_search_string构造全文检索串，在 OpenMetadata 中搜索匹配的 Table 实体；
4. 确定血缘目标：调用_resolve_lineage_target，在数据模型采集启用且数据模型已入库的情况下以查询数据模型为血缘终点（to_entity），否则回退为报告仪表盘；
5. 产出血缘：为每个匹配到的源表生成AddLineageRequest。

从实现细节可以推断，血缘解析的质量直接取决于查询是否带有data_source_id、数据源是否提供数据库名称、以及源表在 OpenMetadata 中是否已被其他数据库连接器采集入库。若数据源缺库名或查询缺 SQL，对应查询会被跳过并在日志中给出 warning，不会中断整体采集。

使用限制与注意事项

结合文档与源码，使用 Mode 连接器时有以下几点需要特别留意：

• Business Workspace 强依赖：非 Business 工作区无法调用 Mode API，这是连接器生效的硬性前提；
• 数据模型列信息缺失：Mode 查询 API 不返回结果列元数据，因此所有查询数据模型的columns列表为空，这是上游 API 的限制而非 OpenMetadata 的问题；
• 可见性边界：只能采集 API Token 可见的空间、报告、查询、图表与数据源。如果希望完整编目整个工作区，请确保 Token 对应的工作区成员对每个空间与报告都有访问权限；
• 采集范围受过滤规则影响：filterQueryParam与四类 Filter Pattern 会改变最终入库的实体集合，配置血缘相关需求时请留意dataModelFilterPattern对链路形态的副作用；
• 血缘依赖已有表实体：表 → 数据模型/仪表盘的血缘需要先在 OpenMetadata 中通过对应的数据库连接器将底层表采集入库，否则 SQL 解析出的源表无法被检索匹配。

相关代码与测试索引

• 连接器配置文档：Mode.md
• 连接参数 Schema：modeConnection.json
• 客户端与认证实现：mode/client.py
• 采集主逻辑：mode/metadata.py
• 连接测试实现：mode/connection.py
• 服务注册入口：mode/service_spec.py
• 连接单元测试：test_connection.py
• 客户端单元测试：test_client.py
• 拓扑级单元测试：test_mode.py

以上源码与测试共同构成了 Mode 连接器的完整证据链：从 UI 表单参数到 JSON Schema 校验，从 Basic Auth 客户端到分页采集与血缘解析，读者可沿着这些文件深入理解连接器的每一个细节，并在排查采集问题时快速定位到对应代码路径。

【免费下载链接】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