Outlook 扩展属性 REST API 参考 (beta)

项目
06/30/2018

备注

此版本的文档包含预览中的 Outlook 扩展属性 REST API。预览功能在最终确定之前可能会发生变化，并可能会让使用它们的代码无法正常运行。正因为如此，一般而言，生产代码中只应使用生产版本的 API。如果可用，v2.0 版目前是首选版本。

Outlook 扩展属性 REST API 允许应用程序存储自定义数据并为其提供一个回退机制，访问 _在 Outlook REST API 元数据中尚未公开_的 Outlook MAPI 属性的自定义数据。你可以使用扩展属性 API 来存储或获取消息、邮件文件夹、事件、日历、联系人、联系人文件夹、任务或已登录用户帐户的任务文件夹中的此类自定义数据。该帐户可以是 Office 365 帐户或 Microsoft 帐户（Hotmail.com、Live.com、MSN.com、Outlook.com 和 Passport.com）。

备注

为简便起见，本文的其余部分使用 Outlook.com 来指代这些 Microsoft 帐户域。

对 API 的 beta 版本不感兴趣？ 在左侧的目录中，转到 Office 365 REST API 引用部分，然后选择所需的版本。

使用扩展属性 REST API

扩展属性或数据扩展？

仅当您需要访问尚未通过 Outlook REST API 元数据公开的 Outlook MAPI 属性自定义数据时，才使用扩展属性和此 REST API。对于大多数情况下，你应该使用 Office 365 数据扩展和其 REST API 存储和访问用户邮箱中项目的自定义数据。你可以在 https://outlook.office.com/api/{version}/$metadata $metadata 验证元数据的属性，使用 v2.0、测试版等替换您选择的版本 {version}。

身份验证

与其他 Outlook REST API 类似，对于扩展属性 API 的每个请求，都应该包含有效的访问令牌。获取访问令牌需要注册和识别应用，并获得相应的授权。

你可以了解更多有关简化注册和授权选项的信息。在扩展属性 API 中继续执行特定操作时，请记住这一点。

API 版本

此 API 已从预览升级到正式发布 (GA) 状态。它在 Outlook REST API 的 v2.0 和测试版本中得到支持。

支持的 REST 资源

你可以为以下资源的实例创建扩展属性：

资源必须位于 Office 365 或 Outlook.com 中的登录用户邮箱中。

URL 参数

本文中的示例使用以下 ID 占位符作为 REST 请求 URL 的参数。你必须指定要为其创建扩展的资源实例的 ID。

参数	类型	说明
URL 参数
calendar_id	字符串	日历 ID。
contact_id	字符串	联系人 ID。
contactFolder_id	字符串	联系人文件夹 ID。
event_id	字符串	字符串
mailFolder_id	字符串	邮件文件夹 ID。
message_id	字符串	消息 ID。
propertyId_value	字符串	PropertyId 值是支持的格式之一。
property_value	字符串	扩展属性的值。
task_id	字符串	任务 ID。
taskFolder_id	字符串	字符串

有关 Outlook REST API 所有子集的更多信息，请参阅使用 Outlook REST API。

概述

你可以在实体实例 扩展属性 中动态创建和存储数据。具体取决于是否要存储（属于同一字段类型）的单个或多个值，您可以创建作为 SingleValueLegacyExtendedProperty或 MultiValueLegacyExtendedProperty 的扩展属性。

每种类型通过 PropertyId 进行标识并将数据存储在 Value 中。

可以使用 PropertyId 获取特定的实体实例以及扩展属性，或筛选单值扩展属性以获取拥有该属性的所有实例。

备注

不能使用 REST API 在一个调用中获取特定实例的所有扩展属性。

PropertyId 格式

创建单值或多值扩展属性时，以两种格式之一指定 PropertyId，即基于字符串名称或数字标识符，以及基于属性值或值的实际类型。以下两个表列出了指定单值和多值扩展属性时支持的格式。 {_type_} 表示一个或多个属性值的类型。在示例中显示的是字符串、整数和这些类型的数组。

由于扩展属性在大多数情况下与定义的 MAPI 属性（未在 Outlook REST API 元数据中公开）交互操作，为了简单起见，选定格式应反映相应 MAPI 属性在其 MAPI 属性标识符中使用字符串还是数字值。在 [MS-OXPROPS] Microsoft Corporation、Exchange Server 协议主属性列表中，可以找到将扩展属性映射到现有 MAPI 属性（例如属性标识符和 GUID）所需的信息。

备注

为 PropertyId 选择一种格式后，只能按此格式访问扩展属性。

单值扩展属性的有效 PropertyId 格式

格式	示例	说明
"{type} {guid} Name {name}"	`"String {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Name TestProperty"`	用所属的命名空间 (GUID) 和名称标识属性。
"{type} {guid} Id {id}"	`"Integer {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8012"`	用所属的命名空间 (GUID) 和标识符标识属性。

多值扩展属性的有效 PropertyId 格式

格式	示例	说明
"{type} {guid} Name {name}"	`"StringArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Name TestProperty"`	用命名空间 (GUID) 和名称标识属性。
"{type} {guid} Id {id}"	`"IntegerArray {8ECCC264-6880-4EBE-992F-8888D2EEAA1D} Id 0x8013"`	用命名空间 (GUID) 和标识符标识属性。

在现有项目中创建扩展属性

为指定的支持资源实例创建一个或多个扩展属性。每个扩展属性可以是单值或多值。

PATCH https://outlook.office.com/api/beta/me/messages('{message_id}')
PATCH https://outlook.office.com/api/beta/me/events('{event_id}')
PATCH https://outlook.office.com/api/beta/me/contacts('{contact_id}')
PATCH https://outlook.office.com/api/beta/me/tasks('{task_id}')
PATCH https://outlook.office.com/api/beta/me/mailfolders('{mailFolder_id}')
PATCH https://outlook.office.com/api/beta/me/calendars('{calendar_id}')
PATCH https://outlook.office.com/api/beta/me/contactfolders('{contactFolder_id}')
PATCH https://outlook.office.com/api/beta/me/taskfolders('{taskFolder_id}')

最低要求的范围

对应于目标资源的以下读/写范围之一：

https://outlook.office.com/mail.readwrite
https://outlook.office.com/calendars.readwrite
https://outlook.office.com/contacts.readwrite
https://outlook.office.com/tasks.readwrite
wl.imap
wl.calendars_更新
wl.events_创建
wl.contacts_创建

参数	类型	说明
正文参数
SingleValueExtendedProperties	集合（SingleValueLegacyExtendedProperty）	一个或多个单值扩展属性的数组。
PropertyId	字符串	对于 SingleValueExtendedProperties 集合中的每个属性，指定以识别属性。它必须遵循用于单值扩展属性的支持格式之一。必需。
值	字符串	对于SingleValueExtendedProperties 集合中的每个属性，指定属性值。必需。
MultiValueExtendedProperties	集合（MultiValueLegacyExtendedProperty）	一个或多个多值扩展属性的数组。
PropertyId	字符串	对于 MultiValueExtendedProperties 集合中的每个属性，指定以识别属性。它必须遵循用于多值扩展属性的支持格式之一。必需。
值	集合（字符串）	对于 MultiValueExtendedProperties 集合中的每个属性，指定以识别属性。必需。

示例请求

第一个示例为指定的消息创建一个单值扩展属性。该扩展属性是 SingleValueExtendedProperties 数组中的唯一元素。请求正文包含扩展属性的以下内容：

PropertyId 指定属性类型为 string、其 GUID 并将属性命名为 Color。
Value 指定 Green 为 Color 属性的值。

PATCH https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2_bs88AACHsLqWAAA=')

Content-Type: application/json

{
  "SingleValueExtendedProperties": [
      {
         "PropertyId":"String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color",
         "Value":"Green"
      }
    ]
}

示例响应

成功的响应由 HTTP 200 OK 响应代码表示，并在响应正文中包括指定的邮件，类似于更新邮件中的响应。该响应不包括新建的扩展属性。

示例请求

第二个示例为指定的消息创建一个多值扩展属性。该属性是 MultiValueExtendedProperties 数组中的唯一元素。请求正文包括：

PropertyId将此属性指定为包含指定 GUID 和 Palette 名称的字符串数组。
Value指定 Palette 为包含 3 个字符串值的数组（["Green", "Aqua", "Blue"]）。

PATCH https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2_as77AACHsLrBBBA=')

Content-Type: application/json

{
  "MultiValueExtendedProperties": [
      {
         "PropertyId":"StringArray {66f5a359-4659-4830-9070-00049ec6ac6e} Name Palette",
         "Value":["Green", "Aqua", "Blue"]
      }
    ]
}

示例响应

成功的响应由 HTTP 200 OK 响应代码表示，并在响应正文中包括指定的邮件，类似于更新邮件中的响应。该响应不包括新建的扩展属性。

若要查看新建的扩展属性，请获取通过扩展属性扩展的邮件。

在新项目中创建扩展属性

在新建一个支持的资源实例过程中，创建一个或多个扩展属性，均位于同一个 POST 调用中。将扩展属性或属性包含在 POST 请求的正文中。

POST https://outlook.office.com/api/beta/me/messages
POST https://outlook.office.com/api/beta/me/events
POST https://outlook.office.com/api/beta/me/contacts
POST https://outlook.office.com/api/beta/me/tasks
POST https://outlook.office.com/api/beta/me/mailfolders
POST https://outlook.office.com/api/beta/me/calendars
POST https://outlook.office.com/api/beta/me/contactfolders
POST https://outlook.office.com/api/beta/me/taskfolders

最低要求的范围

对应于目标资源的以下读/写范围之一：

https://outlook.office.com/mail.readwrite
https://outlook.office.com/calendars.readwrite
https://outlook.office.com/contacts.readwrite
https://outlook.office.com/tasks.readwrite
wl.imap
wl.calendars_更新
wl.events_创建
wl.contacts_创建

参数	类型	说明
正文参数
SingleValueExtendedProperties	集合（SingleValueLegacyExtendedProperty）	一个或多个单值扩展属性的数组。
PropertyId	字符串	对于 SingleValueExtendedProperties 集合中的每个属性，指定以识别属性。它必须遵循用于单值扩展属性的支持格式之一。必需。
值	字符串	对于SingleValueExtendedProperties 集合中的每个属性，指定属性值。必需。
MultiValueExtendedProperties	集合（MultiValueLegacyExtendedProperty）	一个或多个多值扩展属性的数组。
PropertyId	字符串	对于 MultiValueExtendedProperties 集合中的每个属性，指定以识别属性。它必须遵循用于多值扩展属性的支持格式之一。必需。
值	集合（字符串）	对于 MultiValueExtendedProperties 集合中的每个属性，指定以识别属性。必需。

示例请求

第一个示例创建一个新事件和一个单值扩展属性。除了通常为新事件包含的属性外，请求正文还包括 SingleValueExtendedProperties 数组，当中包含单值扩展属性以及属性的以下元素：

PropertyId 指定属性类型为 string、其 GUID 并将属性命名为 Fun。
Value 指定 Food 为 Fun 属性的值。

POST https://outlook.office.com/api/beta/me/events

Content-Type: application/json

{
  "Subject": "Celebrate Thanksgiving",
  "Body": {
    "ContentType": "HTML",
    "Content": "Let's get together!"
  },
  "Start": {
      "DateTime": "2015-11-26T18:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "End": {
      "DateTime": "2015-11-26T23:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "Terrie@contoso.com",
        "Name": "Terrie Barrera"
      },
      "Type": "Required"
    }
  ],
  "SingleValueExtendedProperties": [
     {
           "PropertyId":"String {66f5a359-4659-4830-9070-00040ec6ac6e} Name Fun",
           "Value":"Food"
     }
  ]
}

示例响应

成功的响应由 HTTP 201 Created 响应代码表示，并在响应正文中包括新事件，类似于仅创建事件中的响应。该响应不包括任何新建的扩展属性。

若要查看新建的扩展属性，请使用扩展属性获取扩展的项目。

示例请求

第二个示例在同一 POST 操作中的新事件中创建多值扩展属性。除了通常为新事件包含的属性外，请求正文还包括 MultiValueExtendedProperties数组，其中包含一个扩展属性。

请求正文包含以下多值扩展属性：

PropertyId将此属性指定为包含指定 GUID 和 Recreation 名称的字符串数组。
Value指定 Recreation 为包含 3 个字符串值的数组（["Food", "Hiking", "Swimming"]）。

POST https://outlook.office.com/api/beta/me/events

Content-Type: application/json

{
  "Subject": "Family reunion",
  "Body": {
    "ContentType": "HTML",
    "Content": "Let's get together this Thanksgiving!"
  },
  "Start": {
      "DateTime": "2015-11-26T09:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "End": {
      "DateTime": "2015-11-29T21:00:00",
      "TimeZone": "Pacific Standard Time"
  },
  "Attendees": [
    {
      "EmailAddress": {
        "Address": "Terrie@contoso.com",
        "Name": "Terrie Barrera"
      },
      "Type": "Required"
    },
    {
      "EmailAddress": {
        "Address": "Lauren@contoso.com",
        "Name": "Lauren Solis"
      },
      "Type": "Required"
    }
  ],
  "MultiValueExtendedProperties": [
     {
           "PropertyId":"StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation",
           "Value": ["Food", "Hiking", "Swimming"]
     }
  ]
}

示例响应

成功的响应由 HTTP 201 Created 响应代码表示，并在响应正文中包括新事件，类似于仅创建事件中的响应。该响应不包括任何新建的扩展属性。

若要查看新建的扩展属性，请使用扩展属性获取扩展的项目。

获取带有扩展属性的项目

获取一个支持的资源实例，其扩展属性使用 PropertyId的筛选器指定。

您在筛选器中为 PropertyId 指定的字符串 {propertyId_value} 必须遵循支持的 PropertyId 格式之一。请确保对筛选器字符串中的空格字符应用 URL 编码。

使用匹配的单值扩展属性扩展项目

GET https://outlook.office.com/api/beta/me/messages('{message_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/events('{event_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/contacts('{contact_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/tasks('{task_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/mailfolders('{mailFolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/calendars('{calendar_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/contactfolders('{contactFolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/taskfolders('{taskfolder_id}')?$expand=SingleValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

使用匹配的多值扩展属性扩展项目

GET https://outlook.office.com/api/beta/me/messages('{message_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/events('{event_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/contacts('{contact_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/tasks('{task_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/mailfolders('{mailFolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/calendars('{calendar_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/contactfolders('{contactFolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

GET https://outlook.office.com/api/beta/me/taskfolders('{taskfolder_id}')?$expand=MultiValueExtendedProperties($filter=PropertyId eq '{propertyId_value}')

最低要求的范围

对应于目标资源的以下读取范围之一：

https://outlook.office.com/mail.read
https://outlook.office.com/calendars.read
https://outlook.office.com/contacts.read
https://outlook.office.com/tasks.read
wl.imap
wl.calendars
wl.contacts_日历
wl.basic

示例请求

第一个示例通过包含单值扩展属性来获取并扩展指定的消息。筛选器返回 PropertyId 匹配字符串 String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color 的扩展属性（为了便于阅读，在此删除了 URL 编码）。

GET https://outlook.office.com/api/beta/me/messages('AAMkAGE1M2_bs88AACHsLqWAAA=')?$expand=SingleValueExtendedProperties($filter=PropertyId%20eq%20'String%20{66f5a359-4659-4830-9070-00047ec6ac6e}%20Name%20Color')

示例响应

成功的响应以 HTTP 200 OK 响应代码表示。

响应正文包括指定消息的所有属性以及此筛选器返回的扩展属性。

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages/$entity",
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Messages('AAMkAGE1M2_bs88AACHsLqWAAA=')",
    "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AACbyS4H\"",
    "Id": "AAMkAGE1M2_bs88AACHsLqWAAA=",
    "CreatedDateTime": "2015-11-11T02:41:24Z",
    "LastModifiedDateTime": "2015-12-09T04:07:57Z",
    "ChangeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AACbyS4H",
    "Categories": [
    ],
    "ReceivedDateTime": "2015-11-11T02:41:24Z",
    "SentDateTime": "2015-11-11T02:41:24Z",
    "HasAttachments": false,
    "InternetMessageId": "<SN2SR0101MB002977E7C30F9CA9AA55961484130@SN2SR0101MB0029.contoso.com>",
    "Subject": "RE: Talk about emergency prep",
    "Body": {
        "ContentType": "HTML",
        "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<meta content=\"text/html; charset=iso-8859-1\">\r\n<style type=\"text/css\" style=\"\">\r\n<!--\r\np\r\n\t{margin-top:0;\r\n\tmargin-bottom:0}\r\n-->\r\n</style>\r\n</head>\r\n<body dir=\"ltr\">\r\n<hr tabindex=\"-1\" style=\"display:inline-block; width:98%\">\r\n<div id=\"divRplyFwdMsg\" dir=\"ltr\"><font face=\"Calibri, sans-serif\" color=\"#000000\" style=\"font-size:11pt\"><b>From:</b> Christine Irwin<br>\r\n<b>Sent:</b> Sunday, November 8, 2015 12:28:31 AM<br>\r\n<b>To:</b> Terrie Barrera<br>\r\n<b>Subject:</b> Talk about emergency prep<br>\r\n<b>When:</b> Sunday, November 8, 2015 7:00 PM-8:00 PM.<br>\r\n<b>Where:</b> The Commons</font>\r\n<div>&nbsp;</div>\r\n</div>\r\n<div>\r\n<div id=\"divtagdefaultwrapper\" style=\"font-size:12pt; color:#000000; background-color:#FFFFFF; font-family:Calibri,Arial,Helvetica,sans-serif\">\r\n<p>Please see the attached before you come to the meeting.<br>\r\n</p>\r\n</div>\r\n</div>\r\n</body>\r\n</html>\r\n"
    },
    "BodyPreview": "________________________________",
    "Importance": "Normal",
    "ParentFolderId": "AQMkAGE1M2jgxCloXP1JupQN7j5uzzwAAAIBDwAAAA==",
    "Sender": {
        "EmailAddress": {
            "Name": "Christine Irwin",
            "Address": "christine@contoso.com"
        }
    },
    "From": null,
    "ToRecipients": [
        {
            "EmailAddress": {
                "Name": "Christine Irwin",
                "Address": "christine@contoso.com"
            }
        }
    ],
    "CcRecipients": [
    ],
    "BccRecipients": [
    ],
    "ReplyTo": [
    ],
    "ConversationId": "AAQkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVlLTY0YjcxZWUzNTE1MAAQAHWT1sRiMChEmlQCIZUadoU=",
    "IsDeliveryReceiptRequested": false,
    "IsReadReceiptRequested": false,
    "IsRead": true,
    "IsDraft": true,
    "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2%2Bbs88AACHsLqWAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
    "MentionedMe": null,
    "HashtagDetailsPreview": null,
    "LikesPreview": null,
    "Mentioned": [
    ],
    "InferenceClassification": "Focused",
    "UnsubscribeData": [
    ],
    "UnsubscribeEnabled": false,
    "SingleValueExtendedProperties@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Messages('AAMkAGE1M2_bs88AACHsLqWAAA%3D')/SingleValueExtendedProperties",
    "SingleValueExtendedProperties": [
        {
            "PropertyId": "String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color",
            "Value": "Green"
        }
    ]
}

示例请求

第二个示例通过包含多值扩展属性来获取和展开指定的事件。筛选器返回 PropertyId 匹配字符串 StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation 的扩展属性（为了便于阅读，在此删除了 URL 编码）。

GET https://outlook.office.com/api/beta/me/events('AAMkAGE1M2_bs88AACbuFiiAAA=')?$expand=MultiValueExtendedProperties($filter=PropertyId%20eq%20'StringArray%20{66f5a359-4659-4830-9070-00050ec6ac6e}%20Name%20Recreation')

示例响应

成功的响应以 HTTP 200 OK 响应代码表示。

响应正文包括指定事件的所有属性以及此筛选器返回的扩展属性。

{
    "@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Events/$entity",
    "@odata.id": "https://outlook.office.com/api/beta/Users('ddfcd489-628b-40d7-b48b-57002df800e5@1717622f-1d94-4d0c-9d74-709fad664b77')/Events('AAMkAGE1M2_bs88AACbuFiiAAA=')",
    "@odata.etag": "W/\"mODEKWhc/Um6lA3uPm7PPAAAm8k15A==\"",
    "Id": "AAMkAGE1M2_bs88AACbuFiiAAA=",
    "CreatedDateTime": "2015-12-09T05:18:05.9477979Z",
    "LastModifiedDateTime": "2015-12-09T05:18:06.197802Z",
    "ChangeKey": "mODEKWhc/Um6lA3uPm7PPAAAm8k15A==",
    "Categories": [
    ],
    "OriginalStartTimeZone": "Pacific Standard Time",
    "OriginalEndTimeZone": "Pacific Standard Time",
    "ResponseStatus": {
        "Response": "Organizer",
        "Time": "0001-01-01T00:00:00Z"
    },
    "iCalUId": "04000000828A332796D9",
    "ReminderMinutesBeforeStart": 15,
    "IsReminderOn": true,
    "HasAttachments": false,
    "Subject": "Family reunion",
    "Body": {
        "ContentType": "HTML",
        "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<meta content=\"text/html; charset=us-ascii\">\r\n</head>\r\n<body>\r\nLet's get together this Thanksgiving!\r\n</body>\r\n</html>\r\n"
    },
    "BodyPreview": "Let's get together this Thanksgiving!",
    "Importance": "Normal",
    "Sensitivity": "Normal",
    "Start": {
        "DateTime": "2015-11-26T17:00:00.0000000",
        "TimeZone": "UTC"
    },
    "End": {
        "DateTime": "2015-11-30T05:00:00.0000000",
        "TimeZone": "UTC"
    },
    "Location": {
        "DisplayName": ""
    },
    "IsAllDay": false,
    "IsCancelled": false,
    "IsOrganizer": true,
    "Recurrence": null,
    "ResponseRequested": true,
    "SeriesMasterId": null,
    "ShowAs": "Busy",
    "Type": "SingleInstance",
    "Attendees": [
        {
            "Status": {
                "Response": "None",
                "Time": "0001-01-01T00:00:00Z"
            },
            "Type": "Required",
            "EmailAddress": {
                "Name": "Terrie Barrera",
                "Address": "Terrie@contoso.com"
            }
        },
        {
            "Status": {
                "Response": "None",
                "Time": "0001-01-01T00:00:00Z"
            },
            "Type": "Required",
            "EmailAddress": {
                "Name": "Lauren Solis",
                "Address": "Lauren@contoso.com"
            }
        }
    ],
    "Organizer": {
        "EmailAddress": {
            "Name": "Christine Irwin",
            "Address": "christine@contoso.com"
        }
    },
    "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2%2Bbs88AACbuFiiAAA%3D&exvsurl=1&viewmodel=ICalendarItemDetailsViewModelFactory",
    "MultiValueExtendedProperties@odata.context": "https://outlook.office.com/api/beta/$metadata#Me/Events('AAMkAGE1M2_bs88AACbuFiiAAA%3D')/MultiValueExtendedProperties",
    "MultiValueExtendedProperties": [
        {
            "PropertyId": "StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation",
            "Value": [
                "Food",
                "Hiking",
                "Swimming"
            ]
        }
    ]
}

通过扩展属性筛选来获取项目

获取一个支持的资源实例，其扩展属性由筛选器根据 PropertyId 和 Value 指定。该筛选器应用于资源在已登录用户的邮箱中的所有实例。此筛选仅支持单值但不支持多值扩展属性。

您在筛选器中为 PropertyId 指定的字符串 {propertyId_value} 必须遵循支持的 PropertyId 格式之一。

如果 {property_value} 不是一个字符串，请确保当与 {property_value} 比较时，您将 ep/value 显式转换为适当的 Edm 数据类型。有关此类强制转换的示例，请参阅下面有关非字符串类型属性的请求示例。

请务必对筛选器字符串中的以下字符应用 URL 编码：冒号、正斜杠和空格。

GET https://outlook.office.com/api/beta/me/messages?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/events?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/contacts?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/tasks?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/mailfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/calendars?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/contactfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

GET https://outlook.office.com/api/beta/me/taskfolders?$filter=SingleValueExtendedProperties/Any(ep: ep/PropertyId eq '{propertyId_value}' and ep/Value eq '{property_value}')

最低要求的范围

对应于目标资源的以下读取范围之一：

https://outlook.office.com/mail.read
https://outlook.office.com/calendars.read
https://outlook.office.com/contacts.read
https://outlook.office.com/tasks.read
wl.imap
wl.calendars
wl.contacts_日历
wl.basic

示例请求

第一个示例获取具有在过滤器中指定字符串类型的单值字符串的消息。此筛选器查找如下扩展属性：

与 PropertyId 匹配的字符串String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color（此处为了方便阅读，已将包含的 URL 编码删除）。
它的 Value 是字符串 Green。

GET https://outlook.office.com/api/beta/me/Messages?$filter=SingleValueExtendedProperties%2FAny(ep%3A%20ep%2FPropertyId%20eq%20'String%20{66f5a359-4659-4830-9070-00047ec6ac6e}%20Name%20Color'%20and%20ep%2FValue%20eq%20'Green')

下两个示例展示了如何获取具有非字符串类型单值扩展属性的消息。为了方便阅读，从中删除了必要的 URL 编码。下面的示例展示了查找以下扩展属性的筛选器：

它的 PropertyId 匹配字符串 CLSID {00062008-0000-0000-C000-000000000046} Name ConnectorSenderGuid。
它的 Value 是 GUID b9cf8971-7d55-4b73-9ffa-a584611b600b。若要将属性值与 GUID 比较，请将 ep/Value 转换为 Edm.Guid。

GET https://outlook.office.com/api/beta/me/Messages?$filter=SingleValueExtendedProperties/any(ep:ep/PropertyId eq 'CLSID {00062008-0000-0000-C000-000000000046} Name ConnectorSenderGuid' and cast(ep/Value, Edm.Guid) eq (b9cf8971-7d55-4b73-9ffa-a584611b600b))

第三个也是最后一个例子显示了一个筛选器，查找具有以下内容的扩展属性：

它的 PropertyId 匹配字符串 Integer {66f5a359-4659-4830-9070-00047ec6ac6e} Name Pallete。
它的 Value 等于整数 12。若要将属性值与整数比较，请将 ep/Value 转换为 Edm.Int32。

GET https://outlook.office.com/api/beta/me/Messages?$filter=SingleValueExtendedProperties/any(ep:ep/PropertyId eq 'Integer {66f5a359-4659-4830-9070-00047ec6ac6e} Name Pallete' and cast(ep/Value, Edm.Int32) eq 12)

示例响应

成功的响应将由 HTTP 200 OK 响应代码表示，响应正文包括其扩展属性与筛选器匹配的邮件的所有属性。响应正文类似于获取消息集合中的响应。响应中不包含匹配的扩展属性。

后续步骤

无论你准备开始构建应用还是只想了解更多信息，我们都已为你考虑周全。

开始使用邮件、日历和联系人 REST API。
想要查看一些示例吗？我们就有。

或者，了解有关使用 Office 365 平台的更多信息：

通过

Outlook 扩展属性 REST API 参考 (beta)

使用扩展属性 REST API

扩展属性或数据扩展？

身份验证

API 版本

支持的 REST 资源

URL 参数

概述

PropertyId 格式

扩展属性操作

在现有项目中创建扩展属性

最低要求的范围

示例请求

示例响应

示例请求

示例响应

在新项目中创建扩展属性

最低要求的范围

示例请求

示例响应

示例请求

示例响应

获取带有扩展属性的项目

使用匹配的单值扩展属性扩展项目

使用匹配的多值扩展属性扩展项目

最低要求的范围

示例请求

示例响应

示例请求

示例响应

通过扩展属性筛选来获取项目

最低要求的范围

示例请求

示例响应

后续步骤

其他资源