如何通过Microsoft Graph根据邮箱查询获取指定用户详情

现有代码问题说明 #

• 当前调用的是全量用户列取接口，接口默认采用分页返回机制，单页最大返回100条数据，未携带任何筛选参数，自然无法精准定位目标用户。
• 不建议循环拉取全部分页拿到所有用户后再本地匹配，该方案在租户用户量大时性能极差，还容易触发Graph接口限流。

具体实现代码 #

根据邮箱属性筛选用户时，需要额外在请求头添加ConsistencyLevel: eventual，否则接口会返回属性不支持筛选的报错：

// 替换为实际要查询的目标邮箱地址
string targetMail = "xxx@yourtenant.com";

var queryResult = await graphServiceClient.Users
    .Request()
    // 添加必要请求头支持mail属性筛选
    .Header("ConsistencyLevel", "eventual")
    // 配置筛选规则，精确匹配邮箱字段
    .Filter($"mail eq '{targetMail}'")
    // 按需指定返回字段，减少不必要的数据传输
    .Select(u => new {
        u.Id,
        u.DisplayName,
        u.Mail,
        u.JobTitle,
        u.MobilePhone,
        u.OfficeLocation,
        u.Department
    })
    .Top(1) // 仅返回1条匹配结果
    .GetAsync();

// 拿到匹配的用户实体，无匹配时返回null
var targetUser = queryResult.FirstOrDefault();

更优场景简化方案 #

如果你的租户内用户的UserPrincipalName（用户主体名）和邮箱地址完全一致，可以直接通过用户唯一标识接口查询，不需要走筛选逻辑，性能更高：

// 直接以邮箱（即UPN）作为用户id查询
var targetUser = await graphServiceClient.Users[targetMail]
    .Request()
    .Select(u => new {
        u.Id,
        u.DisplayName,
        u.Mail,
        u.JobTitle,
        u.Department
    })
    .GetAsync();

注意：如果使用筛选方案，不要遗漏ConsistencyLevel请求头，否则会请求失败。

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