跳转到主要内容
sap_odata_api 资源用于接入 SAP 系统中的 OData 服务。UOSE 会同时从 OData V4 catalog 和 Gateway V2 catalog 发现已发布服务，读取用户本次选择的服务 $metadata，并把 Service、Entity Type、Entity Set、导航关系和 Operation 转化为可搜索、可发现动作的本体对象。

​
支持范围

当前支持：
  • OData V4 metadata，以及 Microsoft EDMX 1.0/2.0/3.0 风格的 OData V2 metadata。
  • 同时从 catalog_v4 和 catalog_v2 发现服务。
  • 在同一个服务选择框中混合展示 V2/V4 catalog 来源，包含来源标签、来源筛选和来源计数。
  • 按规范化后的服务根路径去重。同一服务同时出现在两个 catalog 时，优先使用 catalog_v4 元数据。
  • Basic Auth 和 static bearer 认证。
  • V2 和 V4 服务的 collection 查询和单实体查询。
  • SAP metadata 声明 Entity Set 可写时，支持 create entity 和 update entity。
  • V4 action/function import，以及 V2 function import。
  • V2 运行时约定，例如 key predicate、$inlinecount=allpages、function import 参数和 MERGE 更新。
  • V4 运行时约定，例如 $count=true 和 PATCH 更新。
  • 写请求前的 CSRF token 获取配置。
  • V2 JSON 响应归一化：d.results 暴露为 value，d.__count 暴露为 @odata.count，__metadata.etag 保留给预览和执行上下文使用。
当前不支持：
  • delete 动作。
  • $batch。
  • media stream。
  • deep insert。
  • bound action 或 bound function。

​
同步对象

同步后通常包含：
  • sap_odata_service：服务根、catalog 来源、协议版本和 metadata 位置。
  • sap_odata_entity_type：EDMX 中的结构化类型，包含 key、属性和导航属性。
  • sap_odata_entity_set：面向执行的集合入口，包含 query capabilities、写入元数据和导航绑定。
  • sap_odata_operation：unbound action import 或 function import。
关键关系包括：
  • sap_odata_service_has_entity_set
  • sap_odata_service_has_entity_type
  • sap_odata_entity_set_targets_entity_type
  • sap_odata_entity_type_navigates_to_entity_type
  • sap_odata_service_exposes_operation
Agent 应通过 Entity Set 进入执行，并沿关系读取 Entity Type 的字段定义。

​
Capabilities

SAP OData capabilities 现在只描述持久连接行为和 catalog 位置，不再要求用户维护协议或白名单限制。 常用 capabilities 包括：
  • catalogV4Path：OData V4 服务 catalog 路径。
  • catalogV4Expand：V4 catalog 中用于展开服务的表达式。
  • catalogV2Path：Gateway V2 catalog 路径。
  • metadataPath：通常为 $metadata。
  • csrf：写请求前的 CSRF token 获取方式。
以下字段已不属于 SAP OData capabilities：
  • 协议版本：由每个服务的 $metadata 自动识别。
  • 发现模式：发现过程会同时查询 V4 和 V2 catalog。
  • 用户手工维护的 service、Entity Set 或 operation 白名单：同步范围通过服务选择框确定。
  • 手工写入覆盖配置：写动作由 SAP metadata restriction 决定，例如 V4 Capabilities 注解或 V2 sap:creatable、sap:updatable。
服务范围在同步时选择。服务选择框会发现所有已发布的 V2 和 V4 服务，用户可按来源筛选和搜索，最终只把本次勾选的规范化服务根路径提交给本次同步。该选择不会回写到 resource capabilities。

​
Actions

常用动作包括：
  • sap_odata.read_collection
  • sap_odata.read_entity
  • sap_odata.create_entity
  • sap_odata.update_entity
  • sap_odata.invoke_operation
读动作风险较低。创建、更新和 operation 调用风险较高，生产环境建议通过策略要求审批。 Create 和 update 动作只在 metadata 表明 Entity Set 可写时生成。UOSE 不再通过手工 mutation allowlist 覆盖源系统 metadata。

​
推荐使用方式

  1. 创建 SAP Secret，填写系统 baseUrl、认证方式、sap-client 和 TLS 配置。
  2. 注册 sap_odata_api resource。
  3. 同步前打开服务发现。
  4. 在 catalog_v4 和 catalog_v2 的混合结果中搜索、分组并按来源筛选服务。
  5. 勾选本次同步要包含的服务根路径。
  6. 执行 full sync。
  7. 查询 sap_odata_entity_set。
  8. 查看邻域，确认目标 Entity Type、字段、key schema、query capabilities、协议版本和 catalog 来源。
  9. 先 discoverActions，再 simulateAction。
  10. 对写动作查看预期效果和审批要求后执行。

​
排障提示

  • 如果预期服务没有出现，检查它是否发布在 SAP V4 或 Gateway V2 catalog 中、当前 SAP 用户是否有读取 catalog 的权限、sap-client 是否正确、服务是否已在 SAP 系统中激活。
  • 如果某个服务出现在 SAP 文档中但发现不到，确认目标系统是否具备并启用了对应的 S/4HANA 组件、业务功能、communication scenario 或 Gateway service。
  • 如果 metadata 解析失败，检查 $metadata 是否返回有效的 OData V2 或 V4 EDMX 文档。
  • 如果发现不到 create 或 update，检查 SAP metadata 写入 restriction 和源系统权限。
  • 如果写请求失败，检查 CSRF、ETag 和源系统权限。
  • 如果字段不存在，优先查看关联 Entity Type 的 properties，不要只看 Entity Set 摘要。