Dynamics 365 Business Central自定义API复合键单端点PATCH返回404

安全阿岳

2026-6-11

问题描述

在Dynamics 365 Business Central沙箱环境中，为自定义「Warehouse Activity Line」表创建了如下自定义API页面：

page 52105 WarehouseActivityLineApi
{
    PageType = API;
    Caption = 'WarehouseActivityLineApi';
    APIPublisher = //company;
    ApplicationArea = all;
    APIGroup = 'Reporting';
    APIVersion = 'v2.0';
    EntityName = 'warehouseActivityLine';
    EntitySetName = 'warehouseActivityLines';
    SourceTable = "Warehouse Activity Line";
    DelayedInsert = true;
    ODataKeyFields = "Action Type", "No.", "Line No.";

    layout
    {
        area(Content)
        {
            repeater(General)
            {
              // fields 
            }
        }
    }
}

集合端点可正常工作，执行以下GET请求能返回预期记录：

GET /warehouseActivityLines?$filter=actionType eq 'Place' and no eq 'WPA000540' and lineNo eq 20000

但使用复合键调用单端点进行PATCH请求时返回404 Not Found：

PATCH /warehouseActivityLine(actionType='Place',no='WPA000540',lineNo=20000)

该URL格式符合OData规范及定义的EntityName/EntitySetName，且记录确实存在（PATCH前已通过集合GET请求确认）。已多次重新发布页面并等待元数据刷新，疑问：为何集合端点正常，但带复合ODataKeyFields的单端点返回404？是沙箱环境已知的元数据缓存问题，还是页面定义中遗漏了什么？

排查方向与解决办法

检查键字段的名称映射：OData请求中的键字段名称必须和API页面暴露的字段名称严格一致。确认「Action Type」「No.」「Line No.」在API页面的字段定义中，是否使用Name属性指定了小写的actionType、no、lineNo。如果没有显式指定，Business Central可能会生成带有空格或原表字段名的键字段（比如ActionType或Action%20Type），导致匹配失败。
验证复合键的OData格式与完整路径：虽然格式看似符合规范，但需注意Business Central对复合键的大小写、引号使用有严格要求。尝试使用全大写的键名（如ACTIONTYPE='Place'），或者确认数字类型的lineNo是否无需引号（当前写法正确，但需匹配字段实际类型）。另外，确保请求URL包含完整的API前缀，比如/api/[你的publisher]/Reporting/v2.0/warehouseActivityLine(...)，缺失前缀会导致路由错误返回404。
强制刷新元数据缓存：沙箱环境的元数据缓存可能存在延迟，即使重新发布页面，客户端或服务器端缓存仍未更新。可尝试：
- 清除调用工具（如Postman）的本地缓存，重新获取服务元数据；
- 在请求URL后添加?no-cache参数强制绕过缓存；
- 若有权限，在Business Central管理中心重启沙箱环境。
检查权限配置：集合GET请求仅需读取权限，而PATCH需要修改权限。若API页面的权限集未包含「Warehouse Activity Line」表的修改权限，部分场景下会返回404而非权限错误，需确认权限配置是否完整。
核对源表主键与ODataKeyFields：确认「Warehouse Activity Line」表的主键是否和ODataKeyFields指定的字段、顺序完全一致。如果源表主键包含其他字段或顺序不同，API将无法正确定位记录。
启用API日志排查细节：在Business Central中启用API请求日志，查看服务器端对该PATCH请求的处理日志，获取字段不匹配、主键校验失败等具体错误信息，定位问题根源。

内容的提问来源于stack exchange，提问作者LordOrbnauticus