> ## 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 操作案例

> 使用 UOSE 对 SAP OData Entity Set 执行读取、创建、更新和操作调用。

SAP OData 场景的关键是 ontology-first。Agent 不应直接拼接 OData URL，而应先在 UOSE 本体中定位 Entity Set，读取关联 Entity Type，再通过受控 action 执行。

SAP OData V2 和 V4 服务在本体侧使用同一套 action model。Agent 选定目标 Entity Set 或 Operation 后，adapter 会处理协议差异，例如 V2 使用 `MERGE` 更新，V4 使用 `PATCH` 更新。

## 读取集合

适合问题：

* 查询最近创建的销售订单。
* 查看某个组织下的客户列表。
* 按字段过滤业务伙伴。

推荐流程：

1. `queryEntities` 搜索 `sap_odata_entity_set`。
2. `getEntityNeighborhood` 查看 `properties`、`key_schema` 和 `query_capabilities`。
3. `discoverActions` 确认 `sap_odata.read_collection` 可用。
4. `simulateAction` 校验 select、expand、filter、top。
5. `executeAction` 执行读取。

参数示例：

```json theme={null}
{
  "queryOptions": {
    "select": ["SalesOrder", "SalesOrganization", "SoldToParty"],
    "filter": "SalesOrganization eq '1010'",
    "top": 10
  }
}
```

## 读取单实体

读取单实体需要 key。Key 的真相源来自 Entity Set 的 `key_schema` 或关联 Entity Type 的 key properties。

推荐先让 Agent 在邻域中确认 key 字段，而不是根据展示名称猜测。

## 创建实体

创建动作通常为 `sap_odata.create_entity`。执行前应确认：

* Entity Set 允许 create。
* SAP metadata restriction 已放行。UOSE 不使用手工 mutation allowlist 覆盖源系统 metadata。
* payload 字段存在于 Entity Type properties。
* 源系统用户有写权限。
* 策略没有拒绝或审批已通过。

生产环境建议对 create 动作配置 require approval，并要求审批人查看 expected effect。

## 更新实体

更新动作通常为 `sap_odata.update_entity`。执行前应确认：

* key 完整。
* 字段可更新。
* 如源系统要求 ETag，需要正确处理并发。
* payload 不包含只读字段。
* 策略和审批已通过。

更新失败时优先检查源系统权限、CSRF token、ETag 和字段约束。

## Operation 调用

`sap_odata.invoke_operation` 用于 unbound action import 或 function import。它比普通读取风险更高，因为可能触发业务副作用。

对 V2 服务，function import 的参数和 GET/POST 行为来自 metadata。对 V4 服务，action 和 function import 使用 V4 import 定义。

建议：

* 默认设置为审批动作。
* 在 `simulateAction` 中明确参数和预期效果。
* 审计中保留 operation 名称、参数摘要和源系统响应摘要。

## 实操守则

* 读取字段以 Entity Type properties 为准。
* 执行动作以前必须 `discoverActions`。
* 写动作必须经过策略治理。
* 不要把 SAP 密码或 token 放入 capabilities。
* 如果服务发现过多，使用 SAP OData 服务选择框、来源筛选和搜索，只勾选本次同步需要的服务根路径。