通过

创建开放扩展

命名空间：microsoft.graph

创建开放扩展（openTypeExtension 对象），并在资源的新实例或现有实例中添加自定义属性。 可以在同一操作中创建资源实例中的 开放扩展， 并将自定义数据存储到其中，但特定资源除外。

"权限" " "部分中列出支持打开扩展的资源。

请注意：如果要在 Outlook 资源上创建开放扩展，请参阅 openTypeExtension 资源类型中的 Outlook 特定注意事项。

此 API 可用于以下国家级云部署。

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国
✅ ✅ ✅ ✅

权限

根据要创建的资源、 (委托或请求) 的应用程序 (扩展和权限类型，下表中指定的权限是调用此 API 所需的最低特权。 若要了解其他信息， 在 特权权限之前要特别小心，在"权限" 中搜索。

支持的资源 委派（工作或学校帐户） 委派（个人 Microsoft 帐户） 应用程序
设备 Directory.AccessAsUser.All 不支持 Device.ReadWrite.All
事件 Calendars.ReadWrite Calendars.ReadWrite Calendars.ReadWrite
组 Group.ReadWrite.All 不支持 Group.ReadWrite.All
组事件 Group.ReadWrite.All 不支持 不支持
组帖子 Group.ReadWrite.All 不支持 Group.ReadWrite.All
邮件 Mail.ReadWrite Mail.ReadWrite Mail.ReadWrite
组织 Organization.ReadWrite.All 不支持 Organization.ReadWrite.All
个人联系人 Contacts.ReadWrite Contacts.ReadWrite Contacts.ReadWrite
todoTask Tasks.ReadWrite Tasks.ReadWrite Tasks.ReadWrite.All
todoTaskList Tasks.ReadWrite Tasks.ReadWrite Tasks.ReadWrite.All
用户 User.ReadWrite 不支持 User.ReadWrite.All

HTTP 请求

在新资源实例中创建扩展插件

使用创建实例时所用的同一 REST 请求。

POST /users/{id|userPrincipalName}/events
POST /users/{id|userPrincipalName}/messages
POST /groups/{id}/events
POST /groups/{id}/threads/{id}/posts/{id}/reply
POST /users/{id|userPrincipalName}/contacts
POST /users/{id|userPrincipalName}/todo/lists/{id}/tasks
POST /users/{id|userPrincipalName}/todo/lists

请注意：此语法显示了一些创建受支持资源实例的常用方式。 可用来创建这些资源实例的所有其他 POST 语法均支持以类似的方式从中创建开放扩展。

若要了解如何在请求正文中添加新资源实例和扩展的属性，请参阅请求正文部分。

在现有资源实例中创建扩展插件

在请求中标识资源实例，然后对 extensions 导航属性执行 POST。

POST /devices/{id}/extensions
POST /users/{id|userPrincipalName}/events/{id}/extensions
POST /groups/{id}/extensions
POST /groups/{id}/events/{id}/extensions
POST /groups/{id}/threads/{id}/posts/{id}/extensions
POST /users/{id|userPrincipalName}/messages/{id}/extensions
POST /organization/{id}/extensions
POST /users/{id|userPrincipalName}/contacts/{id}/extensions
POST /users/{id|userPrincipalName}/extensions
POST /users/{id|userPrincipalName}/todo/lists/{id}/tasks/{id}/extensions
POST /users/{id|userPrincipalName}/todo/lists/{id}/extensions

请注意：以上语法显示一些标识资源实例的常见方法，以便在其中创建一个扩展。 可用来标识这些资源实例的所有其他语法均支持以类似的方式在其中创建开放扩展。

若要了解如何在请求正文中添加扩展，请参阅请求正文部分。

路径参数

参数 类型 说明
id string 对象在相应集合中的唯一标识符。 必需。

请求标头

名称 值
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权。
Content-Type application/json

请求正文

提供 openTypeExtension 的 JSON 正文，其中包含以下必需的名称/值对以及任何其他自定义数据。 JSON 负载中的数据可以是基元类型或基元类型数组。

名称 值
@odata.type microsoft.graph.openTypeExtension
extensionName %unique_string%

在新资源实例中创建扩展插件时，除了新的 openTypeExtension 对象之外，还要提供 JSON 表示形式的相关属性才能创建此类资源实例。

响应

响应代码

响应代码可以是 201 Created，也可以是 202 Accepted，具体视操作而定。

使用创建资源实例时所用的操作创建扩展时，操作所返回的响应代码与通过该操作创建不带扩展的资源实例时返回的代码相同。 请参阅创建实例的相应文章，如 上所列。

响应正文

应用场景 资源 响应正文
在显式创建新资源实例的同时创建扩展插件 联系人、事件、邮件 包括使用 openTypeExtension 对象扩展的新实例。
在隐式创建资源实例的同时创建扩展插件 帖子 响应只包括响应代码，不包括响应正文。
在现有资源实例中创建扩展插件 所有支持的资源 包括 openTypeExtension 对象。

示例

示例 1：在同一调用中创建消息和扩展

请求

以下示例在同一调用中创建一条消息和一个扩展。 请求正文包含以下内容：

  • 新邮件的典型 subject、body 和 toRecipients 属性。

  • 对于扩展：

    • microsoft.graph.openTypeExtension 类型。
    • 扩展名“Com.Contoso.Referral”。
    • 存储为 JSON 有效负载中的 3 个自定义属性的其他数据：companyName、expirationDate 和 dealValue。
POST https://graph.microsoft.com/v1.0/me/messages

{
  "subject": "Annual review",
  "body": {
    "contentType": "HTML",
    "content": "You should be proud!"
  },
  "toRecipients": [
    {
      "emailAddress": {
        "address": "rufus@contoso.com"
      }
    }
  ],
  "extensions": [
    {
      "@odata.type": "microsoft.graph.openTypeExtension",
      "extensionName": "Com.Contoso.Referral",
      "companyName": "Wingtip Toys",
      "expirationDate": "2015-12-30T11:00:00.000Z",
      "dealValue": 10000
    }
  ]
}

响应

以下示例显示了第一个示例的响应。 响应正文包括新邮件的属性以及新扩展的以下属性：

  • 具有完全限定的名称 的 microsoft.graph.openTypeExtension.Com.Contoso.Referral 属性。
  • 请求中指定的默认属性 extensionName。
  • 请求中指定的自定义数据存储为三个自定义属性。

注意：为了提高可读性，可能缩短了此处显示的响应对象。

HTTP/1.1 201 Created
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('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",
  "inferenceClassification": "Focused",
  "extensions": [
    {
      "@odata.type": "#microsoft.graph.openTypeExtension",
      "@odata.id": "https://graph.microsoft.com/v1.0/users('ddfc984d-b826-40d7-b48b-57002df800e5@1717f226-49d1-4d0c-9d74-709fad664b77')/messages
('AAMkAGEbs88AAB84uLuAAA=')/extensions('microsoft.graph.openTypeExtension.Com.Contoso.Referral')",
      "id": "microsoft.graph.openTypeExtension.Com.Contoso.Referral",
      "extensionName": "Com.Contoso.Referral",
      "companyName": "Wingtip Toys",
      "expirationDate": "2015-12-30T11:00:00.000Z",
      "dealValue": 10000
    }
  ]
}

示例 2：在指定的消息中创建扩展

请求

以下示例在指定的消息中创建扩展。 请求正文包括扩展的如下内容：

  • microsoft.graph.openTypeExtension 类型。
  • 扩展名“Com.Contoso.Referral”。
  • 存储为 JSON 有效负载中的 3 个自定义属性的其他数据：companyName、dealValue 和 expirationDate。
POST https://graph.microsoft.com/v1.0/me/messages/AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===/extensions

{
  "@odata.type" : "microsoft.graph.openTypeExtension",
  "extensionName" : "Com.Contoso.Referral",
  "companyName" : "Wingtip Toys",
  "dealValue" : 500050,
  "expirationDate" : "2015-12-03T10:00:00.000Z"
}

响应

以下示例显示了第二个示例的响应。 请求正文包括新扩展的如下内容：

  • 默认属性 extensionName。
  • 具有完全限定的名称 microsoft.graph.openTypeExtension.Com.Contoso.Referral 的 Id 属性。
  • 要存储的自定义数据。
HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "@odata.id": "https://graph.microsoft.com/v1.0/users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('microsoft.graph.openTypeExtension.Com.Contoso.Referral')",
    "extensionName": "Com.Contoso.Referral",
    "id": "microsoft.graph.openTypeExtension.Com.Contoso.Referral",
    "companyName": "Wingtip Toys",
    "dealValue": 500050,
    "expirationDate": "2015-12-03T10:00:00.000Z"
}

示例 3：在指定的组事件中创建扩展

请求

以下示例在指定的组事件中创建扩展。 请求正文包括扩展的如下内容：

  • microsoft.graph.openTypeExtension 类型。
  • 扩展名“Com.Contoso.Deal”。
  • 存储为 JSON 有效负载中的 3 个自定义属性的其他数据：companyName、dealValue 和 expirationDate。
POST https://graph.microsoft.com/v1.0/groups/f5480dfd-7d77-4d0b-ba2e-3391953cc74a/events/AAMkADVl17IsAAA=/extensions

{
  "@odata.type" : "microsoft.graph.openTypeExtension",
  "extensionName" : "Com.Contoso.Deal",
  "companyName" : "Alpine Skis",
  "dealValue" : 1010100,
  "expirationDate" : "2015-07-03T13:04:00.000Z"
}

响应

以下示例显示了相应的响应。

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups('f5480dfd-7d77-4d0b-ba2e-3391953cc74a')/events('AAMkADVl7IsAAA%3D')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "id": "microsoft.graph.openTypeExtension.Com.Contoso.Deal",
    "extensionName": "Com.Contoso.Deal",
    "companyName": "Alpine Skis",
    "dealValue": 1010100,
    "expirationDate": "2015-07-03T13:04:00Z"
}

示例 4：在新组帖子中创建扩展

请求

以下示例使用对现有组帖子的相同 回复 作调用，在新的组帖子中创建扩展。 回复作将创建一个新帖子，并在帖子中嵌入一个新扩展。 请求正文包括 post 属性，该属性又包含新帖子的 正文 ，以及新扩展的以下数据：

  • microsoft.graph.openTypeExtension 类型。
  • 扩展名“Com.Contoso.HR”。
  • 要在 JSON 有效负载中存储为三个自定义属性的其他数据： companyName、 expirationDate和字符串 topPicks数组。
POST https://graph.microsoft.com/v1.0/groups/37df2ff0-0de0-4c33-8aee-75289364aef6/threads/AAQkADJizZJpEWwqDHsEpV_KA==/posts/AAMkADJiUg96QZUkA-ICwMubAAC1heiSAAA=/reply

{
  "post": {
    "body": {
      "contentType": "html",
      "content": "<html><body><div><div><div><div>When and where? </div></div></div></div></body></html>"
    },
  "extensions": [
    {
      "@odata.type": "microsoft.graph.openTypeExtension",
      "extensionName": "Com.Contoso.HR",
      "companyName": "Contoso",
      "expirationDate": "2015-07-03T13:04:00.000Z",
      "topPicks": [
        "Employees only",
        "Add spouse or guest",
        "Add family"
      ]
    }
  ]
  }
}

响应

以下示例显示了相应的响应。 新的组帖子中成功创建扩展仅会产生 HTTP 202 响应代码。

HTTP/1.1 202 Accepted
Content-type: text/plain
Content-Length: 0

示例 5：使用 POST作在新组帖子中创建扩展

响应 5

以下示例使用同一 POST作在新组帖子中创建扩展以创建对话。 POST作将创建一个新的对话、线程和帖子，以及嵌入在帖子中的新扩展。 请求正文包括 Topic 和 Threads 属性，以及新对话的子 帖子 对象。 post 对象又包含新帖子的正文，以及扩展的以下数据：

  • microsoft.graph.openTypeExtension 类型。
  • 扩展名“Com.Contoso.HR”。
  • 要在 JSON 有效负载中存储为三个自定义属性的其他数据： companyName、 expirationDate和字符串 topPicks数组。
POST https://graph.microsoft.com/v1.0/groups/37df2ff0-0de0-4c33-8aee-75289364aef6/conversations

{
  "Topic": "Does anyone have a second?",
  "Threads": [
    {
      "Posts": [
        {
          "Body": {
            "ContentType": "HTML",
            "Content": "This is urgent!"
          },
          "Extensions": [
            {
              "@odata.type": "microsoft.graph.openTypeExtension",
              "extensionName": "Com.Contoso.Benefits",
              "companyName": "Contoso",
              "expirationDate": "2016-08-03T11:00:00.000Z",
              "topPicks": [
                "Employees only",
                "Add spouse or guest",
                "Add family"
              ]
            }
          ]
        }
      ]
    }
  ]
}

响应 5

以下示例显示了包含新会话和线程 ID 的响应。 这个新线程包含自动创建的帖子，帖子又包含新扩展。

注意：为了提高可读性，可能缩短了此处显示的响应对象。

若要获取新扩展，首先 获取此线程中的所有帖子，线程中最初应该只有一个帖子。 然后应用帖子 ID 和扩展名 Com.Contoso.Benefits 以获取扩展。

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups('37df2ff0-0de0-4c33-8aee-75289364aef6')/conversations/$entity",
    "id": "AAQkADJToRlbJ5Mg7TFM7H-j3Y=",
    "threads": [
        {
            "id": "AAQkADJDtMUzsf_PdhAAswJOhGVsnkyDtMUzsf_Pdg=="
        }
    ]
}
  • Last updated on