获取 singleValueLegacyExtendedProperty

通过使用 $expand$filter 获取包含单值扩展属性的资源实例。

使用查询参数 $expand 可以获得使用指示扩展属性扩展的指定实例。这是当前获得 singleValueLegacyExtendedProperty 对象(表示扩展属性)的唯一方式。

使用查询参数 $filter获得指定资源的所有实例,这些实例具有与 id 中的筛选器匹配的扩展属性以及 value 属性。该筛选器应用于资源在已登录用户的邮箱中的所有实例。

支持以下用户资源:

以及以下组资源:

有关何时使用开放扩展或扩展属性,以及如何指定扩展属性的详细信息,请参阅扩展属性概述

权限

若要调用此 API,必须有以下权限之一,具体视要获取的资源而定。要了解详细信息,包括如何选择权限的信息,请参阅权限

  • Mail.Read
  • Calendars.Read
  • Contacts.Read
  • Group.Read.All

HTTP 请求

使用 $expand 获取资源实例

获取通过与 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}')

获取组帖子实例:

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}')

使用 $filter 获取资源实例

获取支持的资源实例,这些实例具有与 id 中的筛选器匹配的扩展属性以及 value 属性。请确保对筛选器字符串中的空格字符应用 URL 编码 - 正斜杠和空格。

获取邮件实例:

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}')

获取组帖子实例:

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}')

参数

参数 类型 说明
URL parameters    
id_value String 要匹配的扩展属性的 ID。它必须遵照其中一种支持的格式。有关详细信息,请参阅 Outlook 扩展属性概述。必需。
property_value String 要匹配的扩展属性的值。上面 HTTP 请求部分中列出的所必需的参数。

请求标头

名称 说明
Authorization Bearer {token}。必需。

请求正文

请勿提供此方法的请求正文。

响应

如果成功,此方法返回 200 OK 响应代码。

使用 $expand 获取资源实例

响应正文包括通过匹配的 singleValueLegacyExtendedProperty 对象扩展的对象,此对象表示请求的资源实例。

使用 $filter 获取资源实例

响应正文包含一个或多个表示资源实例的对象,这些实例包含匹配的扩展属性。响应正文不包含扩展属性。

示例

请求 1

第一个示例通过包含一个单值扩展属性获取并展开指定的邮件。此筛选器返回其 idString {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@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Me/messages('AAMkAGE1M2_bs88AACHsLqWAAA%3D')/singleValueExtendedProperties",
    "singleValueExtendedProperties": [
        {
            "id": "String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color",
            "value": "Green"
        }
    ]
}

请求 2

第二个示例获���具有筛选器中指定的单值扩展属性的邮件。此筛选器将返回如下的扩展属性: - 其 idString {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color 字符串(包含 URL 编码,此处为了便于阅读,已将其删除)匹配。 - 其Green

GET https://graph.microsoft.com/api/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 响应代码表示,响应正文包括其扩展属性与筛选器匹配的邮件的所有属性。响应正文是类似于获取邮件集合中的响应。该响应不包括匹配的扩展属性。