使用 DataHub sac 连接器接入 SAP Analytics Cloud 元数据Story、Application、Data Model 与 Datasphere 血缘【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahubSAP Analytics CloudSAC是 SAP 的商业智能与分析平台承载 Story故事、Analytic Application分析应用与 Data Model数据模型等分析资产。DataHub 内置的sac源连接器位于 metadata-ingestion/src/datahub/ingestion/source/sac/sac.py以生产级摄入为目标将 SAC 中的 BI 资产及其底层数据模型统一建模进 DataHub并支持与 SAP BW、SAP HANA、SAP Datasphere 之间的血缘打通。读完本文你将掌握sac连接器的完整配置方法、OAuth 客户端准备、连接映射connection_mapping的使用以及 Live/Import Data Model 的 schema 与血缘处理细节。概念映射SAC 资产如何落入 DataHubSAC 的元数据模型与 DataHub 实体之间存在稳定的映射关系官方文档metadata-ingestion/docs/sources/sac/README.md给出了如下对照表SAP Analytics CloudDataHub 实体StoryDashboardApplicationDashboardLive Data ModelDatasetImport Data ModelDatasetModelDataset从源码实现看这一映射在 sac.py 的get_workunits_internal与get_resource_workunits中落地每个 Story/Application 生成一个dashboard实体其引用的每个模型生成一个dataset实体再通过DashboardInfoClass的datasets字段将二者关联。实体子类型定义在 subtypes.pyStory→Dashboard子类型BIAssetSubTypes.SAC_STORYApplication→Dashboard子类型BIAssetSubTypes.SAC_APPLICATION模型 →Dataset按模型形态细分为SAC_IMPORT_DATA_MODEL、SAC_LIVE_DATA_MODEL与通用SAC_MODEL前置条件OAuth 客户端与连接映射1. 在 SAC 中创建 OAuth 客户端连接器通过 OAuth 2.0 Client Credentials 访问 SAC API。请参考 SAP 官方的 Manage OAuth Clients 说明创建 OAuth 客户端时需满足Purpose用途API AccessAccess访问范围Story ListingData Import ServiceData Export Service仅在开启可选配置ingest_acquired_data_model_schema_metadata时需要——此时通过 Data Export Service 读取 acquiredSAC 内置存储Data Model 的 schemaAuthorization Grant授权方式Client Credentials从源码看连接器使用authlib的OAuth2Session以client_secret_post方式向token_url换取令牌并在每次请求的请求头中注入x-sap-sac-custom-auth: true见 sac.py 与_add_sap_sac_custom_auth_header。同时为缓解 SAC API 偶发的瞬时错误会话层配置了重试策略Retry(total3, read3, connect3, backoff_factor10)对 HTTP 400/500/503 重试但刻意不重试 401因为 401 意味着凭据无效或权限缺失重试无意义。2. 配置连接映射connection_mappingSAC 中的模型通过“连接”关联到底层数据源如 BW、HANA、Datasphere。要用connection_mapping将 SAC 连接映射到 DataHub 的 platform、platform instance 与 envconnection_mapping: MY_BW_CONNECTION: platform: bw platform_instance: PROD_BW env: PROD MY_HANA_CONNECTION: platform: hana platform_instance: PROD_HANA env: PROD字典的 key 是你在 SAP Analytics Cloud 中创建的连接名。该配置对应源码中的ConnectionMappingConfigsac.py支持以下字段字段默认值说明platform无缺省时使用模型system_type的小写形式如bw/hana上游数据集所属平台platform_instance无缺省时使用 SAC 连接 id 作为 platform instance上游平台实例envPRODDEFAULT_ENV上游环境datasphere_space无仅用于 SAP DatasphereDWC连接Datasphere 空间 id如bdap_sac用于构建上游sap-datasphere数据集 urnspace.model_name。非 Datasphere 连接请留空convert_urns_to_lowercasetrue构建该连接上游数据集 urn 时是否将标识符转为小写必须与对应上游连接器 recipe 中convert_urns_to_lowercase设置保持一致否则 urn 无法拼接。目前仅作用于 SAP DatasphereDWC上游BW/HANA 上游保持原有大小写未配置映射时连接器会记录日志 No connection mapping found...并退化为以 SAC 连接 id 作为 platform instance、PROD作为 env 来构建上游 urnsac.py。完整 Recipe 示例与配置项全解官方示例 recipemetadata-ingestion/docs/sources/sac/sac_recipe.yml覆盖了大部分核心配置source: type: sac config: stateful_ingestion: enabled: true tenant_url: # 你的 SAC 租户 URL例如 https://company.eu10.sapanalytics.cloud 或 https://company.eu10.hcs.cloud.sap token_url: # 你的 SAC 租户 Token URL例如 https://company.eu10.hana.ondemand.com/oauth/token. # 在 DataHub 的 Secrets 页按对应名称添加密钥 client_id: ${SAC_CLIENT_ID} # 你的 SAP Analytics Cloud 客户端 id client_secret: ${SAC_CLIENT_SECRET} # 你的 SAP Analytics Cloud 客户端密钥 # 是否摄入 Story ingest_stories: true # 是否摄入 Analytic Application 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) 连接SAC 不暴露 Datasphere space # 因此需在此指定以便构建上游 sap-datasphere 血缘 (space.model_name)。 MY_DATASPHERE_CONNECTION: datasphere_space: my_space # platform_instance / env / convert_urns_to_lowercase 必须与 # SAP Datasphere 连接器摄入资产时的配置一致urn 才能拼接。 env: PROD convert_urns_to_lowercase: true # 通过在 DataHub 中镜像上游数据集 schema 来输出到 SAP Datasphere 的列级血缘 # 需要 datahub_api/graph 连接且 SAP Datasphere 已先摄入。 # 不可用时回退为表级血缘。 resolve_datasphere_column_lineage: true连接器配置项速查表SACSourceConfigsac.py支持的完整配置项如下配置项默认值说明tenant_url必填SAC 租户 URL末尾斜杠会被自动去除field_validator处理token_url必填SAC 租户 OAuth Token 端点 URL同样自动去除末尾斜杠client_id必填OAuth 客户端 IDclient_secret必填OAuth 客户端密钥SecretStr类型建议通过${SECRET}引用 DataHub Secretsingest_storiestrue是否摄入 Storyingest_applicationstrue是否摄入 Analytic Applicationingest_import_data_model_schema_metadatatrue是否摄入 Import Data Model 的 schema 元数据。注意开启后会显著增加整体摄入时间每个模型都要额外调用一次 metadata 接口ingest_acquired_data_model_schema_metadatafalse是否通过 Data Export Service 摄入 acquired非 importData Model 的 schema。Live Data Model 的 schema 保存在源系统会被跳过。开启后每个 acquired 模型会增加一次元数据请求需要 OAuth 客户端具备 Data Export Service 访问授权resource_id_pattern允许全部按资源 id 过滤的 allow/deny 模式resource_name_pattern允许全部按资源名称过滤的 allow/deny 模式folder_pattern允许全部按 Story/Application 所在文件夹路径过滤的 allow/deny 模式connection_mapping{}连接映射见上文query_name_templateQUERY/{name}生成所消费 query 的数据集 urn 的模板占位符{name}会被替换为 query 名称resolve_datasphere_lineagetrue对 SAP DatasphereDWC支撑的 SAC Live Data Model 输出到上游sap-datasphere数据集的血缘。对象技术名取自 SAC 模型名space 需通过connection_mapping.connection_id.datasphere_space提供urn 以确定性方式space.model_name构建无需查询 DataHub 图。未配置datasphere_space的模型会跳过并告警resolve_datasphere_column_lineagetrue在表级 DWC 血缘之外额外输出到 SAP Datasphere 上游数据集的列级血缘。SAC 不暴露 Live Data Model 的列字段列表从 DataHub 中上游 Datasphere 数据集的 schema 解析并镜像到 SAC 数据集live 模型是透传故逐字段一一对应。需要datahub_api/graph 连接图或上游 schema 不可用时回退为仅表级血缘。仅在resolve_datasphere_lineage同时开启时生效此外配置类继承自StatefulIngestionConfigBase、DatasetSourceConfigMixin与IncrementalLineageConfigMixin因此还支持platform_instance、env、stateful_ingestion以及增量血缘相关配置。Story 与 Application 的摄入流程get_workunits_internalsac.py是摄入主流程当ingest_stories或ingest_applications任一开启时调用get_resources()拉取资源列表对每个资源Story/Application遍历其关联的resourceModels为每个模型生成 dataset 实体随后生成资源本身的 dashboard 实体。get_resources()sac.py使用 OData 过滤条件筛选资源isTemplate eq 0 and isSample eq 0 and isPublic eq 1并依据ingest_stories/ingest_applications的组合追加条件默认同时摄入两者时使用(resourceType eq STORY and resourceSubtype eq ) or (resourceType eq STORY and resourceSubtype eq APPLICATION)只开 Story 时过滤resourceType eq STORY and resourceSubtype eq 只开 Application 时过滤resourceType eq STORY and resourceSubtype eq APPLICATION。摄入过程中还做三件值得注意的事文件夹浏览路径解析ancestorPathOData 中以 JSON 字符串返回为 dashboard 同时写入BrowsePathsClass形如/sac/folder1/folder2与BrowsePathsV2Class并支持folder_pattern过滤sac.py。自定义属性dashboard 的customProperties包含resourceType、resourceSubtype、storyId、isMobile等externalUrl指向 SAC 租户中的资源打开地址sac.py。OData 分页_query_odata_entities跟随服务端返回的__next链接逐页拉取兼容 OData verbose JSON 的d包装结构sac.py。数据模型摄入三种模型类型与 schema 处理SAC 中的模型被划分为三类连接器对它们的处理方式不同sac.pyImport Data Model导入数据模型schema 默认摄入。连接器先调用GET /api/v1/dataimport/models获取全部 import 模型 id 集合get_import_data_model_ids再对每个模型调用GET /api/v1/dataimport/models/{model_id}/metadata拉取列定义get_import_data_model_columns构造SchemaMetadataClass时会将isKey列写入primaryKeys并映射字段数据类型——string→StringTypedecimal/int32→NumberType未知类型告警并回退NullType原生类型字符串还会携带精度/标度或最大长度如decimal(16, 2)、int32(10)、string(50)sac.py。Acquired Data ModelSAC 内置存储的模型schema 摄入为可选通过ingest_acquired_data_model_schema_metadata开启。开启后连接器调用 Data Export Service 的GET /api/v1/dataexport/providers/sac/{model_id}/$metadata获取 EDMX 文档并解析_emit_acquired_model_schema/_get_data_export_schema。注意两点行为Live Data Model如 BW/HANA会返回 HTTP 412Requested ProviderID is not supported连接器将其视为预期跳过而非失败单模型请求的传输异常也不会中止整轮摄入只会告警并以无 schema 方式输出该模型。EDMX 中未映射的类型会告警并降级为NullType。Live Data Model实时数据模型schema 保存在源系统中无法从 SAC 获取因此不摄入 schema连接器主要处理其上游血缘见下节。模型的DatasetPropertiesClass会携带namespace、modelId、isImport等自定义属性externalUrl指向 SAC 模型编辑器地址随后根据模型形态写入子类型SAC_LIVE_DATA_MODEL/SAC_IMPORT_DATA_MODEL/SAC_MODELsac.py。无法判断模型类型时的处理对于部分模型如 builtin 模型API 无法判断其是 Live 还是 Import 类型因此这类模型只会以Story子类型被摄入。血缘BW、HANA 与 SAP DatasphereLive Data Model 的上游血缘BW / HANA对于systemType为BW或HANA且携带externalId的模型连接器解析其上游数据集并输出UpstreamLineageClass血缘类型为COPYsac.pyBWexternalId形如query:[][][query]解析出 query 名后套用query_name_template默认QUERY/{name}生成数据集名。HANAexternalId形如view:[schema][schema.namespace][view]解析出 schema/namespace/view 后生成schema.namespace::view或schema.view形式的数据集名。上游 urn 的平台、实例、环境取自connection_mapping缺省时用system_type小写形式与连接 id。如果externalId无法解析连接器会告警但不会生成血缘。SAP BW、SAP HANA 以及 SAP DatasphereData Warehouse Cloud /DWC连接是受支持的上游血缘来源其他连接类型会记录告警可携带告警信息到 GitHub 提交 issue 协助修复。对 SAP DatasphereDWC的血缘解析SAP Datasphere 在 SAC 中以 live Data Warehouse CloudDWC连接形式暴露其模型携带空的externalId因此上游 urn 不依赖解析 external id而是由模型名 每连接的datasphere_space构建sac.pyresolve_datasphere_lineage: true默认时对 DWC 模型执行_emit_datasphere_lineage从模型名得到 Datasphere 对象技术名结合connection_mapping.connection_id.datasphere_space构建sap-datasphere平台数据集 urnspace.model_name按convert_urns_to_lowercase决定是否转小写需与 SAP Datasphere 连接器 recipe 的大小写设置一致才能拼接。模型无真实技术名SAC 以namespace:model_id兜底命名时视为无法解析并告警避免拼接出伪造的 urn。连接未配置datasphere_space的模型会跳过并告警若完全不需要 Datasphere 血缘可设置resolve_datasphere_lineage: false关闭。上游 key 会被显式物化_emit_upstream_dataset_key即使 Datasphere 连接器尚未运行上游节点也能存在保证血缘顺序无关。列级血缘Datasphere 镜像 schemaresolve_datasphere_column_lineage默认true开启时连接器在表级血缘之外输出到 Datasphere 的列级血缘sac.py。由于 SAC 不暴露 Live Data Model 的列字段列表从 DataHub 图中上游 Datasphere 数据集的SchemaMetadata解析live 模型是透传因此该 schema 被镜像到 SAC 数据集上写入SchemaMetadataClass并为每个字段生成FineGrainedLineageClassFIELD_SET→FIELD字段一一自映射。该能力的前提条件需要配置datahub_api/graph 连接SAP Datasphere 必须已经摄入进 DataHub否则上游 schema 不存在。当图连接不可用或上游 schema 缺失时自动回退为仅表级血缘并给出对应告警。需要说明的是列级血缘无论 BW/HANA 还是 Datasphere只对 Live Data Model 生效——Import Data Model 的血缘无法摄入因为 API 不提供相关信息。兼容性跨租户世代的连通性连接器直接读取ResourcesOData 数据端点例如api/v1/Resources来获取 Story、Application 与模型而非从租户的$metadata文档发现端点sac.py 的注释说明了这一设计取舍。这样做保证了跨 SAP Analytics Cloud 租户世代的兼容较新的 CAP 架构租户已不再在$metadata中描述Resources实体集被不可查询的RESOURCES_INDEX目录取代但Resources数据端点仍然可用连接器正是依赖这些端点完成摄入。能力矩阵与状态连接器通过capability装饰器声明其能力sac.py当前支持状态为BetaSupportStatus.BETA能力说明Platform Instance默认启用Descriptions默认启用粗粒度血缘表级默认启用仅 Live Data Model删除检测默认启用基于 stateful ingestionSchema 元数据Import Data Model 默认启用Acquired Data Model 需通过ingest_acquired_data_model_schema_metadata可选开启排障建议官方排障指引sac_post.md建议按以下顺序排查先验证基础条件凭据client_id/client_secret、权限OAuth 客户端访问范围、网络连通性、范围过滤器resource_id_pattern/resource_name_pattern/folder_pattern。再检查摄入日志针对来源特有的错误逐一调整配置。善用test_connection连接器实现TestableSource其test_connectionsac.py会分别探测GET /api/v1/ResourcesStory Listing 权限与GET /api/v1/dataimport/modelsData Import Service 权限若开启了ingest_acquired_data_model_schema_metadata还会额外探测 Data Export Service 的 Providers 端点——若该服务返回非 2xx会给出明确失败原因如缺少 Data Export Service 授权建议补充授权或将ingest_acquired_data_model_schema_metadata设为false。可借助datahub ingest命令配合连接测试快速定位配置问题。模块行为整体受限于 SAP Analytics Cloud 的 API 能力、OAuth 权限与平台暴露的元数据具体不支持或需条件支持的特性请以能力表为准。【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考