无法通过单值扩展属性筛选Microsoft Graph API的mailFolder资源

问题描述 #

我尝试为Outlook中的mailFolder添加单值扩展属性，之后通过该属性检索对应的文件夹。已成功创建带扩展属性的文件夹，且可通过$expand查询参数查看该属性，但尝试检索时却出现错误。

已确认的文件夹及属性状态 #

通过$expand查询得到的响应：

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('patrick.ivy%40newburnlaw.com')/mailFolders(singleValueExtendedProperties())/$entity",
    "id": "AAMkADE5YjAwNzQ3LTc0ZjItNGZhYi1iYTYzLTdkZGYzZmUwMDhiZQAuAAAAAABi_R1_L2WOSbhsPsT-ky8qAQAkYDjZMs8-SbldF0OOgsibAAALsLZ3AAA=",
    "displayName": "Test Folder",
    "parentFolderId": "AAMkADE5YjAwNzQ3LTc0ZjItNGZhYi1iYTYzLTdkZGYzZmUwMDhiZQAuAAAAAABi_R1_L2WOSbhsPsT-ky8qAQAkYDjZMs8-SbldF0OOgsibAAAAAAEIAAA=",
    "childFolderCount": 0,
    "unreadItemCount": 0,
    "totalItemCount": 0,
    "sizeInBytes": 0,
    "isHidden": false,
    "singleValueExtendedProperties": [
        {
            "id": "Integer {00000000-0000-0000-0000-000000000001} Name TestProperty",
            "value": "1234567"
        }
    ]
}

检索时使用的API调用（已去除URL编码） #

https://graph.microsoft.com/v1.0/users/patrick.ivy@newburnlaw.com/mailFolders?$filter=singleValueExtendedProperties/Any(ep: ep/id eq 'Integer {00000000-0000-0000-0000-000000000001} Name TestProperty' and ep/value eq '1234567')

收到的错误响应 #

{
    "error": {
        "code": "ErrorInvalidUrlQueryFilter",
        "message": "The filter expression for $filter does not match to a single extended property and a value restriction."
    }
}

问题原因及解决方法 #

错误的核心原因是扩展属性ID的格式不符合筛选查询的要求。虽然创建和$expand查询时可以使用带Name关键字的格式，但在$filter筛选时必须省略Name，只保留「数据类型+GUID+属性名称」的精简结构。

正确的API调用（已去除URL编码） #

https://graph.microsoft.com/v1.0/users/patrick.ivy@newburnlaw.com/mailFolders?$filter=singleValueExtendedProperties/Any(ep: ep/id eq 'Integer {00000000-0000-0000-0000-000000000001} TestProperty' and ep/value eq '1234567')

关键说明 #

• 创建扩展属性时，带Name的格式是合法的，但筛选查询时必须去掉Name关键字，否则Graph API无法识别为匹配单个扩展属性的限制条件。
• 这个格式限制是Microsoft Graph针对扩展属性筛选的特定规则，确保筛选表达式能精准定位到目标属性。

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