Office 365 数据扩展 REST API 参考（版本 2.0）

项目
06/30/2018

Office 365 Data Extensions REST API 允许应用程序动态地将自定义数据存储在用户帐户的消息、事件或联系人中。用户的帐户可以是 Office 365 帐户或 Microsoft 帐户（Hotmail.com、Live.com、MSN.com、Outlook.com 和 Passport.com）。

备注

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

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

概述

Outlook REST API 中的数据扩展是 OData v4 打开类型，其中包含您可以在运行时指定的属性。通过在 JSON 负载中动态指定自定义属性和值，您可以使用 Data Extensions API _扩展_已在实体数据模型 (EDM) 中定义的实体类型实例 - 消息、事件或联系人。这使得此类实体类型的定义更加灵活，节省您为此定义新实体类型的时间。

ExtensionName 属性是为所有扩展定义的唯一属性。一种帮助确保扩展名称的独特方法是，使用依赖_自己的域_的反向域名系统 (DNS) 方法，例如，Com.Contoso.Contact。请勿在扩展名称中使用 Microsoft 域。

由于扩展是开放类型，因此您可以指定实体实例特定的其他数据。例如，您可以为单个业务联系人创建一个扩展来跟踪自定义数据（如公司名称和初始引荐人），并在 JSON 负载中指定数据，如下所示：

POST https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions
{
   @odata.type: "Microsoft.OutlookServices.OpenTypeExtension",  
   "ExtensionName": "Com.Contoso.Customer",
   "CompanyName": "Alpine Skis",
   "InitialReferrer":  "Robin McCall"
}

您可以使用 Data Extensions API 对新资源或现有资源执行 CRUD 操作。更多了解支持的操作。

有关 OData 开放类型的更多信息，请参阅 OData.org 上的 OData v4 文档。

使用 Data Extensions REST API

数据扩展或扩展的属性？

对于大多数涉及存储和访问自定义数据的情景，数据扩展是推荐的解决方案。但是，如果需要访问尚未通过 Outlook REST API 元数据公开的 Outlook MAPI 属性的自定义数据，则可以使用扩展的属性及其 REST API。您可以在 https://outlook.office.com/api/{version}/$metadata 验证元数据暴露的属性，使用 v2.0、测试版等替换您选择的 {version}。

身份验证

像其他 Outlook REST API 那样，对于 Data Extensions API 的每个请求，都应该包含有效的访问令牌。获取访问令牌需要注册和识别应用，并获得相应的授权。

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

支持的 REST 资源

您可以在 Outlook REST 端点中为以下资源的实例创建扩展：

API 版本

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

https://outlook.office.com/api/v2.0/

https://outlook.office.com/api/beta/

URL 参数

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

参数	类型	说明
URL 参数
contact_id	字符串	联系人 ID。
event_id	字符串	事件 ID。
message_id	字符串	消息 ID。

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

在现有项中创建扩展

为指定的资源实例创建一个扩展并添加自定义属性。该资源可以是 Office 365 或 Outlook.com 中的消息、日历事件或联系人。 JSON 有效负载中的数据可以是基元类型，也可以是基元类型的数组。

为每个受支持的资源创建扩展：

POST https://outlook.office.com/api/v2.0/me/messages('{message_id}')/extensions
POST https://outlook.office.com/api/v2.0/me/events('{event_id}')/extensions
POST https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions

最低要求的范围

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

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

参数	类型	说明
正文参数
ExtensionName	字符串	扩展的唯一文本标识符。必需。

示例请求

本示例为指定的消息创建扩展。请求正文包含扩展的以下内容：

类型Microsoft.OutlookServices.OpenTypeExtension定义为 Outlook REST API 元数据中的 OData 开放类型。
扩展名“Com.Contoso.Referral”。
其他数据将作为 JSON 负载中的自定义属性进行存储：包含原始类型的 CompanyName 、DealValue 和 ExpirationDate ，以及包含原始类型数组的 TopModels 和 TopSalespersons 。

POST https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions

Content-Type: application/json

{ 
  "@odata.type" : "Microsoft.OutlookServices.OpenTypeExtension", 
  "ExtensionName" : "Com.Contoso.Referral", 
  "CompanyName" : "Wingtip Toys",
  "DealValue@odata.type": "#Int64", 
  "DealValue" : 500050, 
  "ExpirationDate" : "2015-12-03T10:00:00.000Z",
  "TopModels": [
     3001,
     4002,
     5003
  ],
  "TopSalespersons": [
     "Dana Swope",
     "Fanny Downs",
     "Randi Welch"
  ]
}

示例响应

成功的响应以 HTTP 201 Created 响应代码表示。

对于新的扩展，响应主体包括以下内容：

默认属性 ExtensionName。
具有 Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral 完全限定名称的 Id 属性。
要存储的自定义数据。

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
    "ExtensionName": "Com.Contoso.Referral",
    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys",
    "DealValue@odata.type": "#Int64",
    "DealValue": 500050,
    "ExpirationDate": "2015-12-03T10:00:00.000Z",
    "TopModels@odata.type": "#Collection(Int32)",
    "TopModels": [
      3001,
      4002,
      5003
    ],
    "TopSalespersons@odata.type": "#Collection(String)",
    "TopSalespersons": [
      "Dana Swope",
      "Fanny Downs",
      "Randi Welch"
    ]
}

在新项中创建扩展

创建一个或多个扩展，同时创建新的资源实例，全部在同一 POST 调用中并向扩展添加自定义属性。该资源可以是 Office 365 或 Outlook.com 中的消息、日历事件或联系人。 JSON 有效负载中的数据可以是基元类型，也可以是基元类型的数组。

要为每个受支持的资源创建扩展，请执行类似于创建资源的 POST 调用，并在 POST 请求的主体中包含扩展。

POST https://outlook.office.com/api/v2.0/me/messages
POST https://outlook.office.com/api/v2.0/me/events
POST https://outlook.office.com/api/v2.0/me/contacts

最低要求的范围

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

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

参数	类型	说明
正文参数
ExtensionName	字符串	扩展的唯一文本标识符。必需。

示例请求

本示例在同一个调用中创建一条消息和一个扩展。请求主体包括以下：

新消息的典型 Subject、Body 和 ToRecipients 属性。
对于扩展：
- 类型Microsoft.OutlookServices.OpenTypeExtension定义为 Outlook REST API 元数据中的 OData 开放类型。
- 扩展名“Com.Contoso.Referral”。
- 其他数据将作为 JSON 负载中的自定义属性进行存储：包含原始类型的 CompanyName 、ExpirationDate 和 DealValue ，以及包含原始类型数组的 TopModels 和 TopSalespersons 。

POST https://outlook.office.com/api/v2.0/me/messages

Content-Type: application/json

{
  "Subject": "Annual review",
  "Body": {
    "ContentType": "HTML",
    "Content": "You should be proud!"
  },
  "ToRecipients": [
    {
      "EmailAddress": {
        "Address": "rufus@contoso.com"
      }
    }
  ],
  "Extensions": [
    {
      "@odata.type": "Microsoft.OutlookServices.OpenTypeExtension",
      "ExtensionName": "Com.Contoso.Referral",
      "CompanyName": "Wingtip Toys",
      "ExpirationDate": "2015-12-30T11:00:00.000Z",
      "DealValue": 10000,
      "TopModels": [
        3001,
        4002,
        5003
      ],
      "TopSalespersons": [
        "Dana Swope",
        "Fanny Downs",
        "Randi Welch"
      ]
    }
  ]
}

示例响应

成功的响应以 HTTP 201 Created 响应代码表示。

响应正文包含新消息的属性，以及新扩展的以下属性：

具有 Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral 完全限定名称的 Id 属性。
请求中指定的默认属性 ExtensionName。
请求中指定的作为自定义属性存储的自定义数据。

{
  "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages/$entity",
  "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df800e5@1717f226-49d1-4d0c-9d74-709fad664b77')/Messages
('AAMkAGEbs88AAB84uLuAAA=')",
  "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AAB88LOj\"",
  "Id": "AAMkAGEbs88AAB84uLuAAA=",
  "CreatedDateTime": "2015-10-30T03:03:43Z",
  "LastModifiedDateTime": "2015-10-30T03:03:43Z",
  "ChangeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AAB88LOj",
  "Categories": [ ],
  "ReceivedDateTime": "2015-10-30T03:03:43Z",
  "SentDateTime": "2015-10-30T03:03:43Z",
  "HasAttachments": false,
  "Subject": "Annual review",
  "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\nYou should be proud!\r\n</body>\r
\n</html>\r\n"
  },
  "BodyPreview": "You should be proud!",
  "Importance": "Normal",
  "ParentFolderId": "AQMkAGEwAAAIBDwAAAA==",
  "Sender": null,
  "From": null,
  "ToRecipients": [
    {
      "EmailAddress": {
        "Address": "rufus@contoso.com",
        "Name": "John Doe"
      }
    }
  ],
  "CcRecipients": [ ],
  "BccRecipients": [ ],
  "ReplyTo": [ ],
  "ConversationId": "AAQkAGEFGugh3SVdMzzc=",
  "IsDeliveryReceiptRequested": false,
  "IsReadReceiptRequested": false,
  "IsRead": true,
  "IsDraft": true,
  "WebLink": "https://outlook.office.com/owa/?
ItemID=AAMkAGEbs88AAB84uLuAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
  "MentionedMe": null,
  "Mentioned": [ ],
  "InferenceClassification": "Focused",
  "Extensions@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages
('AAMkAGEbs88AAB84uLuAAA%3D')/Extensions",
  "Extensions": [
    {
      "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
      "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df800e5@1717f226-49d1-4d0c-9d74-709fad664b77')/Messages
('AAMkAGEbs88AAB84uLuAAA=')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
      "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
      "ExtensionName": "Com.Contoso.Referral",
      "CompanyName": "Wingtip Toys",
      "ExpirationDate": "2015-12-30T11:00:00.000Z",
      "DealValue": 10000,
      "TopModels@odata.type": "#Collection(Int32)",
      "TopModels": [
        3001,
        4002,
        5003
      ],
      "TopSalespersons@odata.type": "#Collection(String)",
      "TopSalespersons": [
        "Dana Swope",
        "Fanny Downs",
        "Randi Welch"
      ]
    }
  ]
}

获得扩展

通过名称或 ID 获得指定的资源实例中的扩展。该资源可以是 Office 365 或 Outlook.com 中的消息、日历事件或联系人。

通过名称或 ID 获得扩展将返回相同的响应主体。

GET https://outlook.office.com/api/v2.0/me/messages('{message_id}')/extensions('{extensionId}')
GET https://outlook.office.com/api/v2.0/me/events('{event_id}')/extensions('{extensionId}')
GET https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions('{extensionId}')

最低要求的范围

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

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

参数	类型	说明
URL 参数
extensionId	字符串	这可以是作为资源实例中的所有扩展唯一的文本标识符的扩展名称，或者是连接扩展类型和唯一文本标识符的完全限定的名称。当创建扩展时，完全限定的名称会在 id 属性中返回。必需。

示例请求

第一个示例按名称引用扩展，同时获得指定消息中的扩展。

GET https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Com.Contoso.Referral')

第二个示例通过其 ID（完全限定的名称）引用扩展，并在指定的消息中获取扩展。

GET https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')

示例响应

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

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
    "ExtensionName": "Com.Contoso.Referral",
    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys",
    "DealValue": 500050,
    "ExpirationDate": "2015-12-03T10:00:00Z"
}

获得以扩展来扩展的项

获得通过Id上的过滤器指定的扩展来扩展的资源实例。该资源可以是 Office 365 或 Outlook.com 中的消息、日历事件或联系人。

您可以使用扩展名称或完全限定的名称过滤 Id，然后获得使用扩展来扩展的实例，如下所示。请确保对过滤器字符串中的空格字符应用 URL 编码。

GET https://outlook.office.com/api/v2.0/me/messages('{message_id}')?$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/v2.0/me/events('{event_id}')?$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')?$expand=Extensions($filter=Id eq '{extensionId}')

最低要求的范围

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

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

参数	类型	说明
URL 参数
extensionId	字符串	这可以是作为资源实例中的所有扩展唯一的文本标识符的扩展名称，或者是连接扩展类型和唯一文本标识符的完全限定的名称。当创建扩展时，完全限定的名称会在 id 属性中返回。必需。

示例请求

以下示例通过包含从过滤器返回的扩展来获得并展开指定的消息。过滤器返回其 Id 匹配完全限定名称的扩展。

为了方便起见，以下的请求使用保留字符 - 空格的 URL 编码显示。

GET https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')?$expand=Extensions($filter=Id%20eq%20'Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')

示例响应

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

响应正文包括过滤器返回的指定消息的所有属性和扩展。

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages/$entity",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')",
    "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AABNsWMM\"",
    "Id": "AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===",
    "ChangeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AABNsWMM",
    "Categories": [
    ],
    "CreateDateTime": "2015-06-19T02:03:31Z",
    "LastModifiedDateTime": "2015-08-13T02:28:00Z",
    "Subject": "Attached is the requested info",
    "BodyPreview": "See the images attached.",
    "Body": {
        "ContentType": "HTML",
        "Content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n<style type=\"text/css\" style=\"display:none;\"><!-- P {margin-top:0;margin-bottom:0;} --></style>\r\n</head>\r\n<body dir=\"ltr\">\r\n<div id=\"divtagdefaultwrapper\" style=\"font-size:12pt;color:#000000;background-color:#FFFFFF;font-family:Calibri,Arial,Helvetica,sans-serif;\">\r\n<p>See the images attached. <br>\r\n</p>\r\n</div>\r\n</body>\r\n</html>\r\n"
    },
    "Importance": "Normal",
    "HasAttachments": true,
    "ParentFolderId": "AQMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===QAAAA==",
    "From": {
        "EmailAddress": {
            "Address": "desmond@contoso.com",
            "Name": "Desmond Raley"
        }
    },
    "Sender": {
        "EmailAddress": {
            "Address": "desmond@contoso.com",
            "Name": "Desmond Raley"
        }
    },
    "ToRecipients": [
        {
            "EmailAddress": {
                "Address": "wendy@contoso.com",
                "Name": "Wendy Molina"
            }
        }
    ],
    "CcRecipients": [
    ],
    "BccRecipients": [
    ],
    "ReplyTo": [
    ],
    "ConversationId": "AAQkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===mivdTmQ=",
    "ReceivedDateTime": "2015-06-19T02:05:04Z",
    "SentDateTime": "2015-06-19T02:04:59Z",
    "IsDeliveryReceiptRequested": false,
    "IsReadReceiptRequested": false,
    "IsDraft": false,
    "IsRead": true,
    "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===%2FNJTqt5NqHlVnKVBwCY4MQpaFz9SbqUDe4%2Bbs88AAAAAAEJAACY4MQpaFz9SbqUDe4%2Bbs88AAApA4JMAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
    "MentionedMe": null,
    "Mentioned": [
    ],
    "InferenceClassification": "Focused",
    "Extensions@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Users('desmond40contoso.com')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions", 
    "Extensions": [ 
      { 
        "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
        "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
        "ExtensionName": "Com.Contoso.Referral",
        "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
        "CompanyName": "Wingtip Toys",
        "DealValue": 500050,
        "ExpirationDate": "2015-12-03T10:00:00Z"
      }
     ]
}

查找并扩展带扩展的项

您可以找到包含匹配过滤器的扩展的资源实例。另外，在同一查询中，您可以使用扩展来扩展这些实例。本节中的查询会查找这些实例，扩展并在响应中包含扩展。

该资源可以是 Office 365 或 Outlook.com 中的消息、日历事件或联系人。

您可以使用扩展名称或完全限定的名称过滤 Id，然后获得使用扩展来扩展的实例，如下所示。请确保对过滤器字符串中的空格字符应用 URL 编码。

GET https://outlook.office.com/api/v2.0/me/messages?$filter=Extensions/any(f:f/Id eq '{extensionId}')&$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/v2.0/me/events?$filter=Extensions/any(f:f/Id eq '{extensionId}')&$expand=Extensions($filter=Id eq '{extensionId}')

GET https://outlook.office.com/api/v2.0/me/contacts?$filter=Extensions/any(f:f/Id eq '{extensionId}')&$expand=Extensions($filter=Id eq '{extensionId}')

最低要求的范围

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

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

参数	类型	说明
URL 参数
extensionId	字符串	这可以是作为资源实例中的所有扩展唯一的文本标识符的扩展名称，或者是连接扩展类型和唯一文本标识符的完全限定的名称。当创建扩展时，完全限定的名称会在 id 属性中返回。必需。

示例请求

以下示例将搜索已登录用户邮箱中的所有消息，查找包含与过滤器匹配的扩展的消息，并通过包含扩展来扩展它们。过滤器返回具有匹配扩展名称的Id扩展Com.Contoso.Referral。

为了方便起见，以下的请求使用保留字符 - 空格的 URL 编码显示。

GET https://outlook.office.com/api/v2.0/me/messages?$filter=Extensions/any(f:f/Id%20eq%20'Com.Contoso.Referral')&$expand=Extensions($filter=Id%20eq%20'Com.Contoso.Referral')

示例响应

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

响应正文包含所有具有匹配扩展名的消息以及所有消息属性。在本例中，响应包含两条消息。

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages",
    "value": [
        {
            "@odata.type": "#Microsoft.OutlookServices.EventMessage",
            "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyDREAAA=')",
            "@odata.etag": "W/\"DAAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ9tn\"",
            "Id": "AAMkADIyDREAAA=",
            "CreatedDateTime": "2016-01-06T02:20:17Z",
            "LastModifiedDateTime": "2016-01-13T02:13:54Z",
            "ChangeKey": "DAAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ9tn",
            "Categories": [
            ],
            "ReceivedDateTime": "2016-01-06T02:20:18Z",
            "SentDateTime": "2016-01-06T02:20:18Z",
            "HasAttachments": false,
            "InternetMessageId": "<BY1PR19MB0023E92E0B43F5E268406F0DF5F40@BY1PR19MB0023.namprd19.prod.outlook.com>",
            "Subject": "Accepted: Latin American Product Manual Group",
            "Body": {
                "ContentType": "Text",
                "Content": ""
            },
            "BodyPreview": "",
            "Importance": "Normal",
            "ParentFolderId": "AAMkADIyAAAAEJAAA=",
            "Sender": {
                "EmailAddress": {
                    "Name": "MOD Administrator",
                    "Address": "admin@adatumltd.onmicrosoft.com"
                }
            },
            "From": {
                "EmailAddress": {
                    "Name": "MOD Administrator",
                    "Address": "admin@adatumltd.onmicrosoft.com"
                }
            },
            "ToRecipients": [
                {
                    "EmailAddress": {
                        "Name": "Engineering",
                        "Address": "engineering@adatumltd.onmicrosoft.com"
                    }
                }
            ],
            "CcRecipients": [
            ],
            "BccRecipients": [
            ],
            "ReplyTo": [
            ],
            "ConversationId": "AAQkADIyWejUoYAg=",
            "IsDeliveryReceiptRequested": null,
            "IsReadReceiptRequested": false,
            "IsRead": true,
            "IsDraft": false,
            "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkADIyDREAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
            "InferenceClassification": "Focused",
            "UnsubscribeData": [
            ],
            "UnsubscribeEnabled": false,
            "MeetingMessageType": "MeetingAccepted",
            "StartDateTime": {
                "DateTime": "2015-01-05T19:00:00.0000000",
                "TimeZone": "UTC"
            },
            "EndDateTime": {
                "DateTime": "2015-01-05T20:30:00.0000000",
                "TimeZone": "UTC"
            },
            "Location": {
                "DisplayName": "Mt. Adams"
            },
            "Type": "SeriesMaster",
            "Recurrence": {
                "Pattern": {
                    "Type": "RelativeMonthly",
                    "Interval": 2,
                    "Month": 0,
                    "DayOfMonth": 0,
                    "DaysOfWeek": [
                        "Monday"
                    ],
                    "FirstDayOfWeek": "Sunday",
                    "Index": "First"
                },
                "Range": {
                    "Type": "NoEnd",
                    "StartDate": "2015-01-05",
                    "EndDate": "0001-01-01",
                    "RecurrenceTimeZone": "tzone://Microsoft/Utc",
                    "NumberOfOccurrences": 0
                }
            },
            "IsOutOfDate": false,
            "Extensions@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkADIyDREAAA%3D')/Extensions",
            "Extensions": [
                {
                    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
                    "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyDREAAA=')/Extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
                    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
                    "ExtensionName": "Com.Contoso.Referral",
                    "CompanyName": "Wingtip Toys",
                    "DealValue@odata.type": "#Int64",
                    "DealValue": 500300,
                    "ExpirationDate": "2015-12-03T10:00:00.000Z"
                }
            ],
            "Event@odata.associationLink": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Events('AAMkADIyAAAAABrdAAA=')/$ref",
            "Event@odata.navigationLink": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Events('AAMkADIyAAAAABrdAAA=')"
        },
        {
            "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyAHVAAA=')",
            "@odata.etag": "W/\"CQAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ6aq\"",
            "Id": "AAMkADIyAHVAAA=",
            "CreatedDateTime": "2016-01-06T02:20:02Z",
            "LastModifiedDateTime": "2016-01-13T02:24:50Z",
            "ChangeKey": "CQAAABYAAACGYzsRv+OAR5zyXf6CQkRrAAADJ6aq",
            "Categories": [
            ],
            "ReceivedDateTime": "2016-01-06T02:20:02Z",
            "SentDateTime": "2016-01-06T02:20:01Z",
            "HasAttachments": false,
            "InternetMessageId": "<CY1PR19MB0032531C620A46068FDDD45DE3F40@CY1PR19MB0032.namprd19.prod.outlook.com>",
            "Subject": "International Launch Planning for XT2000",
            "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\nWe will be ready to ship XT 2000 on 10/1, how's the International launch plan going?<br>\r\n<div style=\"display:inline-block\">\r\n<table border=\"0\" cellspacing=\"0\" style=\"background-color:#F4F4F4\">\r\n<tbody>\r\n<tr>\r\n<td style=\"padding:20px; font-size:12px; color:#666666\">You're receiving this message because you're a subscribed member of the Engineering group.<br>\r\n<a href=\"https://outlook.office.com/owa/engineering@adatumltd.onmicrosoft.com/groupsubscription.ashx?realm=adatumltd.onmicrosoft.com&amp;action=conversations&amp;source=EscalatedMessage\">View group conversations</a> |\r\n<a href=\"https://adatumltd.sharepoint.com/_layouts/groupstatus.aspx?id=dbcbe107-6244-40ba-b0f1-1c46ad35435d&amp;target=documents\">\r\nView group files</a> | <a id=\"BD5134C6-8D33-4ABA-A0C4-08581FDF89DB\" href=\"https://outlook.office.com/owa/engineering@adatumltd.onmicrosoft.com/groupsubscription.ashx?realm=adatumltd.onmicrosoft.com&amp;action=unsubscribe&amp;source=EscalatedMessage\">\r\nUnsubscribe</a></td>\r\n</tr>\r\n</tbody>\r\n</table>\r\n</div>\r\n</body>\r\n</html>\r\n"
            },
            "BodyPreview": "We will be ready to ship XT 2000 on 10/1, how's the International launch plan going?\r\nYou're receiving this message because you're a subscribed member of the Engineering group.\r\nView group conversations | View group files | Unsubscribe",
            "Importance": "Normal",
            "ParentFolderId": "AAMkADIyAAAEMAAA=",
            "Sender": {
                "EmailAddress": {
                    "Name": "Engineering",
                    "Address": "engineering@adatumltd.onmicrosoft.com"
                }
            },
            "From": {
                "EmailAddress": {
                    "Name": "Garret Vargas",
                    "Address": "GarretV@adatumltd.onmicrosoft.com"
                }
            },
            "ToRecipients": [
                {
                    "EmailAddress": {
                        "Name": "Engineering",
                        "Address": "engineering@adatumltd.onmicrosoft.com"
                    }
                }
            ],
            "CcRecipients": [
            ],
            "BccRecipients": [
            ],
            "ReplyTo": [
            ],
            "ConversationId": "AAQkADIyLESZnSPc=",
            "IsDeliveryReceiptRequested": null,
            "IsReadReceiptRequested": false,
            "IsRead": false,
            "IsDraft": false,
            "WebLink": "https://outlook.office.com/owa/?ItemID=AAMkADIyAHVAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
            "InferenceClassification": "Focused",
            "UnsubscribeData": [
            ],
            "UnsubscribeEnabled": false,
            "Extensions@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkADIyAHVAAA%3D')/Extensions",
            "Extensions": [
                {
                    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
                    "@odata.id": "https://outlook.office.com/api/v2.0/Users('dc2d952a-78ff-4609-b3ae-eb66271747bf@8638a6dc-2d66-40dc-aecb-b2436ec47fc0')/Messages('AAMkADIyAHVAAA=')/Extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
                    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
                    "ExtensionName": "Com.Contoso.Referral",
                    "CompanyName": "Wingtip Toys",
                    "DealValue@odata.type": "#Int64",
                    "DealValue": 500050,
                    "ExpirationDate": "2015-12-03T10:00:00.000Z"
                }
            ]
        }
    ]
}

添加或修改扩展中的数据

使用请求正文中的属性更新扩展：

如果请求正文中的属性与现有属性在扩展中的名称相匹配，则更新扩展中的数据。
否则，属性及其数据将添加到扩展中。

该扩展可以是 Office 365 或 Outlook.com 中的消息、日历事件或联系人。它可以通过名称或 ID 引用，任何一种方式都会返回相同的响应。 JSON 有效负载中的数据可以是基元类型，也可以是基元类型的数组。

PATCH https://outlook.office.com/api/v2.0/me/messages('{message_id}')/extensions('{extensionId}')
PATCH https://outlook.office.com/api/v2.0/me/events('{event_id}')/extensions('{extensionId}')
PATCH https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions('{extensionId}')

最低要求的范围

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

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

参数	类型	说明
URL 参数
extensionId	字符串	这可以是作为资源实例中的所有扩展唯一的文本标识符的扩展名称，或者是连接扩展类型和唯一文本标识符的完全限定的名称。当创建扩展时，完全限定的名称会在 id 属性中返回。必需。
正文参数
ExtensionName	字符串	扩展的唯一文本标识符。必需。

示例请求

本节中的两个示例都使用了以上 GET 扩展示例中的扩展。第一个按名称引用扩展，第二个按 ID 引用。它们的请求正文和响应是一样的。

每个示例都会通过以下更新上方的扩展：

将 CompanyName 从 Wingtip Toys 更改为 Wingtip Toys (USA)
将 DealValue 从 500050 更改为 500100
将新数据添加为自定义属性 Updated

本示例通过名称引用扩展：

PATCH https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions('Com.Contoso.Referral')

Content-Type: application/json

{
    "@odata.type": "Microsoft.OutlookServices.OpenTypeExtension",
    "ExtensionName": "Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys (USA)",
    "DealValue": "500100",
    "ExpirationDate": "2015-12-03T10:00:00.000Z",
    "Updated": "2015-10-29T11:00:00.000Z"
}

本示例通过其 ID（完全限定的名称）引用扩展：

PATCH https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')

Content-Type: application/json

{
    "@odata.type": "Microsoft.OutlookServices.OpenTypeExtension",
    "ExtensionName": "Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys (USA)",
    "DealValue": "500100",
    "ExpirationDate": "2015-12-03T10:00:00.000Z",
    "Updated": "2015-10-29T11:00:00.000Z"
}

示例响应

一个成功的响应由HTTP 200 OK响应代码和响应主体中的更新扩展来表示。

{
    "@odata.context": "https://outlook.office.com/api/v2.0/$metadata#Me/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/Extensions/$entity",
    "@odata.type": "#Microsoft.OutlookServices.OpenTypeExtension",
    "@odata.id": "https://outlook.office.com/api/v2.0/Users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/Messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
    "Id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
    "ExtensionName": "Com.Contoso.Referral",
    "CompanyName": "Wingtip Toys (USA)",
    "DealValue": 500100,
    "ExpirationDate": "2015-12-03T10:00:00Z",
    "Updated": "2015-10-29T11:00:00.000Z"
}

删除扩展

从指定的资源实例中删除一个扩展。该资源可以是 Office 365 或 Outlook.com 中的消息、日历事件或联系人。

要删除每个受支持的资源实例中的扩展：

DELETE https://outlook.office.com/api/v2.0/me/messages('{message_id}')/extensions('{extension_name}')
DELETE https://outlook.office.com/api/v2.0/me/events('{event_id}')/extensions('{extension_name}')
DELETE https://outlook.office.com/api/v2.0/me/contacts('{contact_id}')/extensions('{extension_name}')

最低要求的范围

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

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

参数	类型	说明
URL 参数
extension_name	字符串	扩展的唯一文本标识符。必需。

示例请求

以下示例按其名称引用扩展并删除指定消息中的扩展。

DELETE https://outlook.office.com/api/v2.0/me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions('Com.Contoso.Referral')

示例响应

成功的响应以 HTTP 204 No Content 响应代码表示。

扩展实体

Extension

类型：Microsoft.OutlookServices.Entity

一个将实体实体作为基础类型的抽象实体。

OpenTypeExtension

类型：Microsoft.OutlookServices.Extension

一种抽象的 OData v4 开放类型，支持动态指定 JSON 负载中的属性和数据以更新实体类型的实例。

属性	类型	说明	可写入？	可筛选？
ExtensionName	字符串	唯一的扩展名称。使用基于您自己的域的反向域名系统，例如Com.Contoso.Contact。	是	否

后续步骤

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

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

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

通过

Office 365 数据扩展 REST API 参考（版本 2.0）

概述

使用 Data Extensions REST API

数据扩展或扩展的属性？

身份验证

支持的 REST 资源

API 版本

URL 参数

扩展操作

在现有项中创建扩展

最低要求的范围

示例请求

示例响应

在新项中创建扩展

最低要求的范围

示例请求

示例响应

获得扩展

最低要求的范围

示例请求

示例响应

获得以扩展来扩展的项

最低要求的范围

示例请求

示例响应

查找并扩展带扩展的项

最低要求的范围

示例请求

示例响应

添加或修改扩展中的数据

最低要求的范围

示例请求

示例响应

删除扩展

最低要求的范围

示例请求

示例响应

扩展实体

Extension

OpenTypeExtension

后续步骤

其他资源