获取 singleValueLegacyExtendedProperty
命名空间:microsoft.graph
可以获取使用特定扩展属性扩展的单个资源实例,或包含与筛选器匹配的扩展属性的资源实例集合。
使用查询参数 $expand
,可以获取使用特定的扩展属性扩展的指定资源实例。 在 id 属性上使用 $filter
和 eq
运算符来指定扩展属性。 这是当前获取 singleValueLegacyExtendedProperty 对象(表示扩展属性)的唯一方式。
要获取具有某些扩展属性的资源实例,请使用 $filter
查询参数并在 id 属性上应用 eq
运算符。 另外,对于数字扩展属性,请在 value 属性上应用以下某个运算符:eq
、ne
、ge
、gt
、le
或 lt
。 对于字符串类型的扩展属性,请在 value 上应用 contains
、startswith
、eq
或 ne
运算符。
该筛选器应用于资源在已登录用户的邮箱中的所有实例。
在扩展属性的 id 中筛选字符串名称 (Name
) 是区分大小写的。 筛选扩展属性的 value 属性是区分大小写的。
支持以下用户资源:
以及以下组资源:
有关何时使用开放扩展或扩展属性,以及如何指定扩展属性的详细信息,请参阅扩展属性概述。
此 API 可用于以下国家级云部署。
全局服务 | 美国政府 L4 | 美国政府 L5 (DOD) | 由世纪互联运营的中国 |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
权限
根据要从中获取扩展属性的资源以及请求 (委托或应用程序) 的权限类型,下表中指定的权限是调用此 API 所需的最低权限。 若要了解详细信息,包括如何选择权限的信息,请参阅权限。
支持的资源 | 委派(工作或学校帐户) | 委派(个人 Microsoft 帐户) | 应用程序 |
---|---|---|---|
calendar | Calendars.Read | Calendars.Read | Calendars.Read |
联系人 | Contacts.Read | Contacts.Read | Contacts.Read |
contactFolder | Contacts.Read | Contacts.Read | Contacts.Read |
event | Calendars.Read | Calendars.Read | Calendars.Read |
组 日历 | Group.Read.All | 不支持 | 不支持 |
组 事件 | Group.Read.All | 不支持 | 不支持 |
组帖子 | Group.Read.All | 不支持 | Group.Read.All |
mailFolder | Mail.Read | Mail.Read | Mail.Read |
邮件 | Mail.Read | Mail.Read | Mail.Read |
HTTP 请求
获取通过与筛选器匹配的扩展属性扩展的资源实例
获取通过与 id 属性中的筛选器匹配的扩展属性展开的资源实例。 请确保对筛选器字符串中的空白字符应用 URL 编码。
获取邮件实例:
GET /me/messages/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
GET /users/{id|userPrincipalName}/messages/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
GET /me/mailFolders/{id}/messages/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
获取 mailFolder 实例:
GET /me/mailFolders/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
GET /users/{id|userPrincipalName}/mailFolders/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
获取事件实例:
GET /me/events/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
GET /users/{id|userPrincipalName}/events/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
获取日历实例:
GET /me/calendars/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
GET /users/{id|userPrincipalName}/calendars/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
获取联系人实例:
GET /me/contacts/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
GET /users/{id|userPrincipalName}/contacts/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
GET /me/contactFolders/{id}/contacts/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
GET /users/{id|userPrincipalName}/contactFolders/{id}/contacts/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
获取 contactFolder 实例:
GET /me/contactfolders/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
GET /users/{id|userPrincipalName}/contactFolders/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
获取组事件实例:
GET /groups/{id}/events/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
获取组 post 实例:
GET /groups/{id}/threads/{id}/posts/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
GET /groups/{id}/conversations/{id}/threads/{id}/posts/{id}?$expand=singleValueExtendedProperties($filter=id eq '{id_value}')
获取包括与筛选器匹配的数值扩展属性的资源实例
获取支持的资源实例,其中包含与筛选器匹配的数字扩展属性。 筛选器在 id 属性上使用 eq
运算符,并在 value 属性上使用以下运算符之一:eq
、ne
、ge
、gt
、le
或 lt
。
请务必对筛选器字符串中的以下字符应用 URL 编码:冒号、正斜杠和空格。
以下语法行显示对 id 使用 eq
运算符的筛选器,对属性值使用另一个 eq
运算符。 可以使用适用于数值的其他运算符中的任何一个(ne
、ge
、gt
、le
或 lt
)替换 value 上的 eq
运算符。
获取 message 实例:
GET /me/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /users/{id|userPrincipalName}/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /me/mailFolders/{id}/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
获取 mailFolder 实例:
GET /me/mailFolders?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /users/{id|userPrincipalName}/mailFolders?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
获取事件实例:
GET /me/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /users/{id|userPrincipalName}/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
获取日历实例:
GET /me/calendars?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /users/{id|userPrincipalName}/calendars?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
获取联系人实例:
GET /me/contacts?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /users/{id|userPrincipalName}/contacts?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /me/contactFolders/{id}/contacts?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /users/{id|userPrincipalName}/contactFolders/{id}/contacts?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
获取 contactFolder 实例:
GET /me/contactfolders?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /users/{id|userPrincipalName}/contactFolders?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
获取组事件实例:
GET /groups/{id}/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
获取组 post 实例:
GET /groups/{id}/threads/{id}/posts?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /groups/{id}/conversations/{id}/threads/{id}/posts?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
获取资源实例,其中包括与筛选器匹配的字符串类型的扩展属性
获取 message 或 event 资源的实例,其中包括与筛选器匹配的字符串类型的扩展属性。 筛选器在 id 属性上使用 eq
运算符,并在 value 属性上使用以下运算符之一:contains
、startswith
、eq
或 ne
。 请务必对筛选器字符串中的以下字符应用 URL 编码:冒号、正斜杠和空格。
获取 message 实例:
GET /me/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and contains(ep/value, '{property_value}'))
GET /users/{id|userPrincipalName}/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and contains(ep/value, '{property_value}'))
GET /me/mailFolders/{id}/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and contains(ep/value, '{property_value}'))
GET /me/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and startswith(ep/value, '{property_value}'))
GET /users/{id|userPrincipalName}/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and startswith(ep/value, '{property_value}'))
GET /me/mailFolders/{id}/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and startswith(ep/value, '{property_value}'))
GET /me/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /users/{id|userPrincipalName}/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /me/mailFolders/{id}/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /me/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value ne '{property_value}')
GET /users/{id|userPrincipalName}/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value ne '{property_value}')
GET /me/mailFolders/{id}/messages?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value ne '{property_value}')
获取 event 实例:
GET /me/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and contains(ep/value, '{property_value}'))
GET /users/{id|userPrincipalName}/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and contains(ep/value, '{property_value}'))
GET /me/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and startswith(ep/value, '{property_value}'))
GET /users/{id|userPrincipalName}/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and startswith(ep/value, '{property_value}'))
GET /me/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /users/{id|userPrincipalName}/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /me/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value ne '{property_value}')
GET /users/{id|userPrincipalName}/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value ne '{property_value}')
获取组 event 实例:
GET /groups/{id}/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and contains(ep/value, '{property_value}'))
GET /groups/{id}/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and startswith(ep/value, '{property_value}'))
GET /groups/{id}/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}')
GET /groups/{id}/events?$filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value ne '{property_value}')
路径参数
参数 | 类型 | 说明 |
---|---|---|
id_value | String | 要匹配的扩展属性的 ID。 它必须遵照其中一种支持的格式。 有关详细信息,请参阅 Outlook 扩展属性概述。 必需。 |
property_value | String | 要匹配的扩展属性的值。 如果在上面的 HTTP 请求部分中列出,则为必需参数。 如果 {property_value} 不是字符串,请务必在与 {property_value} 比较时,将 ep/value 显式转换为相应的 Edm 数据类型。 有关示例,请参阅下面的请求 4。 |
请求标头
名称 | 说明 |
---|---|
Authorization | 持有者 {token}。 必填。 详细了解 身份验证和授权。 |
请求正文
请勿提供此方法的请求正文。
响应
如果成功,此方法返回 200 OK
响应代码。
获取通过匹配的扩展属性扩展的资源实例
响应正文包括通过匹配的 singleValueLegacyExtendedProperty 对象扩展的对象,此对象表示请求的资源实例。
获取包含与筛选器匹配的扩展属性的资源实例
响应主体包含一个或多个对象,它们表示包含匹配的扩展属性的资源实例。 响应正文不包含扩展属性。
示例
请求 1
第一个示例通过包含一个单值扩展属性获取并展开指定的邮件。 此筛选器返回其 id 与 String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color
字符串(包含 URL 编码,此处为了便于阅读,已将其删除)匹配的扩展属性。
GET https://graph.microsoft.com/v1.0/me/messages/AAMkAGE1M2_bs88AACHsLqWAAA=?$expand=singleValueExtendedProperties($filter=id%20eq%20'String%20{66f5a359-4659-4830-9070-00047ec6ac6e}%20Name%20Color')
响应 1
响应正文包括指定邮件的所有属性以及此筛选器返回的扩展属性。
注意:为了简单起见,会将此处所示的邮件对象截断。 将从实际调用中返回所有属性。
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Me/messages/$entity",
"@odata.id": "https://graph.microsoft.com/v1.0/users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/messages('AAMkAGE1M2_bs88AACHsLqWAAA=')",
"@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AACbyS4H\"",
"id": "AAMkAGE1M2_bs88AACHsLqWAAA=",
"subject": "RE: Talk about emergency prep",
"sender": {
"emailAddress": {
"name": "Christine Irwin",
"address": "christine@contoso.com"
}
},
"from": null,
"toRecipients": [
{
"emailAddress": {
"name": "Christine Irwin",
"address": "christine@contoso.com"
}
}
],
"singleValueExtendedProperties": [
{
"id": "String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color",
"value": "Green"
}
]
}
请求 2
第二个示例展示了如何获取具有筛选器中指定的字符串类型单值扩展属性的邮件。 此筛选器查找如下扩展属性:
它的 id 等同于字符串
String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color
(包含 URL 编码,但此处为了方便阅读,已将其删除)。它的 value 等于字符串
Green
。
GET https://graph.microsoft.com/v1.0/me/messages?$filter=singleValueExtendedProperties%2FAny(ep%3A%20ep%2Fid%20eq%20'String%20{66f5a359-4659-4830-9070-00047ec6ac6e}%20Name%20Color'%20and%20ep%2Fvalue%20eq%20'Green')
响应 2
成功的响应将由 HTTP 200 OK
响应代码表示,响应正文包括其扩展属性与筛选器匹配的邮件的所有属性。 响应正文是类似于获取邮件集合中的响应。 响应中不包含匹配的扩展属性。
请求 3
第三个示例展示了如何获取具有筛选器中指定的字符串类型单值扩展属性的邮件。 此筛选器查找如下扩展属性:
它的 id 等同于字符串
String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color
(包含 URL 编码,但此处为了方便阅读,已将其删除)。它的 value 包含字符串
green
。
GET https://graph.microsoft.com/v1.0/Me/messages?$filter=singleValueExtendedProperties/any(ep:ep/Id eq 'String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color' and contains(ep/Value, 'green'))
响应 3
成功的响应将由 HTTP 200 OK
响应代码表示,响应正文包括其扩展属性与筛选器匹配的邮件的所有属性。 例如,具有 ID 等于字符串String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color
和 值Light green
的单值扩展属性的消息将匹配筛选器并包含在响应中。
响应正文类似于获取邮件集合中的响应。 响应中不包含匹配的扩展属性。
请求 4
接下来的两个示例展示了如何获取具有非字符串类型单值扩展属性的邮件。 为了方便阅读,从中删除了必要的 URL 编码。
下面的示例展示了查找以下扩展属性的筛选器:
它的 id 与字符串
CLSID {00062008-0000-0000-C000-000000000046} Name ConnectorSenderGuid
匹配。它的 value 是 GUID
b9cf8971-7d55-4b73-9ffa-a584611b600b
。 若要将属性值与 GUID 比较,请将ep/value
转换为Edm.Guid
。
GET https://graph.microsoft.com/v1.0/me/messages?$filter=singleValueExtendedProperties/any(ep:ep/id eq 'CLSID {00062008-0000-0000-C000-000000000046} Name ConnectorSenderGuid' and cast(ep/value, Edm.Guid) eq (b9cf8971-7d55-4b73-9ffa-a584611b600b))
接下来的示例展示了查找以下扩展属性的筛选器:
它的 id 与字符串
Integer {66f5a359-4659-4830-9070-00047ec6ac6e} Name Pallete
匹配。它的 value 等于整数 12。 若要将属性值与整数比较,请将
ep/value
转换为Edm.Int32
。
GET https://graph.microsoft.com/v1.0/me/messages?$filter=singleValueExtendedProperties/any(ep:ep/id eq 'Integer {66f5a359-4659-4830-9070-00047ec6ac6e} Name Pallete' and cast(ep/value, Edm.Int32) eq 12)
响应 4
对于前面两个示例中的任意一个,成功响应由 HTTP 200 OK
响应代码表示,响应正文包括扩展属性与相应筛选器匹配的邮件的所有属性。 响应正文类似于获取邮件集合中的响应。 响应中不包含匹配的扩展属性。