通过Graph API搜索SharePoint列表项的方法咨询

一、替代无效search参数的正确筛选方法 #

你用的search参数在列表项接口中不生效，应该用$filter参数针对文件夹属性做精准筛选，以下是常用场景：

1. 按文件夹名称筛选 #

• 先通过FileSystemObjectType eq 1过滤出文件夹（文件对应值为0），再搭配名称匹配：
  • 模糊匹配（名称包含关键词）：

    /sites/{site-id}/lists/{list-id}/items?$filter=FileSystemObjectType eq 1 and substringof('目标关键词', FileLeafRef)
    

  • 精确匹配（完全匹配文件夹名）：

    /sites/{site-id}/lists/{list-id}/items?$filter=FileSystemObjectType eq 1 and FileLeafRef eq '目标文件夹名称'
    

2. 按父文件夹路径筛选 #

如果要找某个指定父文件夹下的子文件夹，用Folder/ServerRelativeUrl定位路径：

/sites/{site-id}/lists/{list-id}/items?$filter=FileSystemObjectType eq 1 and Folder/ServerRelativeUrl eq '/sites/你的站点名/Shared Documents/父文件夹路径'

二、$expand参数的实际用法 #

$expand是用来展开关联实体属性的，不是用来筛选的，比如你需要同时获取文件夹的父文件夹详情、关联元数据时才需要用到：

/sites/{site-id}/lists/{list-id}/items?$filter=FileSystemObjectType eq 1&$expand=Folder

返回结果中每个条目会附带Folder对象，包含该文件夹的Name、ServerRelativeUrl、UniqueId等详细属性。

三、大量结果的分页处理 #

如果筛选后仍有数百条数据，用$top和$skip做分页请求，避免单次返回数据过载：

/sites/{site-id}/lists/{list-id}/items?$filter=FileSystemObjectType eq 1 and substringof('关键词', FileLeafRef)&$top=100&$skip=0

每次请求递增$skip的值（比如下一页用$skip=100）来获取后续数据。

四、注意事项 #

• 确保请求账号拥有目标站点和文档库的访问权限
• SharePoint Online环境下，API端点需以https://{tenant}.sharepoint.com/_api/v1.0/开头
• 路径或名称中的特殊字符需做URL编码（比如空格替换为%20）

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