> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# SAP OData API 资源

> 将 SAP OData V2 和 V4 服务同步为本体对象，并支持受控读写动作。

`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 摘要。