如何构建含德语变音符号等非英文字符的Microsoft Graph用户OData查询？

我之前在处理德语用户的Graph查询时也踩过这个坑，刚好能给你梳理下问题原因和解决办法：

为什么会出现这个问题？ #

Microsoft Graph对用户数据的字符串存储和查询匹配，默认会做ASCII折叠（变音符号映射）——比如把ü等价映射为u，所以你用startswith(surname,'mu')能匹配到Müller；但直接用带变音符号的查询条件时，容易因为两个原因失败：

1. URL编码不规范：变音符号如果没正确编码，服务器会解析错误甚至截断查询参数；
2. Unicode规范化不一致：你输入的ü可能是Unicode规范化形式D（NFD），而Graph存储的是形式C（NFC），导致字符串不匹配。

解决办法 #

1. 确保查询参数正确URL编码

这是最容易忽略也最常见的问题。德语变音符号（比如ü）的URL编码是%C3%BC，手动构造URL时必须替换，或者在代码里用工具自动编码。

正确的查询URL示例：

https://graph.microsoft.com/v1.0/myOrganization/users?$filter=startswith(surname,'m%C3%BC')

代码里的编码示例（Python）：

import urllib.parse
surname = "mü"
encoded_surname = urllib.parse.quote(surname)
# 拼接后的URL会自动带上正确编码的参数
query_url = f"https://graph.microsoft.com/v1.0/myOrganization/users?$filter=startswith(surname,'{encoded_surname}')"

PowerShell示例：

$targetSurname = "mü"
$encodedSurname = [Uri]::EscapeDataString($targetSurname)
$graphUrl = "https://graph.microsoft.com/v1.0/myOrganization/users`$filter=startswith(surname,'$encodedSurname')"
# 后续携带token发送请求即可

2. 使用OData normalize函数实现精确匹配

如果需要严格匹配带变音符号的姓氏（比如区分Müller和Muller），可以用OData的normalize函数，将存储的姓氏和查询条件统一为相同的Unicode规范化形式（Graph默认用NFC）：

https://graph.microsoft.com/v1.0/myOrganization/users?$filter=startswith(normalize(surname, 'NFC'), normalize('mü', 'NFC'))

这个方法能确保两边字符串的编码形式完全一致，避免因为规范化差异导致的匹配失败。

3. 使用$search参数进行灵活匹配

如果不需要精确的startswith逻辑，只是想模糊匹配包含变音或非变音的姓氏，可以用Graph的$search参数——它默认支持变音符号的等价匹配，不管你输入mu还是mü都能找到Müller：

https://graph.microsoft.com/v1.0/myOrganization/users?$search="surname:mü"

注意使用$search时需要请求头里带上ConsistencyLevel: eventual，否则会报错。

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