SharePoint API筛选URL格式异常问题排查求助

嘿，我之前也踩过SharePoint API筛选请求的坑——移除筛选就正常，一加就报格式异常，大概率是这几个常见问题没注意到，给你梳理下排查方向：

1. 务必使用字段的内部名称而非显示名称 #

SharePoint的自定义字段在API中不认显示名称，必须用系统生成的内部名称。比如你显示名称是「项目优先级」，内部名称可能是Project_x0020_Priority（空格会被转义成_x0020_）。

• 怎么获取内部名称？进入列表设置→点击目标字段，看浏览器地址栏里的Field=xxx参数，xxx就是内部名称。

2. 筛选语法要严格符合OData规范 #

不同类型字段的筛选写法差异很大，写错就会触发格式异常：

• 字符串字段：值必须用单引号包裹，运算符用小写eq/ne，比如：$filter=CustomField eq '测试内容'
• 数字/日期字段：不用单引号，日期要转成ISO8601格式并加datetime前缀，比如：$filter=CreateTime ge datetime'2024-05-01T00:00:00Z'
• 逻辑运算符：and/or要小写，多条件嵌套必须用括号，比如：$filter=(Title eq '文档') and (CreateTime ge datetime'2024-05-01')
• 注意：所有运算符区分大小写，写EQ会直接报错！

3. 特殊字符必须做URL编码 #

筛选条件里的空格、单引号、&等特殊字符，必须转成URL编码格式：

• 空格→%20
• 单引号→%27
• 比如筛选CustomField eq '我的项目'，编码后应该是：$filter=CustomField%20eq%20%27%E6%88%91%E7%9A%84%E9%A1%B9%E7%9B%AE%27

4. 确认字段是否支持筛选 #

不是所有字段都能用$filter：

• 多值选择字段、计算字段、超链接字段等，直接筛选可能不支持，需要用特殊语法（比如多值字段用any运算符）
• 如果是这类字段，建议先测试简单的文本/数字字段筛选是否正常，排除字段类型问题

5. 请求头的OData版本要匹配 #

确保请求头里指定了正确的OData版本，比如：

Accept: application/json;odata=verbose

旧版本的OData对筛选的支持有限，用verbose或nometadata版本兼容性更好。

举个正确的示例：
假设自定义字段内部名称是ProjectCode，字符串类型，值是SP-2024-001，完整请求URL应该是：

https://your-site.sharepoint.com/_api/web/lists/getbytitle('项目列表')/items?$filter=ProjectCode eq 'SP-2024-001'

如果有空格需要编码，就改成：

https://your-site.sharepoint.com/_api/web/lists/getbytitle('项目列表')/items?$filter=ProjectCode%20eq%20%27SP-2024-001%27

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