SharePoint Rest API查询列表文件仅在存在文件时报未知500错误

• 文档库配置触发全量扫描异常：/_api/web/lists/Documents/Files端点会一次性拉取整个文档库所有层级的所有文件元数据，若客户站点的文档库开启了强制签出、内容审批、信息权限管理(IRM) 其中任意一项配置，且库中存在处于草稿状态、未审批、受IRM保护的文件时，默认不带筛选参数的全量请求会触发SharePoint后台权限校验逻辑异常，返回未定义的500错误。你内部测试站点未开启上述配置因此无异常，而GetFolderByServerRelativeUrl端点仅拉取指定路径下的文件，不会触发全库权限校验，因此可正常返回。
• 隐性权限配置问题：客户站点可能对库层级配置了自定义权限继承规则，或者对特定字段设置了读取权限限制，全量拉取文件时后台尝试读取无权限的字段/文件元数据导致服务崩溃，单文件夹拉取时未触及无权限资源因此无异常。
• 查询阈值触发：若客户站点的文档库条目数已经接近或超过列表视图阈值（默认5000条），无筛选条件的全量Files请求会触发阈值拦截，部分旧版SharePoint环境不会返回明确的阈值错误，而是抛出通用UnknownError。

• 优先使用路径级拉取接口：保持目前使用/_api/Web/GetFolderByServerRelativeUrl('{文件夹相对路径}')/Files的方案，该接口性能更稳定，也符合SharePoint REST API的官方推荐实践，可避免全库扫描带来的各类异常。
• 为全量接口添加必要参数：如果必须使用Lists下的Files接口，请求时添加$top参数限制单次拉取数量，同时添加请求头Accept: application/json;odata=nometadata减少返回字段，示例请求：

  GET {{mainLink}}sites/{{subsite}}/_api/web/lists/Documents/Files?$top=100
  Headers:
  Accept: application/json;odata=nometadata
  

• 联系客户侧检查库配置：确认目标文档库是否开启强制签出、内容审批、IRM保护，若开启可针对接口调用账号添加对应的草稿查看、审批权限，或者关闭不必要的配置项。
• 排查自定义字段异常：若文档库存在自定义的字段类型（比如第三方插件扩展的字段），可在请求中添加$select参数指定仅返回需要的标准字段，避免读取异常字段导致报错，示例：

  GET {{mainLink}}sites/{{subsite}}/_api/web/lists/Documents/Files?$select=Name,ServerRelativeUrl,TimeCreated
  

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