创建开放扩展Create open extension

重要

Microsoft Graph 中/beta的版本下的 api 可能会发生更改。APIs under the /beta version in Microsoft Graph are subject to change. 不支持在生产应用程序中使用这些 API。Use of these APIs in production applications is not supported.

创建开放扩展 (openTypeExtension对象), 并在新的或现有的受支持的资源实例中添加自定义属性。Create an open extension (openTypeExtension object) and add custom properties in a new or existing instance of a supported resource.

请注意: 如果要在 Outlook 资源上创建开放扩展,请参阅 openTypeExtension 资源类型中的 Outlook 特定注意事项Note: If you're creating open extensions on Outlook resources, see Outlook-specific considerations in openTypeExtension resource type.

权限Permissions

根据要在其中创建扩展的资源和所请求的权限类型(委派或应用程序),下表中指定的权限是指调用此 API 所需的最低限度的特权。Depending on the resource you're creating the extension in and the permission type (delegated or application) requested, the permission specified in the following table is the least privileged required to call this API. 若要了解详细信息,包括如何选择权限的信息,请参阅权限To learn more, including how to choose permissions, see Permissions.

支持的资源Supported resource 委派(工作或学校帐户)Delegated (work or school account) 委派(个人 Microsoft 帐户)Delegated (personal Microsoft account) 应用程序Application
设备device Directory.AccessAsUser.AllDirectory.AccessAsUser.All 不支持Not supported Device.ReadWrite.AllDevice.ReadWrite.All
事件event Calendars.ReadWriteCalendars.ReadWrite Calendars.ReadWriteCalendars.ReadWrite Calendars.ReadWriteCalendars.ReadWrite
group Group.ReadWrite.AllGroup.ReadWrite.All 不支持Not supported Group.ReadWrite.AllGroup.ReadWrite.All
组事件group event Group.ReadWrite.AllGroup.ReadWrite.All 不支持Not supported 不支持Not supported
组帖子group post Group.ReadWrite.AllGroup.ReadWrite.All 不支持Not supported Group.ReadWrite.AllGroup.ReadWrite.All
邮件message Mail.ReadWriteMail.ReadWrite Mail.ReadWriteMail.ReadWrite Mail.ReadWriteMail.ReadWrite
组织organization Directory.AccessAsUser.AllDirectory.AccessAsUser.All 不支持Not supported 不支持Not supported
个人联系人personal contact Contacts.ReadWriteContacts.ReadWrite Contacts.ReadWriteContacts.ReadWrite Contacts.ReadWriteContacts.ReadWrite
用户user User.ReadWrite.AllUser.ReadWrite.All User.ReadWriteUser.ReadWrite User.ReadWrite.AllUser.ReadWrite.All

HTTP 请求HTTP request

在新资源实例中创建扩展插件Create an extension in a new resource instance

使用创建实例时所用的同一 REST 请求。Use the same REST request that you use to create the instance.

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

请注意: 此语法显示了一些创建受支持资源实例的常用方式。Note: This syntax shows some common ways to create the supported resource instances. 可用来创建这些资源实例的所有其他 POST 语法均支持以类似的方式从中创建开放扩展。All other POST syntaxes that allows you to create these resource instances supports creating open extensions in them in a similar way.

若要了解如何在请求正文中添加新资源实例和_扩展_的属性,请参阅请求正文部分。See the Request body section about including the properties of the new resource instance and the extension in the request body.

在现有资源实例中创建扩展插件Create an extension in an existing resource instance

在请求中标识资源实例,然后对 extensions 导航属性执行 POSTIdentify the resource instance in the request and do a POST to the extensions navigation property.

POST /administrativeunits/{id}/extensions
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

请注意: 以上语法显示一些标识资源实例的常见方法,以便在其中创建一个扩展。Note: This syntax shows some common ways to identify a resource instance, in order to create an extension in it. 可用来标识这些资源实例的所有其他语法均支持以类似的方式在其中创建开放扩展。All other syntaxes that allows you to identify these resource instances supports creating open extensions in them in a similar way.

若要了解如何在请求正文中添加_扩展_,请参阅请求正文部分。See the Request body section about including the extension in the request body.

路径参数Path parameters

参数Parameter 类型Type 说明Description
idid stringstring 对象在相应集合中的唯一标识符。必需。A unique identifier for an object in the corresponding collection. Required.

请求标头Request headers

名称Name Value
AuthorizationAuthorization Bearer {token}。必需。Bearer {token}. Required.
Content-TypeContent-Type application/jsonapplication/json

请求正文Request body

提供具有以下必需的名称-值对和任何其他自定义数据的openTypeExtension的 JSON 正文。JSON 有效负载中的数据可以是基元类型, 也可以是基元类型的数组。Provide a JSON body of an openTypeExtension, with the following required name-value pairs and any additional custom data. The data in the JSON payload can be primitive types, or arrays of primitive types.

名称Name Value
@odata.type@odata.type microsoft.graph.openTypeExtensionmicrosoft.graph.openTypeExtension
extensionNameextensionName %unique_string%%unique_string%

在_新_资源实例中创建扩展插件时,除了新的 openTypeExtension 对象之外,还要提供 JSON 表示形式的相关属性才能创建此类资源实例。When creating an extension in a new resource instance, in addition to the new openTypeExtension object, provide a JSON representation of the relevant properties to create such a resource instance.

响应Response

响应代码Response code

响应代码可以是 201 Created,也可以是 202 Accepted,具体视操作而定。Depending on the operation, the response code can be 201 Created or 202 Accepted.

使用创建资源实例时所用的操作创建扩展时,操作所返回的响应代码与通过该操作创建不带扩展的资源实例时返回的代码相同。When you create an extension using the same operation that you use to create a resource instance, the operation returns the same response code that it returns when you use the operation to create the resource instance without the extension. 请参阅有关创建实例的相应主题,如所列。Refer to the corresponding topics for creating the instance, as listed above.

响应正文Response body

应用场景Scenario 资源Resource 响应正文Response body
在显式创建_新_资源实例的同时创建扩展插件Creating an extension while explicitly creating a new resource instance 联系人事件邮件contact, event, message 包括使用 openTypeExtension 对象扩展的新实例。Includes the new instance expanded with the openTypeExtension object.
在隐式创建资源实例的同时创建扩展插件Creating an extension while implicitly creating a resource instance 帖子post 响应只包括响应代码,不包括响应正文。The response includes only a response code but not a response body.
在_现有_资源实例中创建扩展插件Creating an extension in an existing resource instance 所有支持的资源All supported resources 包括 openTypeExtension 对象。Includes the openTypeExtension object.

示例Example

请求 1Request 1

第一个示例在同一个调用中创建一个邮件和一个扩展。请求正文包含以下内容:The first example creates a message and an extension in the same call. The request body includes the following:

  • 新邮件的典型 subjectbodytoRecipients 属性。The subject, body, and toRecipients properties typical of a new message.

  • 对于扩展:And for the extension:

    • microsoft.graph.openTypeExtension 类型。The type microsoft.graph.openTypeExtension.
    • 扩展名“Com.Contoso.Referral”。The extension name "Com.Contoso.Referral".
    • 存储为 JSON 有效负载中的 3 个自定义属性的其他数据:companyNameexpirationDatedealValueAdditional data to be stored as three custom properties in the JSON payload: companyName, expirationDate, and dealValue.
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
    }
  ]
}

响应 1Response 1

下面是第一个示例的响应。响应正文包括新邮件的属性以及新扩展的以下属性:Here is the response for the first example. The response body includes properties of the new message, and the following for the new extension:

  • 具有完全限定的名称 **** 的 microsoft.graph.openTypeExtension.Com.Contoso.Referral 属性。The id property with the fully qualified name of microsoft.graph.openTypeExtension.Com.Contoso.Referral.
  • 请求中指定的默认属性 extensionNameThe default property extensionName specified in the request.
  • 请求中指定的作为 3 个自定义属性存储的自定义数据。The custom data specified in the request stored as 3 custom properties.

注意:为了简单起见,可能会将此处所示的响应对象截断。将从实际调用中返回所有属性。Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

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.context": "https://graph.microsoft.com/beta/$metadata#Me/messages
('AAMkAGEbs88AAB84uLuAAA%3D')/extensions",
  "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
    }
  ]
}

请求 2Request 2

第二个示例在指定邮件中创建扩展。请求正文包括扩展的如下内容:The second example creates an extension in the specified message. The request body includes the following for the extension:

  • microsoft.graph.openTypeExtension 类型。The type microsoft.graph.openTypeExtension.
  • 扩展名“Com.Contoso.Referral”。The extension name "Com.Contoso.Referral".
  • 存储为 JSON 负载中的 3 个自定义属性的其他数据:companyNamedealValueexpirationDateAdditional data to be stored as 3 custom properties in the JSON payload: companyName, dealValue, and expirationDate.
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"
}

响应 2Response 2

下面是第二个示例的响应。请求正文包括新扩展的如下内容:Here is the response for the second example. The response body includes the following for the new extension:

  • 默认属性 extensionNameThe default property extensionName.
  • 具有完全限定的名称 microsoft.graph.openTypeExtension.Com.Contoso.ReferralId 属性。The id property with the fully qualified name of microsoft.graph.openTypeExtension.Com.Contoso.Referral.
  • 要存储的自定义数据。The custom data to be stored.
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"
}

请求 3Request 3

第三个示例在指定组事件中创建扩展。请求正文包括扩展的如下内容:The third example creates an extension in the specified group event. The request body includes the following for the extension:

  • microsoft.graph.openTypeExtension 类型。The type microsoft.graph.openTypeExtension.
  • 扩展名“Com.Contoso.Deal”。The extension name "Com.Contoso.Deal".
  • 存储为 JSON 负载中的 3 个自定义属性的其他数据:companyNamedealValueexpirationDateAdditional data to be stored as 3 custom properties in the JSON payload: companyName, dealValue, and expirationDate.
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"
}

响应 3Response 3

下面是第三个示例请求的响应。Here is the response from the third example request.

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

请求 4Request 4

第四个示例对现有的组帖子使用相同的 reply 操作调用,在新的组帖子中创建扩展。reply 操作创建新帖子和嵌入帖子中的新扩展。请求正文包括 post 属性,此属性又包含新帖子的 body 以及新扩展的以下数据:The fourth example creates an extension in a new group post, using the same reply action call to an existing group post. The reply action creates a new post, and a new extension embedded in the post. The request body includes a post property, which in turn contains the body of the new post, and the following data for the new extension:

  • microsoft.graph.openTypeExtension 类型。The type microsoft.graph.openTypeExtension.
  • 扩展名“Com.Contoso.HR”。The extension name "Com.Contoso.HR".
  • 存储为 JSON 负载中的 3 个自定义属性的其他数据:companyNameexpirationDatetopPicks 字符串数组。Additional data to be stored as 3 custom properties in the JSON payload: companyName, expirationDate, and the array of strings topPicks.
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"
      ]
    }
  ]
  }
}

响应 4Response 4

下面是第四个示例的响应。新的组帖子中成功创建扩展仅会产生 HTTP 202 响应代码。Here is the response from the fourth example. Successfully creating an extension in a new group post results in only the HTTP 202 response code.

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

响应 5Request 5

第五个示例使用 POST 操作创建对话,在新的组帖子中创建扩展。POST 操作创建新对话、线程和帖子以及嵌入帖子中的新扩展。请求正文包括 TopicThreads 属性以及新对话的子 post 对象。post 对象又包含新帖子的 body 和以下扩展数据:The fifth example creates an extension in a new group post using the same POST operation to create a conversation. The POST operation creates a new conversation, thread and post, and a new extension embedded in the post. The request body includes the Topic and Threads properties, and a child post object for the new conversation. The post object in turn contains the body of the new post, and the following data for the extension:

  • microsoft.graph.openTypeExtension 类型。The type microsoft.graph.openTypeExtension.
  • 扩展名“Com.Contoso.HR”。The extension name "Com.Contoso.HR".
  • 存储为 JSON 负载中的 3 个自定义属性的其他数据:companyNameexpirationDatetopPicks 字符串数组。Additional data to be stored as 3 custom properties in the JSON payload: companyName, expirationDate, and the array of strings topPicks.
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"
              ]
            }
          ]
        }
      ]
    }
  ]
}

响应 5Response 5

下面是第五个示例的响应,其中包含新对话和线程 ID。这个新线程包含自动创建的帖子,帖子又包含新扩展。Here is the response from the fifth example which contains the new conversation and a thread ID. This new thread contains an automatically created post, which in turn contains the new extension.

注意:为了简单起见,可能会将此处所示的响应对象截断。将从实际调用中返回所有属性。Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

若要获取新扩展,首先 获取此线程中的所有帖子,线程中最初应该只有一个帖子。然后应用帖子 ID 和扩展名 Com.Contoso.Benefits获取扩展To get the new extension, first get all the posts in this thread, and initially there should be only one. Then apply the post ID and the extension name Com.Contoso.Benefits to get the extension.

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@odata.context": "https://graph.microsoft.com/beta/$metadata#groups('37df2ff0-0de0-4c33-8aee-75289364aef6')/conversations('AAQkADJToRlbJ5Mg7TFM7H-j3Y%3D')/threads",
    "threads": [
        {
            "id": "AAQkADJDtMUzsf_PdhAAswJOhGVsnkyDtMUzsf_Pdg=="
        }
    ]
}