创建 openTypeExtension

命名空间:microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用,请使用 版本 选择器。

警告

应更新将此功能与 baseTaskbaseTaskList 配合使用的现有应用,因为自 2022 年 5 月 31 日起,基于这些资源构建的待办事项 API 集已弃用。 该 API 集将于 2022 年 8 月 31 日停止返回数据。 请使用基于 todoTask 构建的 API 集。

创建开放扩展(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 不支持
todoTaskList Tasks.ReadWrite Tasks.ReadWrite 不支持
用户 User.ReadWrite User.ReadWrite User.ReadWrite.All
baseTask (已弃用) Tasks.ReadWrite Tasks.ReadWrite 不支持
baseTaskList (已弃用) Tasks.ReadWrite Tasks.ReadWrite 不支持

HTTP 请求

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

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

POST /users/{userId|userPrincipalName}/events
POST /users/{userId|userPrincipalName}/messages
POST /groups/{userId}/events
POST /groups/{userId}/threads/{threadId}/posts/{postId}/reply
POST /users/{userId|userPrincipalName}/contacts
POST /users/{userId|userPrincipalName}/todo/lists/{listId}/tasks
POST /users/{userId|userPrincipalName}/todo/lists
POST /users/{userId|userPrincipalName}/tasks/lists/{listId}/tasks
POST /users/{userId|userPrincipalName}/tasks/lists

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

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

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

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

POST /administrativeunits/{administrativeUnitId}/extensions
POST /devices/{deviceId}/extensions
POST /users/{userId|userPrincipalName}/events/{eventId}/extensions
POST /groups/{groupId}/extensions
POST /groups/{groupId}/events/{eventId}/extensions
POST /groups/{groupId}/threads/{threadId}/posts/{postId}/extensions
POST /users/{userId|userPrincipalName}/messages/{messageId}/extensions
POST /organization/{organizationId}/extensions
POST /users/{userId|userPrincipalName}/contacts/{contactId}/extensions
POST /users/{userId|userPrincipalName}/extensions
POST /users/{userId|userPrincipalName}/todo/lists/{listId}/tasks/{taskId}/extensions
POST /users/{userId|userPrincipalName}/todo/lists/{listId}/extensions
POST /users/{userId|userPrincipalName}/tasks/lists/{listId}/tasks/{taskId}/extensions
POST /users/{userId|userPrincipalName}/tasks/lists/{listId}/extensions

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

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

请求标头

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

请求正文

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

名称
@odata.type microsoft.graph.openTypeExtension
extensionName 唯一字符串

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

响应

响应代码

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

使用创建资源实例时所用的操作创建扩展时,操作所返回的响应代码与通过该操作创建不带扩展的资源实例时返回的代码相同。 请参阅有关创建实例的相应主题,如所列。

响应正文

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

示例

请求 1

第一个示例在同一个调用中创建一个邮件和一个扩展。 请求正文包含以下内容:

  • 新邮件的典型 subjectbodytoRecipients 属性。

  • 对于扩展:

    • microsoft.graph.openTypeExtension 类型。
    • 扩展名“Com.Contoso.Referral”。
    • 存储为 JSON 有效负载中的 3 个自定义属性的其他数据:companyNameexpirationDatedealValue
POST https://graph.microsoft.com/beta/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.graph.openTypeExtension",
      "extensionName": "Com.Contoso.Referral",
      "companyName": "Wingtip Toys",
      "expirationDate": "2015-12-30T11:00:00.000Z",
      "dealValue": 10000
    }
  ]
}

响应 1

下面是第一个示例的响应。 响应正文包括新邮件的属性以及新扩展的以下属性:

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

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

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#Me/messages/$entity",
  "@odata.id": "https://graph.microsoft.com/beta/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/beta/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 个自定义属性的其他数据:companyNamedealValueexpirationDate
POST https://graph.microsoft.com/beta/me/messages/AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===/extensions
Content-Type: application/json

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

响应 2

下面是第二个示例的响应。 请求正文包括新扩展的如下内容:

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#Me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "@odata.id": "https://graph.microsoft.com/beta/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 个自定义属性的其他数据:companyNamedealValueexpirationDate
POST https://graph.microsoft.com/beta/groups/f5480dfd-7d77-4d0b-ba2e-3391953cc74a/events/AAMkADVl17IsAAA=/extensions
Content-type: application/json

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

响应 3

下面是第三个示例请求的响应。

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$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 负载中的 3 个自定义属性的其他数据:companyNameexpirationDatetopPicks 字符串数组。
POST https://graph.microsoft.com/beta/groups/37df2ff0-0de0-4c33-8aee-75289364aef6/threads/AAQkADJizZJpEWwqDHsEpV_KA==/posts/AAMkADJiUg96QZUkA-ICwMubAAC1heiSAAA=/reply
Content-type: application/json

{
  "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"
      ]
    }
  ]
  }
}

响应 4

下面是第四个示例的响应。 新的组帖子中成功创建扩展仅会产生 HTTP 202 响应代码。

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

响应 5

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

  • microsoft.graph.openTypeExtension 类型。
  • 扩展名“Com.Contoso.HR”。
  • 存储为 JSON 负载中的 3 个自定义属性的其他数据:companyNameexpirationDatetopPicks 字符串数组。
POST https://graph.microsoft.com/beta/groups/37df2ff0-0de0-4c33-8aee-75289364aef6/conversations
Content-type: application/json

{
  "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/beta/$metadata#groups('37df2ff0-0de0-4c33-8aee-75289364aef6')/conversations/$entity",
    "id": "AAQkADJToRlbJ5Mg7TFM7H-j3Y=",
    "threads": [
        {
            "id": "AAQkADJDtMUzsf_PdhAAswJOhGVsnkyDtMUzsf_Pdg=="
        }
    ]
}