Tips on using $filter with MS Graph API endpoint `https://graph.microsoft.com/v1.0/groups/{group-id}/drives/{drive-id}/items`

近日，微软 Graph 社区多位开发者围绕一个高频问题展开讨论：如何正确使用 $filter 参数对 OneDrive 或 SharePoint 文档库中的文件进行精准查询？本文结合官方文档与实测经验，梳理出在 https://graph.microsoft.com/v1.0/groups/{group-id}/drives/{drive-id}/items 端点下使用 $filter 的关键技巧与避坑指南。

背景：为何需要 `$filter`？

在 Microsoft Graph 中，drives 资源代表 OneDrive 或 SharePoint 文档库，其下的 items 集合往往包含成千上万个文件与文件夹。直接调用 /items 端点会返回大量数据，既影响性能又增加网络开销。此时，$filter 参数允许开发者通过 OData 查询语法指定筛选条件，仅返回符合条件的项，极大提升效率。

例如，仅查找名为“Report.docx”的文件：

GET /groups/{group-id}/drives/{drive-id}/items?$filter=name eq 'Report.docx'

核心技巧：支持哪些属性与运算符？

根据 Microsoft 官方文档，items 端点支持对部分标准属性进行筛选，常见可用的属性包括：

属性	类型	说明
`name`	String	文件名（区分大小写）
`size`	Int64	文件大小（字节）
`lastModifiedDateTime`	DateTimeOffset	最后修改时间（UTC）
`createdDateTime`	DateTimeOffset	创建时间
`file.mimeType`	String	文件 MIME 类型（需注意嵌套属性写法）
`folder.childCount`	Int32	文件夹内子项数量

支持的运算符：eq（等于）、ne（不等于）、gt/ge/lt/le（数值或日期比较）、and/or 逻辑组合、startswith、contains（字符串匹配）。

注意：并非所有 OData 标准函数都支持。例如 endswith、any、all 在 items 端点不可用。

实战场景一：按时间范围筛选

企业常需要查询最近一周修改的文档：

GET /groups/{group-id}/drives/{drive-id}/items?$filter=lastModifiedDateTime ge 2025-03-01T00:00:00Z and lastModifiedDateTime lt 2025-03-08T00:00:00Z

需要留意时间必须使用 ISO 8601 格式，且推荐加上 Z 表示 UTC。若本地时间与 UTC 存在偏差，务必在客户端做转换。

实战场景二：按文件类型过滤

若要筛选所有 PDF 文件，不能直接写 file.mimeType eq 'application/pdf'，因为 file 是一个导航属性，mimeType 是其子属性。正确的写法：

GET /groups/{group-id}/drives/{drive-id}/items?$filter=file/mimeType eq 'application/pdf'

注意斜杠 / 表示属性路径。同样，想查找文件夹可以使用 folder ne null。

实战场景三：结合分页与排序

$filter 常与 $top、$orderby 搭配使用。例如，取最大的5个文件：

GET /groups/{group-id}/drives/{drive-id}/items?$filter=size gt 1000&$orderby=size desc&$top=5

但需注意：$top 最大值为 999（Graph 默认限制），且 $filter 后返回的结果可能包含 @odata.nextLink，需要循环请求才能获取全部数据。

踩坑记录：常见错误及解决方案

未对值加单引号：字符串必须用单引号包裹，数字和日期不用。例如 name eq 'file.txt' 正确，name eq file.txt 会报错。
特殊字符转义：文件名中的单引号本身需双写表示，如 name eq 'O''Brien.docx'。
属性名大小写：file.mimeType 中的 mimeType 首字母小写（注意 M 小写），而 folder 和 file 本身是导航属性。
不支持跨文件夹递归筛选：$filter 只能针对当前目录（根目录）下的直接子项，无法搜索子文件夹内的文件。若要递归搜索，需使用 /search 端点或 query=... 参数。
权限影响：执行查询的访问令牌必须拥有对目标组或驱动器的读取权限（如 Files.Read 或 Files.Read.All），否则即使语法正确也会返回 403 或 404。

性能建议：先范围后过滤

当需要查询大量项时，官方建议优先使用 $filter 缩小范围，而不是先 $top 再在客户端过滤。另外可考虑将 lastModifiedDateTime 作为第一筛选条件，因为 Graph 后台对此属性建立了索引，能显著加快响应速度。

未来展望

微软 Graph 团队在 2024 年 Q4 更新中已预告将在 Drive Items 端点支持更多高级筛选能力，例如 any 对集合属性的过滤以及全文搜索的增强。开发者可以关注 Microsoft 365 Roadmap 上的相关条目，以便及时调整代码。

结语：$filter 是 Graph API 查询中的“瑞士军刀”，但只有精确掌握其语法边界与资源特性，才能真正发挥威力。建议开发者在测试阶段使用 Graph Explorer 工具反复验证筛选表达式，避免在生产环境中踩坑。如果你有更多实用技巧，欢迎在评论区分享交流。

背景：为何需要 $filter？