DataHub Hex 连接器实战Workspace Token 鉴权、URN 对齐与血缘接入前置配置详解【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub本文聚焦 DataHub 元数据摄入框架中 Hex 数据源的接入前置配置如何在 Hex 应用中获取 workspace 名称、如何签发并授权 Workspace Token含各 read-only scope 的作用与取舍、以及如何通过connection_platform_map让 Hex 上游血缘的 URN 与数仓侧已摄入的 URN 精确对齐。读完后你可以独立完成 Hex → DataHub 的鉴权配置与血缘 URN 对齐并理解连接器在 hex.py 中如何消费这些配置。Hex 连接器type: hex从 Hex REST API 摄入 Hex 的 Projects映射为 Dashboard、Components映射为 Chart、Workspace 容器、归属、标签、使用统计以及到数仓的上游血缘。概念映射关系见 README完整能力说明血缘分层、运行历史、上下文文档、限制与故障排查见 hex_post.md。在配置这些能力之前先要把本篇覆盖的三块前置工作做对否则会出现“能枚举项目但读不到 cell、血缘为零”或“血缘 URN 与数仓 URN 不重合”这类典型问题。前置一确定 workspace_name及其 slug在 Hex 应用界面左上角的 workspace 切换下拉框中每个 workspace 条目前会显示其名称和 slug。配方中workspace_name字段填写的就是该slug 值source: type: hex config: workspace_name: my-workspace # workspace 切换下拉框中显示的 slugworkspace_name在 config.py 中是必填字段HexSourceConfig.workspace_name它决定了 DataHub 侧 Workspace 容器实体的命名——该容器是工作区内所有 Project/Component 的父级 Container。与之容易混淆的是workspace_idHex workspace/org 的 UUID它是可选字段用于构建指向 Hex 应用的 external URL。从 config.py 的字段定义可以看出两者的分工不设置workspace_id连接器会调用/v1/users/me接口自动发现 UUID见 api.py 的fetch_workspace_id但这要求 token 具备Users → Read access权限显式设置workspace_id可以免去授予Users → Read access这一 scope。UUID 可直接从任意 Hex 项目 URL 中读取。如果自动发现失败连接器只会降级为“不输出 externalUrl”并记录一条 warningCould not auto-discover Hex workspace_id不会中断摄入。前置二签发 Workspace Token 并授予只读 scope在哪里签发在 Hex 的Settings → API → Workspace tokens中签发一个Workspace token并将其作为配方中的token字段建议用环境变量注入避免明文入库config: token: ${HEX_TOKEN}必须授予的只读 scope 清单以下 scope 全部为只读连接器从不修改 Hex 中的任何状态因此不需要任何写权限Scope作用Projects → Read access列出 projects/components 并读取其详情与运行历史。注意仅能枚举项目而缺少此 scope 的 token无法读取项目 cell 内容将直接导致血缘为零Cells → Read access读取 SQL cell 内容用于 SQL 解析血缘与上下文文档Read project queried tables使用 Hex 预解析的queriedTables血缘。仅 Hex Enterprise 工作区可用低档位工作区请跳过此 scope——连接器会自动回退到 SQL 解析Data connections → Read access将每个 Hex 数据连接映射到其数仓的 platform/database/schema是上游 URN 拼装的关键输入Users → Read access可选仅用于自动发现构建 external URL 所需的 workspace UUID。若跳过请在配方中显式设置workspace_idtoken字段的 字段定义 中明确要求token 必须具备Read projectsscope 才能访问项目 cell 内容用于血缘提取——“无此 scope 的 token 可以枚举项目但读不到内容”。Workspace Token vs Personal Access TokenPersonal Access TokensPAT也能工作但它以签发用户的权限运行——该用户在 Hex 中看不到的项目会被静默跳过。生产环境的规模化摄入推荐使用 Workspace token。连接器的test_connection能力检查hex.py正是围绕这些权限差异设计的先用/v1/users/me探测连通性Workspace token 在该用户级端点上会返回 500代码会自动回退到/v1/projects作为连通性检查L216-L243分别探测queriedTablesTier 1非 Enterprise 返回 403 即标记不可用与/v1/cellsTier 2并在data-connections不可访问且未配置connection_platform_map时给出明确的失败原因与补救建议——“给 Workspace Token 加Read data connectionsscope或在配方中提供connection_platform_map”还会采样最多 5 个项目走 export API因为它在 cells 被 403 时仍可用解析出各连接 ID 的示例表名拼进失败信息中帮助你快速补齐connection_platform_map条目hex.py。因此建议在正式摄入前先运行datahub ingest --dry-run或 UI 中的 Test Connection按报告逐项修正权限。前置三血缘 URN 对齐Lineage URN Alignment上游 URN 是怎么拼出来的上游血缘 URN 的三个组成要素——platform、database、schema——全部来自 Hex 的/v1/data-connections响应而非猜测或硬编码。具体解析链路api.py 的fetch_connections constants.pytype → platform响应中每条连接的type字段通过CONNECTION_TYPE_TO_DATAHUB_PLATFORM映射到 DataHub platform 名。内置映射覆盖了 19 种连接类型包括 API 枚举中的bigquery/snowflake/redshift/postgres/athena/databricks/trino/clickhouse以及“UI 中存在但 API 枚举缺失”的motherduck → duckdb、alloydb → postgres、cloudsql__postgres → postgres、cloudsql__mysql → mysql、cloudsql__sqlserver → mssql、sqlserver → mssql、starburst → trino等。connectionDetails → 默认限定符CONNECTION_TYPE_DEFAULTS按连接类型定义了从connectionDetails.type中提取default_database/default_schema的键名。例如bigquery取projectId、snowflake取databaseschema、databricks取catalogschemapostgres/redshift在 schema 缺失时回退到publicsqlserver回退到dbodatabricks回退到default。而 MySQL/MariaDB/ClickHouse 这类两段式 URN 平台其database字段实为 schema 槽位因此database_key置None——避免拼出错误的三段式 URN。这些默认限定符用于把 SQL cell 中未加限定的FROM table解析为规范数仓 URN。何时必须配置 connection_platform_map在上述自动解析满足不了时需要配置connection_platform_map以 Hex 的dataConnectionIdUUID 为键文档明确指出两类场景上游数仓是以platform_instance摄入的——需要设置相同的platform_instanceHex 侧拼出的 URN 才能与数仓摄入侧的 URN 重合否则同一张表在 DataHub 中会分裂为两个实体血缘断链Hex 连接类型无法识别连接已删除、自定义类型、或 token 对/v1/data-connections无权限——显式设置platform否则引用该连接的 cell 会被整体跳过。每个键下可覆盖的字段完整定义见 HexConnectionDetail字段说明platformDataHub platform 名。仅在 Hex 连接类型无法自动解析时必填platform_instance底层数仓在 DataHub 中摄入所用的 platform_instance数仓未用 platform_instance 摄入时如典型 BigQuery留空default_databaseSQL cell 中未限定表引用的外层限定符。BigQuery 为 GCP project IDSnowflake/Postgres/Redshift/MSSQL 为 databaseTrino/Databricks/Presto 为 catalogMySQL/MariaDB/ClickHouse 为两段式平台留空只设default_schema。覆盖/v1/data-connections自动提取的值default_schema未限定表引用的内层限定符。BigQuery 为 datasetSnowflake/Postgres/Redshift/MSSQL/Trino/Databricks/Presto/Athena 为 schemaMySQL/MariaDB/ClickHouse 为 database 名完整示例以下示例同时演示了两种场景对应 hex_post.md 中 Connection Platform Resolution 一节配方注释见 hex_recipe.ymlconnection_platform_map: 8f3a1c2d-4b5e-6789-abcd-ef0123456789: platform: snowflake platform_instance: prod_snowflake default_database: ANALYTICS default_schema: PUBLIC 1a2b3c4d-5e6f-7890-abcd-1234567890ab: platform: bigquery default_database: my-gcp-project在源码中该合并逻辑位于HexSource._resolve_connectionsAPI 响应先给出platform/default_database/default_schema基线值connection_platform_map中设置的字段逐字段覆盖override 优先未设置的字段保留 API 值任何既不在内置映射表、又没有被 override 救回的 Hex 连接类型会汇总为一条Unmapped Hex connection typeswarning 输出到摄入报告并跳过引用这些连接的所有 cell。落地一份可直接复制的完整配方将三块前置配置组合起来得到如下最小可运行配方完整版含所有可选开关见 hex_recipe.ymlsource: type: hex config: workspace_name: my-workspace # 前置一workspace 切换下拉框中的 slug workspace_id: org-uuid # 前置二可选显式设置可免授 Users → Read access token: ${HEX_TOKEN} # 前置二Settings → API → Workspace tokens 签发的 token # base_url 默认 https://app.hex.tech/api/v1单租户 Hex 用户请改为自己的访问域名 # 前置三URK 对齐。数仓以 platform_instance 摄入时必须设置 # connection_platform_map: # 8f3a1c2d-4b5e-6789-abcd-ef0123456789: # platform: snowflake # platform_instance: prod_snowflake # default_database: ANALYTICS # default_schema: PUBLIC # 可选过滤与限流 # project_title_pattern: # allow: [^Production .*] # max_projects: 50 # 注意stateful_ingestion 开启时超出上限的项目会被软删除 stateful_ingestion: enabled: true # 启用后Hex 中已删除的项目会在下次运行时被软删除 sink: type: datahub-rest config: server: http://localhost:8080源码级补充限流、重试与稳健性设计理解这些细节有助于判断摄入耗时的量级与偶发失败的成因均位于 api.py主动限流Hex API 限制为 60 请求/分钟HexApi构造时内置滑动窗口限流器57 次/60 秒L345-L357通过 monkey-patchsession.request对所有HTTP 调用透明限速——大工作区的一次完整摄入耗时长属预期行为429 重试requests Session 挂载了Retry(total5, status_forcelist[429], backoff_factor2)指数退避适配器L371-L391与test_connection使用同一套会话保证测试与实际摄入行为一致queriedTables 三层态缓存_queried_tables_tier_available在收到首次 403 后被永久置为False后续实体直接跳过该 API 调用并回退到 SQL 解析只在摄入报告中留一条 warningL809-L845——这与文档“403非 Enterprise 工作区整体回退到 Tier 2 并告警”的描述一致分页容错项目列表分页在单页失败/解析异常时清空after游标终止循环并记录 failure避免对同一失败页无限重试L460-L487。自检清单接入 Hex 前按本篇逐项核对可覆盖绝大多数“摄入成功但数据缺失”的工单workspace_name用的是下拉框中的 slug不是显示名或 UUIDToken 是Workspace token且至少包含Projects → Read accessCells → Read access低档位工作区不要授予也无法授予Read project queried tables不想授Users → Read access时workspace_id已从某个 Hex 项目 URL 中复制进配方Test Connection 报告中若出现/v1/data-connections失败已按提示补 scope 或补connection_platform_map数仓侧用了platform_instance的每个对应连接 UUID 都已在connection_platform_map中设置了相同的platform_instance否则血缘 URN 不会与数仓实体重合运行后检查摄入报告中的Unmapped Hex connection types与逐 cell 的 skipped 原因missing_connection_id/unresolved_platform逐一补齐映射后重跑——排查细节见 hex_post.md 的 Troubleshooting。【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考