DataHub 接入 SAP Analytics CloudSACBI 元数据摄取、概念映射与血缘解析实战指南【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahubSAP Analytics CloudSAC是 SAP 推出的商务智能与分析平台本篇指南围绕 DataHub 仓库中的sac摄取模块位于 metadata-ingestion/docs/sources/sac/README.md完整讲解其支持的 BI 对象类型、SAC 与 DataHub 的概念映射关系、OAuth 客户端前置配置、Recipe 编写要点以及面向 SAP BW / HANA / Datasphere 的实时数据模型血缘解析原理。读完本文你将能够独立完成一个生产可用的 SAC → DataHub 摄取流水线配置并理解其能力边界与排障思路。模块定位SAC 能向 DataHub 提供什么DataHub 的 SAC 集成主要覆盖 BI 实体如 Dashboard、Chart、Dataset及其相关的所有权ownership上下文同时支持表级血缘table-level lineage与基于状态化摄取的删除检测stateful deletion detection。其核心处理逻辑集中在 sac.py 的SACSource类中该类通过platform_name(SAP Analytics Cloud, idsac)注册为平台标识sac当前支持状态为 BETA见 connector 注册表。从模块装饰器声明的能力看SAC 源在 DataHub 能力模型中注册了以下能力能力说明PLATFORM_INSTANCE默认启用支持平台实例platform instance标注DESCRIPTIONS默认启用摄取描述信息LINEAGE_COARSE默认启用但仅针对 Live Data Models实时数据模型DELETION_DETECTION默认启用经由状态化摄取实现SCHEMA_METADATAImport Data Models 默认启用acquiredSAC 存储型模型需通过ingest_acquired_data_model_schema_metadata显式开启概念映射SAC 对象如何落入 DataHub 实体模型SAC 中的对象与 DataHub 实体的映射关系是理解本模块的起点官方文档给出了如下对应表SAP Analytics CloudDataHubStoryDashboardApplicationDashboardLive Data ModelDatasetImport Data ModelDatasetModelDataset也就是说SAC 的 Story故事与 Application分析应用在 DataHub 中被建模为Dashboard而所有类型的数据模型实时模型、导入模型、通用模型都被建模为Dataset。在 DataHub 子类型SubType层面实现更加细化。源码 subtypes.py 与 sac.py 显示模型会依据来源打上以下子类型之一SAC_LIVE_DATA_MODELLive Data Model当模型带有connection_id、system_type且具备external_id或为 DWC 类型时判定为实时数据模型SAC_IMPORT_DATA_MODELImport Data Model当模型被识别为导入模型时SAC_MODELModel其余无法明确区分类型的模型例如 builtin 内置模型仅打上通用 Model 子类型。而 Story / Application 则在 get_resource_workunits 中通过resource_subtype判定并打上SAC_STORYStory或SAC_APPLICATIONApplication子类型两者最终都落在Dashboard实体上。前置条件创建具备 API 访问权限的 OAuth 客户端在运行摄取前需要确保满足到源系统的网络连通性、有效的认证凭据以及元数据 API 所需的读取权限。针对 SAC 的具体要求是在 SAP Analytics Cloud 中创建 OAuth 客户端参见 SAP 官方文档《Manage OAuth Clients》该 OAuth 客户端必须满足以下属性Purpose用途API AccessAccess访问范围Story Listing故事列表Data Import Service数据导入服务Data Export Service数据导出服务仅当启用ingest_acquired_data_model_schema_metadata时必需——acquired 数据模型的 schema 需要经由 Data Export Service 读取Authorization Grant授权方式Client Credentials客户端凭证从实现上看SACSource.get_sac_connectionsac.py使用authlib的OAuth2Session以client_credentials授权方式换取 token并向请求头注入x-sap-sac-custom-auth: trueSAP SAC 自定义认证头。该实现还配置了重试策略对400/500/503状态码自动重试最多 3 次退避因子 10 秒但刻意不对 401 重试——因为 401 同时可能是临时故障也可能是 OAuth 凭据无效或权限配置错误重试只会掩盖问题源码注释对此有明确说明。模块内置的连接测试方法test_connection会分别探测{tenant_url}/api/v1/Resources与{tenant_url}/api/v1/dataimport/models两个端点Data Import Service 需要 OAuth 客户端具备特定属性故单独验证若开启了 acquired 模型 schema 摄取还会额外探测 Data Export Service 端点{tenant_url}/api/v1/dataexport/administration/Namespaces(NamespaceIDsac)/Providers并单独报告SCHEMA_METADATA能力是否可用方便排查权限缺失问题。编写 Recipe参数逐一拆解以下是官方示例 Recipe来自 sac_recipe.yml的完整形态source: type: sac config: stateful_ingestion: enabled: true tenant_url: # Your SAP Analytics Cloud tenant URL, e.g. https://company.eu10.sapanalytics.cloud or https://company.eu10.hcs.cloud.sap token_url: # The Token URL of your SAP Analytics Cloud tenant, e.g. https://company.eu10.hana.ondemand.com/oauth/token. # Add secret in Secrets Tab with relevant names for each variable client_id: ${SAC_CLIENT_ID} # Your SAP Analytics Cloud client id client_secret: ${SAC_CLIENT_SECRET} # Your SAP Analytics Cloud client secret # ingest stories ingest_stories: true # ingest applications ingest_applications: true resource_id_pattern: allow: - .* resource_name_pattern: allow: - .* folder_pattern: allow: - .* connection_mapping: MY_BW_CONNECTION: platform: bw platform_instance: PROD_BW env: PROD MY_HANA_CONNECTION: platform: hana platform_instance: PROD_HANA env: PROD # SAP Datasphere (DWC) connection: SAC does not expose the Datasphere space, # so set it here to build the upstream sap-datasphere lineage (space.model_name). MY_DATASPHERE_CONNECTION: datasphere_space: my_space # platform_instance / env / convert_urns_to_lowercase must match how the # SAP Datasphere connector ingested the assets so the urns stitch. env: PROD convert_urns_to_lowercase: true # Emit column-level lineage to SAP Datasphere by mirroring the upstream datasets # schema from DataHub (requires a datahub_api/graph connection and SAP Datasphere # to be ingested first). Falls back to table-level lineage when unavailable. resolve_datasphere_column_lineage: true结合 SACSourceConfig 的字段定义对核心参数逐一说明连接与认证参数参数类型/默认值说明tenant_urlstring必填SAC 租户地址例如https://company.eu10.sapanalytics.cloud或https://company.eu10.hcs.cloud.sap实现中会自动去除尾部斜杠token_urlstring必填SAC 租户的 OAuth Token 端点例如https://company.eu10.hana.ondemand.com/oauth/token同样自动去除尾部斜杠client_idstring必填OAuth 客户端 IDclient_secretSecretStr必填OAuth 客户端密钥建议在 DataHub 的 Secrets 中管理并通过${SAC_CLIENT_SECRET}引用stateful_ingestion对象默认关闭状态化摄取配置启用后获得删除检测能力摄取范围控制参数类型/默认值说明ingest_storiesbool默认true是否摄取 Storyingest_applicationsbool默认true是否摄取 Analytic Applicationresource_id_patternAllowDenyPattern默认允许全部按资源 ID 过滤要包含的资源resource_name_patternAllowDenyPattern默认允许全部按资源名称过滤folder_patternAllowDenyPattern默认允许全部按文件夹路径过滤这三个模式过滤的实现位于 get_resourcesresource_id_pattern与resource_name_pattern直接作用于资源 ID 和名称folder_pattern作用于解析后的祖先路径ancestorPath。ingest_stories/ingest_applications则通过 OData$filter表达为组合条件——仅摄取 Story 时过滤resourceType eq STORY and resourceSubtype eq 仅摄取 Application 时过滤resourceType eq STORY and resourceSubtype eq APPLICATION两者同时开启则合并。此外所有资源的底层过滤统一包含isTemplate eq 0 and isSample eq 0 and isPublic eq 1即跳过模板、示例与非公开资源。连接映射connection_mappingconnection_mapping用于把 SAC 中的连接connection映射到具体的平台、平台实例与环境键是 SAC 中创建的连接名称。官方示例connection_mapping: MY_BW_CONNECTION: platform: bw platform_instance: PROD_BW env: PROD MY_HANA_CONNECTION: platform: hana platform_instance: PROD_HANA env: PRODConnectionMappingConfigsac.py支持以下字段字段类型/默认值说明platformstring默认None该连接所属的数据平台未设置时回退到模型的system_type小写形式如bw、hanaplatform_instancestring默认None平台实例名envstring默认PRODDEFAULT_ENV环境标识datasphere_spacestring默认None仅对 SAP DatasphereDWC连接有效该连接对应的 Datasphere space id如bdap_sac。由于 SAC 不暴露 Datasphere-backed 实时模型的 space必须在此手动提供用于构建上游sap-datasphere数据集 URNspace.model_nameconvert_urns_to_lowercasebool默认true构建上游数据集 URN 时是否将标识符转小写必须与对应的 SAP Datasphere 连接器 Recipe 中的同名配置保持一致否则 URN 无法拼接stitch。目前仅作用于 DatasphereDWC上游BW/HANA 上游保持原有大小写若某模型引用的连接未出现在connection_mapping中实现会以system_type.lower()作为平台、以连接 ID 作为 platform_instance回退处理并打印提示日志sac.py。血缘解析开关参数类型/默认值说明resolve_datasphere_lineagebool默认true对由 SAP DatasphereDWC 连接支撑的 SAC 实时数据模型向上游 Datasphere 数据集发出表级血缘。Datasphere 对象技术名从 SAC 模型名推导space 需在connection_mapping.connection_id.datasphere_space中配置上游 URN 确定性构建space.model_name无需 DataHub graph 查询。未配置 space 的模型会被跳过并告警resolve_datasphere_column_lineagebool默认true在表级血缘之外进一步发出到 Datasphere 的列级血缘。SAC 不暴露实时数据模型的列字段列表从 DataHub 中已摄取的上游 Datasphere 数据集 schema 解析并镜像到 SAC 数据集实时模型是透传字段一一自映射。需要datahub_api/graph 连接且 Datasphere 已先被摄取graph 或上游 schema 不可用时回退为仅表级血缘。该开关仅在resolve_datasphere_lineage开启时生效摄取产物Dashboard 与 Dataset 都包含什么DashboardStory / Application对每个资源get_resource_workunitssac.py会产出DashboardInfo标题、描述、创建/修改时间与操作者createdBy/modifiedBy中的SYSTEM、$DELETED_USER$会被归一化为 unknown 用户、外部链接{tenant_url}{openURL}以及resourceType、resourceSubtype、storyId、isMobile等自定义属性BrowsePaths / BrowsePathsV2当资源具有ancestorPathSAC 中的文件夹层级时生成浏览路径SubTypesStory或ApplicationDataPlatformInstance当配置了platform_instance时附带。Dataset数据模型对每个模型get_model_workunitssac.py产出DatasetProperties模型名称、描述以及namespace、modelId、isImport等自定义属性并附带直达 SAC 模型编辑视图的externalUrlSchemaMetadata依模型类型而定详见下一节UpstreamLineage对 Live Data Models 产生详见血缘章节Statusremovedfalse与DataPlatformInstance。Dataset 的 URN 命名为{namespace}:{model_id}平台sac。需要留意的是模型 ID 结构存在差异内置模型如t.4.sap.fpa.services.userFriendlyPerfLog:ACTIVITY_LOG无法获取更多元数据也有模型 ID 本身出现在 namespace 中的情况如t.4.YV67EM4QBRU035A7TVKERZ786N:YV67EM4QBRU035A7TVKERZ786N源码通过partition(:)统一拆分处理sac.py。Schema 元数据的三条路径Import Data Models默认启用通过GET {tenant_url}/api/v1/dataimport/models/{model_id}/metadata拉取列信息列名、描述、属性类型、数据类型、长度、精度、标度、是否主键映射为 DataHubSchemaMetadataClass。数据类型映射规则见get_schema_field_data_typesac.pyDATE属性类型 →DateTypestring→StringTypedecimal/int32→NumberType其余未知类型 →NullType并记录告警。原生类型则按精度/长度拼接如decimal(p, s)、int32(p)、string(max_length)。注意源码提示摄取 Import Data Model 的 schema 会显著增加整体摄取耗时对应配置项ingest_import_data_model_schema_metadata默认true。Acquired Data ModelsSAC 存储型opt-in默认不启用开启ingest_acquired_data_model_schema_metadata后通过 Data Export Service 的$metadata文档GET {tenant_url}/api/v1/dataexport/providers/sac/{model_id}/$metadata解析 EDMX 得到字段列表解析逻辑在 data_export_metadata.py单元测试见 test_data_export_metadata.py。此路径要求 OAuth 客户端具备Data Export Service授权。实现细节上BW/HANA 这类已知实时模型会直接跳过 DES 请求DES 返回 HTTP 412Requested ProviderID is not supported即模型实际为实时模型也被视为预期跳过单模型请求失败不会中断整个运行——该模型仍会被产出只是不带 DES 派生 schema。Live Data Models实时模型schema 保留在源系统中如 BW/HANA/DWCSAC 无法提供因此不摄取 schema。血缘解析Live Data Models 的上游追踪Import Data Models 由于 API 不提供相关信息无法摄取血缘血缘能力只覆盖 Live Data Models且依据system_type分为三条路径BW 与 HANA 上游SAC 返回的externalId携带编码信息sac.pyBWexternalId形如query:[][][query]提取中间的 query 名并套用query_name_template默认QUERY/{name}生成上游数据集名即默认上游名为QUERY/query名HANAexternalId形如view:[schema][schema.namespace][view]拆分为 schema、namespace、view 后按{schema}.{namespace}::{view}有 namespace或{schema}.{view}无 namespace拼出上游数据集名。之后结合connection_mapping得到 platform / platform_instance / env构造上游数据集 URN并以COPY血缘类型写入UpstreamLineageClass。血缘输出前还会先物化上游数据集 key_emit_upstream_dataset_keysac.py即使上游源尚未被摄取血缘节点也能存在从而保证顺序无关order-independent。SAP DatasphereDWC上游SAP Datasphere 在 SAC 中以实时 Data Warehouse CloudDWC连接的形式呈现其模型externalId为空。上游 URN 的构建逻辑_resolve_datasphere_upstreamsac.py为使用模型名称技术名作为 Datasphere 对象名若模型没有真实技术名SAC 合成的namespace:model_id名称无法定位 Datasphere 对象视为无法解析并告警从connection_mapping.connection_id.datasphere_space取 space拼接为space.object_name并按convert_urns_to_lowercase决定是否转小写以平台sap-datasphere构造 URNplatform_instance/env必须与 SAP Datasphere 连接器摄取资产时保持一致URN 才能拼接。列级血缘Datasphere当resolve_datasphere_column_lineage开启默认true时_resolve_datasphere_column_lineagesac.py会通过 DataHub graph需要datahub_api连接读取上游 Datasphere 数据集的SchemaMetadataClass将上游 schema镜像到 SAC 数据集实时模型是透传schema 相同为每个字段生成FineGrainedLineageClass将 SAC 字段一一自映射到同名的上游字段。若 graph 不可用或上游 schema 尚未摄取提示先摄取 SAP Datasphere则优雅回退为仅表级血缘并记录dwc_column_lineage_unresolved统计。源码中的SACSourceReport提供了dwc_models_scanned、dwc_lineage_resolved、dwc_lineage_unresolved、dwc_lineage_skipped_no_space、dwc_column_lineage_resolved/unresolved等细分计数器便于排障。状态化摄取与删除检测启用stateful_ingestion.enabled: true后模块基于StatefulIngestionSourceBase与StaleEntityRemovalSourceReport实现删除检测每次运行维护已见实体集合跨运行比对后可将源端已删除的 Story / Application / 模型在 DataHub 中标记为删除StatusClass(removed...)能力表中DELETION_DETECTION即由此而来。该机制同样覆盖血缘输出时物化的上游节点避免产生孤儿实体。能力边界与已知限制以下是官方文档明确列出的限制配置与排障时必须了解仅摄取被 Story 或 Application 使用的模型SAC 没有专门的模型检索 API只有 Story 和 Application 的 API因此未被任何 Story / Application 引用的模型不会被摄取。模型无法生成 Browse PathsAPI 不返回模型保存所在的文件夹因此无法为模型创建浏览路径。Schema 摄取按模型类型区分Import Data Model 默认摄取 schemaacquiredSAC 存储型模型可通过ingest_acquired_data_model_schema_metadata经由 Data Export Service$metadata额外摄取默认关闭需 Data Export Service OAuth 授权Live Data Model如 BW/HANA/DWC的 schema 保留在源系统无法从 SAC 获取。Import Data Model 无血缘API 不提供相关信息无法摄取其血缘。Live Data Model 上游支持范围SAP BW、SAP HANA、SAP DatasphereData Warehouse Cloud /DWC连接支持摄取上游血缘其他连接类型会记录告警可携带告警信息提交 issue 以便修复。Datasphere space 需手动配置SAC 只暴露 Datasphere 对象名而不暴露其 space需通过connection_mapping.connection_id.datasphere_space配置才能构建上游sap-datasphere数据集 URNspace.model_name。convert_urns_to_lowercase默认true需与你的 SAP Datasphere 连接器 Recipe 大小写保持一致。未配置 space 的模型会被跳过并告警或设置resolve_datasphere_lineage: false完全关闭。Datasphere 列级血缘依赖预摄取SAC 不暴露实时模型的列字段列表从 DataHub 中已摄取的上游 Datasphere 数据集 schema 解析——需要datahub_api/graph 连接且SAP Datasphere 已先被摄取graph 或上游 schema 不可用时回退为仅表级血缘。builtin 等模型类型无法判别部分模型如内置模型无法检测是 Live Data 还是 Import Data Model这类模型只会以Story子类型摄取。模块行为整体受源 API、权限及平台暴露的元数据约束未支持或有条件的特性以上述能力说明为准。排障指南官方文档给出的排障起点非常务实若摄取失败先依次校验凭据、权限、连通性与范围过滤然后检查摄取日志中源相关的错误信息并相应调整配置。基于源码可补充的排查要点401 错误多为 OAuth 凭据无效或 OAuth 客户端缺少权限如未勾选Story Listing/Data Import Service请核对客户端配置401 不会被自动重试会在日志中直接暴露400 / 500 / 503SAC 的 Resources 与 Data Import Service API 偶发不稳定模块已内置 3 次重试退避 10 秒若仍失败说明问题持续存在Data Export Service 相关失败开启 acquired 模型 schema 摄取后若失败检查 OAuth 客户端是否具备Data Export Service授权运行test_connection可单独得到SCHEMA_METADATA能力报告Datasphere 血缘缺失检查connection_mapping.connection_id.datasphere_space是否配置、convert_urns_to_lowercase是否与 Datasphere 连接器一致、上游 Datasphere 是否已先摄取列级血缘需要利用报告计数运行结束后的SACSourceReport中dwc_*与acquired_model_schema_*系列计数器可以快速定位是哪类模型的血缘或 schema 解析失败。租户代际兼容性直连 Resources OData 端点一个值得注意的实现细节是连接器直接读取ResourcesOData 数据端点例如api/v1/Resources而不是从租户的$metadata文档中发现资源。这与新老两代 SAC 租户的兼容性直接相关新一代基于 CAP 的租户不再在$metadata中描述Resources实体集那里被替换为不可查询的RESOURCES_INDEX目录但Resources数据端点仍然可用——这正是连接器所依赖的对应实现见_query_odata_entitiessac.py其 OData verbose JSON 分页通过顶层d包装与__next驱动。集成测试 test_sac.py 中只 mock 了数据端点而刻意不 mock$metadata与这一设计互相印证完整的黄金文件见 sac_mces_golden.json其中覆盖了 DWC 模型 URN如urn:li:dataset:(urn:li:dataPlatform:sac,t.3.C1ekdhlvx11ts0000000000000:C1ekdhlvx11ts0000000000000,PROD)与 DES schema 解析场景可作为理解输出形态的参考。小结DataHub 的sac模块以 BETA 状态提供了 SAP Analytics Cloud 的 BI 元数据摄取能力Story / Application 落入 Dashboard各类数据模型落入 DatasetImport Data Model 默认携带 schemaLive Data Model 面向 BW / HANA / Datasphere 输出表级Datasphere 可选列级血缘配合状态化摄取实现删除检测。合理配置 OAuth 客户端授权、范围过滤与connection_mapping尤其是 Datasphere 的datasphere_space与大小写一致性即可在生产环境中稳定运行。【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DataHub 接入 SAP Analytics Cloud（SAC）：BI 元数据摄取、概念映射与血缘解析实战指南
DataHub 接入 SAP Analytics CloudSACBI 元数据摄取、概念映射与血缘解析实战指南【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahubSAP Analytics CloudSAC是 SAP 推出的商务智能与分析平台本篇指南围绕 DataHub 仓库中的sac摄取模块位于 metadata-ingestion/docs/sources/sac/README.md完整讲解其支持的 BI 对象类型、SAC 与 DataHub 的概念映射关系、OAuth 客户端前置配置、Recipe 编写要点以及面向 SAP BW / HANA / Datasphere 的实时数据模型血缘解析原理。读完本文你将能够独立完成一个生产可用的 SAC → DataHub 摄取流水线配置并理解其能力边界与排障思路。模块定位SAC 能向 DataHub 提供什么DataHub 的 SAC 集成主要覆盖 BI 实体如 Dashboard、Chart、Dataset及其相关的所有权ownership上下文同时支持表级血缘table-level lineage与基于状态化摄取的删除检测stateful deletion detection。其核心处理逻辑集中在 sac.py 的SACSource类中该类通过platform_name(SAP Analytics Cloud, idsac)注册为平台标识sac当前支持状态为 BETA见 connector 注册表。从模块装饰器声明的能力看SAC 源在 DataHub 能力模型中注册了以下能力能力说明PLATFORM_INSTANCE默认启用支持平台实例platform instance标注DESCRIPTIONS默认启用摄取描述信息LINEAGE_COARSE默认启用但仅针对 Live Data Models实时数据模型DELETION_DETECTION默认启用经由状态化摄取实现SCHEMA_METADATAImport Data Models 默认启用acquiredSAC 存储型模型需通过ingest_acquired_data_model_schema_metadata显式开启概念映射SAC 对象如何落入 DataHub 实体模型SAC 中的对象与 DataHub 实体的映射关系是理解本模块的起点官方文档给出了如下对应表SAP Analytics CloudDataHubStoryDashboardApplicationDashboardLive Data ModelDatasetImport Data ModelDatasetModelDataset也就是说SAC 的 Story故事与 Application分析应用在 DataHub 中被建模为Dashboard而所有类型的数据模型实时模型、导入模型、通用模型都被建模为Dataset。在 DataHub 子类型SubType层面实现更加细化。源码 subtypes.py 与 sac.py 显示模型会依据来源打上以下子类型之一SAC_LIVE_DATA_MODELLive Data Model当模型带有connection_id、system_type且具备external_id或为 DWC 类型时判定为实时数据模型SAC_IMPORT_DATA_MODELImport Data Model当模型被识别为导入模型时SAC_MODELModel其余无法明确区分类型的模型例如 builtin 内置模型仅打上通用 Model 子类型。而 Story / Application 则在 get_resource_workunits 中通过resource_subtype判定并打上SAC_STORYStory或SAC_APPLICATIONApplication子类型两者最终都落在Dashboard实体上。前置条件创建具备 API 访问权限的 OAuth 客户端在运行摄取前需要确保满足到源系统的网络连通性、有效的认证凭据以及元数据 API 所需的读取权限。针对 SAC 的具体要求是在 SAP Analytics Cloud 中创建 OAuth 客户端参见 SAP 官方文档《Manage OAuth Clients》该 OAuth 客户端必须满足以下属性Purpose用途API AccessAccess访问范围Story Listing故事列表Data Import Service数据导入服务Data Export Service数据导出服务仅当启用ingest_acquired_data_model_schema_metadata时必需——acquired 数据模型的 schema 需要经由 Data Export Service 读取Authorization Grant授权方式Client Credentials客户端凭证从实现上看SACSource.get_sac_connectionsac.py使用authlib的OAuth2Session以client_credentials授权方式换取 token并向请求头注入x-sap-sac-custom-auth: trueSAP SAC 自定义认证头。该实现还配置了重试策略对400/500/503状态码自动重试最多 3 次退避因子 10 秒但刻意不对 401 重试——因为 401 同时可能是临时故障也可能是 OAuth 凭据无效或权限配置错误重试只会掩盖问题源码注释对此有明确说明。模块内置的连接测试方法test_connection会分别探测{tenant_url}/api/v1/Resources与{tenant_url}/api/v1/dataimport/models两个端点Data Import Service 需要 OAuth 客户端具备特定属性故单独验证若开启了 acquired 模型 schema 摄取还会额外探测 Data Export Service 端点{tenant_url}/api/v1/dataexport/administration/Namespaces(NamespaceIDsac)/Providers并单独报告SCHEMA_METADATA能力是否可用方便排查权限缺失问题。编写 Recipe参数逐一拆解以下是官方示例 Recipe来自 sac_recipe.yml的完整形态source: type: sac config: stateful_ingestion: enabled: true tenant_url: # Your SAP Analytics Cloud tenant URL, e.g. https://company.eu10.sapanalytics.cloud or https://company.eu10.hcs.cloud.sap token_url: # The Token URL of your SAP Analytics Cloud tenant, e.g. https://company.eu10.hana.ondemand.com/oauth/token. # Add secret in Secrets Tab with relevant names for each variable client_id: ${SAC_CLIENT_ID} # Your SAP Analytics Cloud client id client_secret: ${SAC_CLIENT_SECRET} # Your SAP Analytics Cloud client secret # ingest stories ingest_stories: true # ingest applications ingest_applications: true resource_id_pattern: allow: - .* resource_name_pattern: allow: - .* folder_pattern: allow: - .* connection_mapping: MY_BW_CONNECTION: platform: bw platform_instance: PROD_BW env: PROD MY_HANA_CONNECTION: platform: hana platform_instance: PROD_HANA env: PROD # SAP Datasphere (DWC) connection: SAC does not expose the Datasphere space, # so set it here to build the upstream sap-datasphere lineage (space.model_name). MY_DATASPHERE_CONNECTION: datasphere_space: my_space # platform_instance / env / convert_urns_to_lowercase must match how the # SAP Datasphere connector ingested the assets so the urns stitch. env: PROD convert_urns_to_lowercase: true # Emit column-level lineage to SAP Datasphere by mirroring the upstream datasets # schema from DataHub (requires a datahub_api/graph connection and SAP Datasphere # to be ingested first). Falls back to table-level lineage when unavailable. resolve_datasphere_column_lineage: true结合 SACSourceConfig 的字段定义对核心参数逐一说明连接与认证参数参数类型/默认值说明tenant_urlstring必填SAC 租户地址例如https://company.eu10.sapanalytics.cloud或https://company.eu10.hcs.cloud.sap实现中会自动去除尾部斜杠token_urlstring必填SAC 租户的 OAuth Token 端点例如https://company.eu10.hana.ondemand.com/oauth/token同样自动去除尾部斜杠client_idstring必填OAuth 客户端 IDclient_secretSecretStr必填OAuth 客户端密钥建议在 DataHub 的 Secrets 中管理并通过${SAC_CLIENT_SECRET}引用stateful_ingestion对象默认关闭状态化摄取配置启用后获得删除检测能力摄取范围控制参数类型/默认值说明ingest_storiesbool默认true是否摄取 Storyingest_applicationsbool默认true是否摄取 Analytic Applicationresource_id_patternAllowDenyPattern默认允许全部按资源 ID 过滤要包含的资源resource_name_patternAllowDenyPattern默认允许全部按资源名称过滤folder_patternAllowDenyPattern默认允许全部按文件夹路径过滤这三个模式过滤的实现位于 get_resourcesresource_id_pattern与resource_name_pattern直接作用于资源 ID 和名称folder_pattern作用于解析后的祖先路径ancestorPath。ingest_stories/ingest_applications则通过 OData$filter表达为组合条件——仅摄取 Story 时过滤resourceType eq STORY and resourceSubtype eq 仅摄取 Application 时过滤resourceType eq STORY and resourceSubtype eq APPLICATION两者同时开启则合并。此外所有资源的底层过滤统一包含isTemplate eq 0 and isSample eq 0 and isPublic eq 1即跳过模板、示例与非公开资源。连接映射connection_mappingconnection_mapping用于把 SAC 中的连接connection映射到具体的平台、平台实例与环境键是 SAC 中创建的连接名称。官方示例connection_mapping: MY_BW_CONNECTION: platform: bw platform_instance: PROD_BW env: PROD MY_HANA_CONNECTION: platform: hana platform_instance: PROD_HANA env: PRODConnectionMappingConfigsac.py支持以下字段字段类型/默认值说明platformstring默认None该连接所属的数据平台未设置时回退到模型的system_type小写形式如bw、hanaplatform_instancestring默认None平台实例名envstring默认PRODDEFAULT_ENV环境标识datasphere_spacestring默认None仅对 SAP DatasphereDWC连接有效该连接对应的 Datasphere space id如bdap_sac。由于 SAC 不暴露 Datasphere-backed 实时模型的 space必须在此手动提供用于构建上游sap-datasphere数据集 URNspace.model_nameconvert_urns_to_lowercasebool默认true构建上游数据集 URN 时是否将标识符转小写必须与对应的 SAP Datasphere 连接器 Recipe 中的同名配置保持一致否则 URN 无法拼接stitch。目前仅作用于 DatasphereDWC上游BW/HANA 上游保持原有大小写若某模型引用的连接未出现在connection_mapping中实现会以system_type.lower()作为平台、以连接 ID 作为 platform_instance回退处理并打印提示日志sac.py。血缘解析开关参数类型/默认值说明resolve_datasphere_lineagebool默认true对由 SAP DatasphereDWC 连接支撑的 SAC 实时数据模型向上游 Datasphere 数据集发出表级血缘。Datasphere 对象技术名从 SAC 模型名推导space 需在connection_mapping.connection_id.datasphere_space中配置上游 URN 确定性构建space.model_name无需 DataHub graph 查询。未配置 space 的模型会被跳过并告警resolve_datasphere_column_lineagebool默认true在表级血缘之外进一步发出到 Datasphere 的列级血缘。SAC 不暴露实时数据模型的列字段列表从 DataHub 中已摄取的上游 Datasphere 数据集 schema 解析并镜像到 SAC 数据集实时模型是透传字段一一自映射。需要datahub_api/graph 连接且 Datasphere 已先被摄取graph 或上游 schema 不可用时回退为仅表级血缘。该开关仅在resolve_datasphere_lineage开启时生效摄取产物Dashboard 与 Dataset 都包含什么DashboardStory / Application对每个资源get_resource_workunitssac.py会产出DashboardInfo标题、描述、创建/修改时间与操作者createdBy/modifiedBy中的SYSTEM、$DELETED_USER$会被归一化为 unknown 用户、外部链接{tenant_url}{openURL}以及resourceType、resourceSubtype、storyId、isMobile等自定义属性BrowsePaths / BrowsePathsV2当资源具有ancestorPathSAC 中的文件夹层级时生成浏览路径SubTypesStory或ApplicationDataPlatformInstance当配置了platform_instance时附带。Dataset数据模型对每个模型get_model_workunitssac.py产出DatasetProperties模型名称、描述以及namespace、modelId、isImport等自定义属性并附带直达 SAC 模型编辑视图的externalUrlSchemaMetadata依模型类型而定详见下一节UpstreamLineage对 Live Data Models 产生详见血缘章节Statusremovedfalse与DataPlatformInstance。Dataset 的 URN 命名为{namespace}:{model_id}平台sac。需要留意的是模型 ID 结构存在差异内置模型如t.4.sap.fpa.services.userFriendlyPerfLog:ACTIVITY_LOG无法获取更多元数据也有模型 ID 本身出现在 namespace 中的情况如t.4.YV67EM4QBRU035A7TVKERZ786N:YV67EM4QBRU035A7TVKERZ786N源码通过partition(:)统一拆分处理sac.py。Schema 元数据的三条路径Import Data Models默认启用通过GET {tenant_url}/api/v1/dataimport/models/{model_id}/metadata拉取列信息列名、描述、属性类型、数据类型、长度、精度、标度、是否主键映射为 DataHubSchemaMetadataClass。数据类型映射规则见get_schema_field_data_typesac.pyDATE属性类型 →DateTypestring→StringTypedecimal/int32→NumberType其余未知类型 →NullType并记录告警。原生类型则按精度/长度拼接如decimal(p, s)、int32(p)、string(max_length)。注意源码提示摄取 Import Data Model 的 schema 会显著增加整体摄取耗时对应配置项ingest_import_data_model_schema_metadata默认true。Acquired Data ModelsSAC 存储型opt-in默认不启用开启ingest_acquired_data_model_schema_metadata后通过 Data Export Service 的$metadata文档GET {tenant_url}/api/v1/dataexport/providers/sac/{model_id}/$metadata解析 EDMX 得到字段列表解析逻辑在 data_export_metadata.py单元测试见 test_data_export_metadata.py。此路径要求 OAuth 客户端具备Data Export Service授权。实现细节上BW/HANA 这类已知实时模型会直接跳过 DES 请求DES 返回 HTTP 412Requested ProviderID is not supported即模型实际为实时模型也被视为预期跳过单模型请求失败不会中断整个运行——该模型仍会被产出只是不带 DES 派生 schema。Live Data Models实时模型schema 保留在源系统中如 BW/HANA/DWCSAC 无法提供因此不摄取 schema。血缘解析Live Data Models 的上游追踪Import Data Models 由于 API 不提供相关信息无法摄取血缘血缘能力只覆盖 Live Data Models且依据system_type分为三条路径BW 与 HANA 上游SAC 返回的externalId携带编码信息sac.pyBWexternalId形如query:[][][query]提取中间的 query 名并套用query_name_template默认QUERY/{name}生成上游数据集名即默认上游名为QUERY/query名HANAexternalId形如view:[schema][schema.namespace][view]拆分为 schema、namespace、view 后按{schema}.{namespace}::{view}有 namespace或{schema}.{view}无 namespace拼出上游数据集名。之后结合connection_mapping得到 platform / platform_instance / env构造上游数据集 URN并以COPY血缘类型写入UpstreamLineageClass。血缘输出前还会先物化上游数据集 key_emit_upstream_dataset_keysac.py即使上游源尚未被摄取血缘节点也能存在从而保证顺序无关order-independent。SAP DatasphereDWC上游SAP Datasphere 在 SAC 中以实时 Data Warehouse CloudDWC连接的形式呈现其模型externalId为空。上游 URN 的构建逻辑_resolve_datasphere_upstreamsac.py为使用模型名称技术名作为 Datasphere 对象名若模型没有真实技术名SAC 合成的namespace:model_id名称无法定位 Datasphere 对象视为无法解析并告警从connection_mapping.connection_id.datasphere_space取 space拼接为space.object_name并按convert_urns_to_lowercase决定是否转小写以平台sap-datasphere构造 URNplatform_instance/env必须与 SAP Datasphere 连接器摄取资产时保持一致URN 才能拼接。列级血缘Datasphere当resolve_datasphere_column_lineage开启默认true时_resolve_datasphere_column_lineagesac.py会通过 DataHub graph需要datahub_api连接读取上游 Datasphere 数据集的SchemaMetadataClass将上游 schema镜像到 SAC 数据集实时模型是透传schema 相同为每个字段生成FineGrainedLineageClass将 SAC 字段一一自映射到同名的上游字段。若 graph 不可用或上游 schema 尚未摄取提示先摄取 SAP Datasphere则优雅回退为仅表级血缘并记录dwc_column_lineage_unresolved统计。源码中的SACSourceReport提供了dwc_models_scanned、dwc_lineage_resolved、dwc_lineage_unresolved、dwc_lineage_skipped_no_space、dwc_column_lineage_resolved/unresolved等细分计数器便于排障。状态化摄取与删除检测启用stateful_ingestion.enabled: true后模块基于StatefulIngestionSourceBase与StaleEntityRemovalSourceReport实现删除检测每次运行维护已见实体集合跨运行比对后可将源端已删除的 Story / Application / 模型在 DataHub 中标记为删除StatusClass(removed...)能力表中DELETION_DETECTION即由此而来。该机制同样覆盖血缘输出时物化的上游节点避免产生孤儿实体。能力边界与已知限制以下是官方文档明确列出的限制配置与排障时必须了解仅摄取被 Story 或 Application 使用的模型SAC 没有专门的模型检索 API只有 Story 和 Application 的 API因此未被任何 Story / Application 引用的模型不会被摄取。模型无法生成 Browse PathsAPI 不返回模型保存所在的文件夹因此无法为模型创建浏览路径。Schema 摄取按模型类型区分Import Data Model 默认摄取 schemaacquiredSAC 存储型模型可通过ingest_acquired_data_model_schema_metadata经由 Data Export Service$metadata额外摄取默认关闭需 Data Export Service OAuth 授权Live Data Model如 BW/HANA/DWC的 schema 保留在源系统无法从 SAC 获取。Import Data Model 无血缘API 不提供相关信息无法摄取其血缘。Live Data Model 上游支持范围SAP BW、SAP HANA、SAP DatasphereData Warehouse Cloud /DWC连接支持摄取上游血缘其他连接类型会记录告警可携带告警信息提交 issue 以便修复。Datasphere space 需手动配置SAC 只暴露 Datasphere 对象名而不暴露其 space需通过connection_mapping.connection_id.datasphere_space配置才能构建上游sap-datasphere数据集 URNspace.model_name。convert_urns_to_lowercase默认true需与你的 SAP Datasphere 连接器 Recipe 大小写保持一致。未配置 space 的模型会被跳过并告警或设置resolve_datasphere_lineage: false完全关闭。Datasphere 列级血缘依赖预摄取SAC 不暴露实时模型的列字段列表从 DataHub 中已摄取的上游 Datasphere 数据集 schema 解析——需要datahub_api/graph 连接且SAP Datasphere 已先被摄取graph 或上游 schema 不可用时回退为仅表级血缘。builtin 等模型类型无法判别部分模型如内置模型无法检测是 Live Data 还是 Import Data Model这类模型只会以Story子类型摄取。模块行为整体受源 API、权限及平台暴露的元数据约束未支持或有条件的特性以上述能力说明为准。排障指南官方文档给出的排障起点非常务实若摄取失败先依次校验凭据、权限、连通性与范围过滤然后检查摄取日志中源相关的错误信息并相应调整配置。基于源码可补充的排查要点401 错误多为 OAuth 凭据无效或 OAuth 客户端缺少权限如未勾选Story Listing/Data Import Service请核对客户端配置401 不会被自动重试会在日志中直接暴露400 / 500 / 503SAC 的 Resources 与 Data Import Service API 偶发不稳定模块已内置 3 次重试退避 10 秒若仍失败说明问题持续存在Data Export Service 相关失败开启 acquired 模型 schema 摄取后若失败检查 OAuth 客户端是否具备Data Export Service授权运行test_connection可单独得到SCHEMA_METADATA能力报告Datasphere 血缘缺失检查connection_mapping.connection_id.datasphere_space是否配置、convert_urns_to_lowercase是否与 Datasphere 连接器一致、上游 Datasphere 是否已先摄取列级血缘需要利用报告计数运行结束后的SACSourceReport中dwc_*与acquired_model_schema_*系列计数器可以快速定位是哪类模型的血缘或 schema 解析失败。租户代际兼容性直连 Resources OData 端点一个值得注意的实现细节是连接器直接读取ResourcesOData 数据端点例如api/v1/Resources而不是从租户的$metadata文档中发现资源。这与新老两代 SAC 租户的兼容性直接相关新一代基于 CAP 的租户不再在$metadata中描述Resources实体集那里被替换为不可查询的RESOURCES_INDEX目录但Resources数据端点仍然可用——这正是连接器所依赖的对应实现见_query_odata_entitiessac.py其 OData verbose JSON 分页通过顶层d包装与__next驱动。集成测试 test_sac.py 中只 mock 了数据端点而刻意不 mock$metadata与这一设计互相印证完整的黄金文件见 sac_mces_golden.json其中覆盖了 DWC 模型 URN如urn:li:dataset:(urn:li:dataPlatform:sac,t.3.C1ekdhlvx11ts0000000000000:C1ekdhlvx11ts0000000000000,PROD)与 DES schema 解析场景可作为理解输出形态的参考。小结DataHub 的sac模块以 BETA 状态提供了 SAP Analytics Cloud 的 BI 元数据摄取能力Story / Application 落入 Dashboard各类数据模型落入 DatasetImport Data Model 默认携带 schemaLive Data Model 面向 BW / HANA / Datasphere 输出表级Datasphere 可选列级血缘配合状态化摄取实现删除检测。合理配置 OAuth 客户端授权、范围过滤与connection_mapping尤其是 Datasphere 的datasphere_space与大小写一致性即可在生产环境中稳定运行。【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考