Azure Graph 通过ImmutableId检索用户失败及过滤问题排查

看起来你遇到的问题核心在于旧版Azure AD Graph API的URL参数格式、编码细节，以及语法规范——毕竟直接通过GUID能查到用户，说明权限和用户本身是没问题的，下面一步步帮你定位解决：

1. 先修正最可能的URL参数错误 #

你给出的URI里用了&，这是HTML转义后的&符号，但直接在HTTP请求里使用这个会导致API无法正确解析参数！比如你的请求路径：

https://graph.windows.net/{tenant}/users?&api-version={version}?$filter=...

正确的格式应该用原始的&来分隔参数，第一个参数用?开头，后续参数用&：

https://graph.windows.net/{tenant}/users?api-version={version}&$filter=immutableId eq '{encoded_id}'

&是给HTML页面用的转义字符，直接放在请求URL里会被API当成参数的一部分，导致$filter根本没被识别，自然过滤无效。

2. ImmutableId的编码必须精确 #

ImmutableId在Azure AD里是Base64编码的字符串，查询时需要注意两个点：

• 必须使用和Azure AD中完全一致的Base64值：你手动看到的immutableId可能有隐藏的空格/换行，建议先通过GUID查询拿到精确值（就是你能成功调用的那个接口返回的immutableId字段），直接复制这个值来用。
• 必须做URL编码：Base64里的+、/、=这些字符在URL里有特殊含义，必须转成URL编码形式，比如：
  • + → %2B
  • / → %2F
  • = → %3D
    举个例子，如果你的immutableId是abc+def/ghi=，编码后应该是abc%2Bdef%2Fghi%3D，再放到$filter里：

  https://graph.windows.net/{tenant}/users?api-version=1.6&$filter=immutableId eq 'abc%2Bdef%2Fghi%3D'
  

3. 验证过滤语法的正确性 #

旧版Azure AD Graph的$filter语法有一些细节要注意：

• 对于displayName的startswith查询，确保单引号里的内容没有多余空格，且语法正确：

  https://graph.windows.net/{tenant}/users?api-version=1.6&$filter=startswith(displayName,'{startofuid}')
  

• 检查API版本：建议使用1.6（旧版Graph的稳定版本），过低的版本可能对某些过滤支持不好。

4. 额外建议：尽快迁移到Microsoft Graph #

Azure AD Graph（graph.windows.net）已经被官方弃用，后续不会再更新，而且Microsoft Graph（graph.microsoft.com）的过滤逻辑更清晰、支持性更好。比如查询immutableId的接口在Microsoft Graph里是：

https://graph.microsoft.com/v1.0/users?$filter=onPremisesImmutableId eq '{encoded_id}'

迁移后不仅能解决这类问题，还能获得更多功能支持。

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