如何使用本体模型分析 SAP BW 数据资源

适用版本： Data Xpert / UOSE 当前版本。前置条件： 可访问的 SAP BW/BPC 系统、对应 Secret、语义模型权限和可用的 Assistant。外部依赖： 需要可访问的 SAP BW/XMLA 系统、对应 Secret、语义模型权限和 Assistant；没有 SAP 时请先阅读数据本体系统快速开始。

SAP BW 的 Cube、度量和维度是多维分析对象。新的 Data 产品流程把已发布的语义模型投影成系统托管的本体资源。Assistant 先从本体定位对象，再经过统一动作发现、授权、预演和执行，最后把标准化结果交给 Workbench 或 LiveArtifact，而不是直接拼接 XMLA 地址或未经治理的 MDX。本文以 SAP BW 语义模型为例，说明从模型发布、查看本体资源、绑定 Assistant、执行 Cube slice 到生成 LiveArtifact Dashboard 的完整流程。

开始前

准备一个已发布的 SAP BW 语义模型、目标 Cube、可用的 Assistant 和资源访问策略。文中的模型名称、资源 ID、Cube、维度和度量均应替换为你的环境值。

新系统的执行链路

发布语义模型后，系统自动生成 datax-semantic-model-${modelId} 资源。该资源在本体空间中以 business_ontology 类型保存，capabilities 中的 runtimeAdapterId: semantic_model 将查询路由到语义模型运行时。因此不需要手工创建旧式 semantic_model resource、填写 modelIds 或再发一个补偿请求。创建者保存 binding 时要有资源和业务域权限；看板查看者打开或刷新时，会针对每个 binding 重新检查资源访问和 live_artifact action policy。组织内分享不会绕过查看者权限。

前置条件

可以登录 Data X Web 和 Xpert 工作台；
有权查看已发布的 SAP BW 语义模型和本体空间；
有权在 目标业务域 业务域中创建或编辑 Assistant；
对目标资源拥有读取权限，并允许执行 mdx.query_cube_slice；
需要当前组织具备目标 SAP BW 数据源和 Assistant 的访问权限。

只有本体查看权限时，仍可能看见 Cube 元数据，但 simulateAction 会返回拒绝。

1. 确认已发布的 SAP BW 模型

打开语义模型列表，搜索 示例 SAP BW 模型，确认状态为“已发布”。发布是后续生成本体资源的前提。

图 1：示例流程使用的模型已经发布，名称和版本来自实际的语义模型列表。记录模型 ID 和系统托管资源 ID：

modelId: <modelId>
resourceId: <resourceId>

不要把 XMLA 密码、访问令牌或连接地址复制到 Assistant 指令或 LiveArtifact HTML；连接信息由语义模型和服务端 Secret 管理。

2. 在模型工作台确认 Cube 契约

打开模型工作台，确认数据源为 目标 SAP BW 数据源，查看 Cube 示例 Cube 的度量和维度。

图 2：模型工作台显示Cube、度量和维度；这里用于确认查询契约，不是 Assistant 的运行时入口。示例流程发现：

对象	技术引用	用途
采购金额	`[Measures].[GrossAmountInTransacCurrency]`	按公司汇总采购金额
采购订单数量	`[Measures].[po_counter]`	按公司统计采购订单量
公司维度	`[2CLQV6IYPDAMTF6DFH2S2PADWW5]`	Cube slice 的分组维度

这份模型没有合法时间维度，所以不要在 prompt 中要求“最近 12 个月趋势”，也不要让 Agent 自动补默认时间窗。

3. 查看系统托管本体资源

进入本体空间，搜索模型名称或 resourceId，确认模型、Cube、度量和维度已经出现在 ontology snapshot 中。

图 3：本体空间中的项目来自已发布模型。正式资源类型是 business_ontology，通过 runtimeAdapterId: semantic_model 使用语义模型适配器。这里不要按旧系统教程手工注册第二个 semantic_model 外部资源，也不要填写一套 modelIds、endpoints 和 full sync 表单。只需确认：

资源状态可用，snapshot 已生成；
目标 Cube、度量和维度出现在本体中；
资源没有归档，当前租户和组织可以访问；
目标 action 属于该资源的只读能力集合。

本体负责定位对象和保存查询契约，事实值仍由语义模型运行时回源 SAP BW。看见本体实体不等于当前用户一定可以读取事实数据。

4. 将资源绑定到 Assistant

在 Assistant 配置页选择业务域 目标业务域，在资源访问配置中勾选目标模型的系统托管资源。

图 4：Assistant 只被授予当前分析需要的系统托管资源。资源白名单是运行时授权边界，不是 prompt 中的一段说明。可使用下面的指令约束分析边界：

你是 SAP BW 采购运营分析助手。
先在已授权的本体资源中定位 semantic_cube、semantic_measure 和 semantic_dimension，
再发现并模拟可用的只读 action。执行前说明目标 Cube、维度、度量和过滤条件；
执行后说明 effect kind、返回行数、是否截断、数据更新时间和审计引用。
如果目标模型没有时间维度，不要自动补默认时间窗，也不要把公司行数称为订单总数。
缺少资源、目标对象或当前查看者权限时，直接返回结构化拒绝原因。

资源绑定和业务域变更由同一个 Assistant 配置命令保存。外部同步如果暂时未完成，会显示同步状态并由 outbox 重试，不需要前端再发第二个补偿请求。

5. 执行本体动作

使用统一链路：

queryEntities → discoverActions → simulateAction → executeAction

5.1 定位 Cube

{
  "resourceId": "<resourceId>",
  "entityTypeCode": "semantic_cube",
  "entityRef": "<modelId>::示例 Cube"
}

5.2 发现并预演 action

对目标 Cube 发现并执行 mdx.query_cube_slice，payload 为：

{
  "actionTypeCode": "mdx.query_cube_slice",
  "target": {
    "entityTypeCode": "semantic_cube",
    "entityRef": "<modelId>::示例 Cube"
  },
  "params": {
    "dimensions": ["[2CLQV6IYPDAMTF6DFH2S2PADWW5]"],
    "measures": [
      "[Measures].[GrossAmountInTransacCurrency]",
      "[Measures].[po_counter]"
    ],
    "limit": 10,
    "title": "SAP BW采购订单按公司代码"
  }
}

simulateAction 返回 ALLOWED 后，才用完全相同的 payload 调用 executeAction。保存 LiveArtifact 时服务端也会重新预演，确保保存的 binding 与预演 payload 一致。

图 5：回执由该流程 queryEntities → discoverActions → simulateAction → executeAction 响应生成，包含动作、策略、返回行数、耗时、审计引用和标准 effect v2，不是预置数据，也不是原始 XMLA 响应。

字段	结果
`simulateAction`	`ALLOWED`
`executeAction`	`SUCCEEDED`
`policyDecision`	`allow`
`returnedRowCount`	返回行数
`truncated`	`false`
执行耗时	约 `1255 ms`
`auditRef`	`<id>`

返回结果是标准 effect v2 的 kind: rows，包含 columns、rows 和 summary。适配器负责转换 SAP BW 响应；HTML 和图表层不读取 XMLA envelope 或 SAP BW 专用字段。

6. 生成 LiveArtifact Dashboard

向 Assistant 提出一句业务需求即可：

请基于已授权的 SAP BW 采购订单 Cube 创建一个采购运营指挥中心。
按公司展示采购金额和采购订单量，顶部显示返回金额、返回订单量和公司数，
同时显示使用的 Cube、resourceId、返回行数、truncated 和 policyDecision。
如果模型没有时间维度，就做公司切片，不要生成月度趋势。
保存前完成每条 binding 的 simulateAction，并在运行时继续按查看者权限校验。

binding 使用资源、动作、target 和解析后的参数，不保存 XMLA URL：

{
  "company_procurement": {
    "resourceId": "<resourceId>",
    "actionTypeCode": "mdx.query_cube_slice",
    "target": {
      "entityTypeCode": "semantic_cube",
      "entityRef": "<modelId>::示例 Cube"
    },
    "params": {
      "dimensions": ["[2CLQV6IYPDAMTF6DFH2S2PADWW5]"],
      "measures": [
        "[Measures].[GrossAmountInTransacCurrency]",
        "[Measures].[po_counter]"
      ],
      "limit": 10,
      "title": "SAP BW采购订单按公司代码"
    }
  }
}

保存和查询都要求资源状态、目标实体和 action policy 校验；运行时按当前查看者重新校验。资源撤权、归档、业务域变化或 policy 收紧后，已有看板下一次刷新会立即受影响。缺少 assistant context 的 Artifact 不允许查询，组织内分享不会绕过权限。示例流程生成：

artifactId: <artifact-id>
versionId: <id>
shareSlug: <share-slug>

图 6：分享页中的看板。页面应同时展示返回指标、policyDecision 和 truncated；结果仅代表当前 Cube slice 的返回范围。

7. 标准 effect v2 和图表

LiveArtifact 的 HTML 或 ECharts 渲染层只读取统一结构：

interface DataXLiveArtifactEffect {
  version: 2;
  kind: "rows" | "series" | "entity";
  columns: Array<{
    key: string;
    label?: string;
    type?: "string" | "number" | "boolean" | "date" | "datetime";
    semanticRef?: string;
  }>;
  rows?: Array<Record<string, unknown>>;
  series?: Array<Record<string, unknown>>;
  entity?: Record<string, unknown>;
  summary: {
    rowCount: number;
    returnedRowCount: number;
    truncated: boolean;
  };
}

此流程使用 kind: rows：columns 描述列，rows 提供查询返回值，summary.returnedRowCount 表示实际行数，summary.truncated 表示是否截断。ECharts 只负责展示，不能负责资源发现、动作执行或授权；不能读取 raw、XMLA envelope 或 adapter-specific 字段。首版 OData 动作最多返回 200 行，截断数据不能直接作为全量 KPI。

8. 验收清单

模型已发布，modelId 和系统托管 resourceId 与当前版本一致。
本体空间可以看到 business_ontology、Cube、度量和维度实体。
Assistant 业务域为 目标业务域，资源白名单包含目标资源。
queryEntities 能定位目标 semantic_cube。
discoverActions 返回只读 mdx.query_cube_slice。
保存前和运行前的 simulateAction 均返回 ALLOWED。
executeAction 返回标准 effect v2、策略结果、行数和审计引用。
LiveArtifact 显示资源、Cube、returnedRowCount 和 truncated。
无权查看者刷新会被拒绝；组织分享不会绕过权限。

常见问题

为什么资源类型是 `business_ontology`？

这是新系统的正式资源类型。已发布语义模型由系统生成 datax-semantic-model-${modelId}，再通过 runtimeAdapterId: semantic_model 路由到语义模型运行时。不要再手工创建第二个同模型资源。

为什么没有生成月度趋势？

示例 SAP BW 模型 没有可用时间维度。没有时间维度时，运行时不会自动补默认时间窗，该流程使用公司维度 Cube slice；需要趋势时请换用带时间维度的模型并重新预演。

`simulateAction` 返回 `ACTION_PARAMS_INVALID` 怎么办？

确认 target 的 entityRef 来自当前 snapshot，并确认 dimensions 和 measures 都来自该 Cube 的分析契约。不要把另一个 Cube 的技术名称复制过来，也不要把 business_ontology 错误地当成旧 semantic_model 注册。

为什么能看到 Cube，却不能查询事实数据？

本体可见性和事实数据访问是两层权限。查看者还需要资源读取权限和 live_artifact action policy；资源归档或策略撤销后，已有看板下一次刷新也会被拒绝。

为什么看板数字不一定等于 SAP BW 全量报表？

本教程 binding 设置 limit: 10，看板展示的是返回范围。必须同时展示 returnedRowCount 和 truncated；需要全量聚合时，应在语义模型中定义指标，而不是在 LiveArtifact HTML 中对截断行自行求和。

SAP 与资源接入

语义模型与分析

如何使用本体模型分析 SAP BW 数据资源

开始前

新系统的执行链路

前置条件

1. 确认已发布的 SAP BW 模型

2. 在模型工作台确认 Cube 契约

3. 查看系统托管本体资源

4. 将资源绑定到 Assistant

5. 执行本体动作

5.1 定位 Cube

5.2 发现并预演 action

6. 生成 LiveArtifact Dashboard

7. 标准 effect v2 和图表

8. 验收清单

常见问题

为什么资源类型是 `business_ontology`？

为什么没有生成月度趋势？

`simulateAction` 返回 `ACTION_PARAMS_INVALID` 怎么办？

为什么能看到 Cube，却不能查询事实数据？

为什么看板数字不一定等于 SAP BW 全量报表？

延伸阅读

​开始前

​新系统的执行链路

​前置条件

​1. 确认已发布的 SAP BW 模型

​2. 在模型工作台确认 Cube 契约

​3. 查看系统托管本体资源

​4. 将资源绑定到 Assistant

​5. 执行本体动作

​5.1 定位 Cube

​5.2 发现并预演 action

​6. 生成 LiveArtifact Dashboard

​7. 标准 effect v2 和图表

​8. 验收清单

​常见问题

​为什么资源类型是 business_ontology？

​为什么没有生成月度趋势？

​simulateAction 返回 ACTION_PARAMS_INVALID 怎么办？

​为什么能看到 Cube，却不能查询事实数据？

​为什么看板数字不一定等于 SAP BW 全量报表？

​延伸阅读

开始前

新系统的执行链路

前置条件

1. 确认已发布的 SAP BW 模型

2. 在模型工作台确认 Cube 契约

3. 查看系统托管本体资源

4. 将资源绑定到 Assistant

5. 执行本体动作

5.1 定位 Cube

5.2 发现并预演 action

6. 生成 LiveArtifact Dashboard

7. 标准 effect v2 和图表

8. 验收清单

常见问题

为什么资源类型是 `business_ontology`？

为什么没有生成月度趋势？

`simulateAction` 返回 `ACTION_PARAMS_INVALID` 怎么办？

为什么能看到 Cube，却不能查询事实数据？

为什么看板数字不一定等于 SAP BW 全量报表？

延伸阅读