Microsoft Graph v5按名称查询SharePoint子站点：过滤失效与分页问题

核心问题分析 #

你的代码存在两个关键问题：

• 筛选条件不生效：错误使用了Name属性，且多余的Expand参数干扰了筛选逻辑
• 分页截断：Graph API返回子站点时默认分页，仅返回部分结果，未处理后续页面

解决方案及修改后的代码 #

1. 修正筛选逻辑 #

• 用displayName替代Name：Graph API中Site资源的displayName才是站点的显示名称，Name是内部标识（通常为URL路径片段），不支持筛选
• 移除Expand = "sites"：这个参数是展开子站点的子站点集合，和当前筛选父站点的直接子站点无关
• 使用编码后的站点名称：避免特殊字符导致筛选语法错误

2. 处理分页遍历 #

Graph API返回子站点默认分页（你的场景返回40条），需要通过@odata.nextLink循环获取所有页面，直到找到目标站点或遍历结束

public async Task<Site?> GetSiteSubSiteByNameAsync(string parentSiteId, string subSiteName)
{
    var encodedSubSiteName = System.Text.Encodings.Web.UrlEncoder.Default.Encode(subSiteName);
    var filterQuery = $"displayName eq '{encodedSubSiteName}'";

    try
    {
        // 初始化请求，设置筛选条件和最大页大小
        var pageResult = await _graphServiceClient
            .Sites[parentSiteId]
            .Sites
            .GetAsync(requestConfiguration =>
            {
                requestConfiguration.QueryParameters.Filter = filterQuery;
                requestConfiguration.QueryParameters.Top = 999; // 一次最多获取999条，减少请求次数
            });

        // 遍历所有分页结果
        while (pageResult != null)
        {
            // 在当前页查找目标站点，忽略大小写匹配
            var targetSite = pageResult.Value?.FirstOrDefault(s => 
                s.DisplayName.Equals(subSiteName, StringComparison.OrdinalIgnoreCase));
            if (targetSite != null)
            {
                return targetSite;
            }

            // 无下一页则终止遍历
            if (pageResult.OdataNextLink == null)
            {
                break;
            }

            // 请求下一页数据
            pageResult = await _graphServiceClient
                .Sites[parentSiteId]
                .Sites
                .GetAsync(requestConfiguration =>
                {
                    requestConfiguration.Url = pageResult.OdataNextLink;
                });
        }

        Trace.WriteLine($"未找到子站点({subSiteName})");
    }
    catch (Exception ex)
    {
        System.Diagnostics.Trace.TraceError(ex.ToString());
    }

    return null;
}

额外说明 #

• 页大小优化：设置Top = 999可以最大化单次请求的结果数量，减少分页请求次数
• 匹配容错：使用StringComparison.OrdinalIgnoreCase避免站点名称大小写不匹配的问题
• 性能优化：找到目标站点后立即返回，无需遍历所有分页数据

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