创建单值扩展属性Create single-value extended property

命名空间:microsoft.graphNamespace: microsoft.graph

在新建或现有的资源实例中创建一个或多个单值扩展属性。Create one or more single-value extended properties in a new or existing instance of a resource.

支持以下用户资源:The following user resources are supported:

以及以下组资源:As well as the following group resources:

有关何时使用开放扩展或扩展属性,以及如何指定扩展属性的详细信息,请参阅扩展属性概述See Extended properties overview for more information about when to use open extensions or extended properties, and how to specify extended properties.

权限Permissions

根据您要在其中创建扩展属性的资源以及所请求的权限类型(委派或应用程序),在下表中指定的权限是调用此 API 所需的最低权限。Depending on the resource you're creating the extended property in and the permission type (delegated or application) you request, the permission specified in the following table is the minimum 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
日历calendar Calendars.ReadWriteCalendars.ReadWrite Calendars.ReadWriteCalendars.ReadWrite Calendars.ReadWriteCalendars.ReadWrite
联系人contact Contacts.ReadWriteContacts.ReadWrite Contacts.ReadWriteContacts.ReadWrite Contacts.ReadWriteContacts.ReadWrite
contactFoldercontactFolder Contacts.ReadWriteContacts.ReadWrite Contacts.ReadWriteContacts.ReadWrite Contacts.ReadWriteContacts.ReadWrite
事件event Calendars.ReadWriteCalendars.ReadWrite Calendars.ReadWriteCalendars.ReadWrite Calendars.ReadWriteCalendars.ReadWrite
日历group calendar Group.ReadWrite.AllGroup.ReadWrite.All 不支持Not supported 不支持Not supported
事件group event Group.ReadWrite.AllGroup.ReadWrite.All 不支持Not supported 不支持Not supported
帖子group post Group.ReadWrite.AllGroup.ReadWrite.All 不支持Not supported 不支持Not supported
mailFoldermailFolder Mail.ReadWriteMail.ReadWrite Mail.ReadWriteMail.ReadWrite Mail.ReadWriteMail.ReadWrite
邮件message Mail.ReadWriteMail.ReadWrite Mail.ReadWriteMail.ReadWrite Mail.ReadWriteMail.ReadWrite

HTTP 请求HTTP request

可以在新建或现有的资源实例中创建扩展属性。You can create extended properties in a new or existing resource instance.

若要在_新的_资源实例中创建一个或多个扩展属性,请使用与创建实例相同的 REST 请求,并包括新资源实例的属性和请求正文中的_扩展属性_。注意,一些资源支持以多种方式创建。有关创建这些资源实例的详细信息,请参阅创建 邮件mailFolder事件日历联系人contactFolder组事件组帖子 的相应主题。To create one or more extended properties in a new resource instance, use the same REST request as creating the instance, and include the properties of the new resource instance and extended property in the request body. Note that some resources support creation in more than one way. For more information on creating these resource instances, see the corresponding topics for creating a message, mailFolder, event, calendar, contact, contactFolder, group event, and group post.

以下是请求的语法。The following is the syntax of the requests.

POST /me/messages
POST /users/{id|userPrincipalName}/messages
POST /me/mailFolders/{id}/messages

POST /me/mailFolders
POST /users/{id|userPrincipalName}/mailFolders

POST /me/events
POST /users/{id|userPrincipalName}/events

POST /me/calendars
POST /users/{id|userPrincipalName}/calendars

POST /me/contacts
POST /users/{id|userPrincipalName}/contacts

POST /me/contactFolders
POST /users/{id|userPrincipalName}/contactFolders

POST /groups/{id}/events

POST /groups/{id}/threads/{id}/posts/{id}/reply
POST /groups/{id}/conversations/{id}/threads/{id}/posts/{id}/reply
POST /groups/{id}/threads/{id}/reply
POST /groups/{id}/conversations/{id}/threads/{id}/reply
POST /groups/{id}/threads
POST /groups/{id}/conversations

若要在现有资源实例中创建一个或多个扩展属性,请在请求中指定实例,并在请求正文中包括扩展属性。To create one or more extended properties in an existing resource instance, specify the instance in the request, and include the extended property in the request body.

注意不能在现有的组帖子中创建扩展属性。Note You cannot create an extended property in an existing group post.

PATCH /me/messages/{id}
PATCH /users/{id|userPrincipalName}/messages/{id}
PATCH /me/mailFolders/{id}/messages/{id}

PATCH /me/mailFolders/{id}
PATCH /users/{id|userPrincipalName}/mailFolders/{id}

PATCH /me/events/{id}
PATCH /users/{id|userPrincipalName}/events/{id}

PATCH /me/calendars/{id}
PATCH /users/{id|userPrincipalName}/calendars/{id}

PATCH /me/contacts/{id}
PATCH /users/{id|userPrincipalName}/contacts/{id}

PATCH /me/contactFolders/{id}
PATCH /users/{id|userPrincipalName}/contactFolders/{id}

PATCH /groups/{id}/events/{id}

请求头Request headers

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

请求正文Request body

提供每个 singleValueLegacyExtendedProperty 对象在资源实例的 singleValueExtendedProperties 集合属性中的 JSON 正文。Provide a JSON body of each singleValueLegacyExtendedProperty object in the singleValueExtendedProperties collection property of the resource instance.

属性Property 类型Type 说明Description
singleValueExtendedPropertiessingleValueExtendedProperties singleValueLegacyExtendedProperty collectionsingleValueLegacyExtendedProperty collection 一个或多个单值扩展属性的数组。An array of one or more single-valued extended properties.
idid 字符串String 对于 singleValueExtendedProperties 集合中的每个属性,请指定此参数以标识属性。它必须遵照其中一种支持的格式。有关详细信息,请参阅 Outlook 扩展属性概述。必需。For each property in the singleValueExtendedProperties collection, specify this to identify the property. It must follow one of the supported formats. See Outlook extended properties overview for more information. Required.
value stringstring 对于 singleValueExtendedProperties 集合中的每个属性,请指定属性值。必需。For each property in the singleValueExtendedProperties collection, specify the property value. Required.

在_新的_资源实例中创建扩展属性时,除了新的 singleValueExtendedProperties 集合,请提供资源实例的 JSON 表示形式(即 邮件mailFolder事件 等)。When creating an extended property in a new resource instance, in addition to the new singleValueExtendedProperties collection, provide a JSON representation of that resource instance (that is, a message, mailFolder, event, etc.)

响应Response

响应代码Response code

在新建资源实例中成功创建扩展属性的操作返回 201 Created(在新的组帖子中除外),根据所用的方法,该操作可以返回 200 OK202 AcceptedAn operation successful in creating an extended property in a new resource instance returns 201 Created, except in a new group post, depending on the method used, the operation can return 200 OK or 202 Accepted.

在现有的资源实例中,成功的创建操作返回 200 OKIn an existing resource instance, a successful create operation returns 200 OK.

响应正文Response body

创建扩展属性时,该响应只包括新建或现有的实例,但不包括新的扩展属性。若要查看新创建的扩展属性,请 获取通过扩展属性扩展的实例When creating an extended property, the response includes only the new or existing instance but not the new extended property. To see the newly created extended property, get the instance expanded with the extended property.

通过回复线程或帖子在_新建_组帖子中创建扩展属性时,响应仅包括响应代码,但不包括新帖子或扩展属性。When creating an extended property in a new group post by replying to a thread or post, the response includes only a response code but not the new post nor the extended property.

示例Example

请求 1Request 1

第一个示例在相同的 POST 操作中创建一个新事件和一个单值扩展属性。除了通常要包括的新事件的属性,请求正文还包括 singleValueExtendedProperties 集合,该集合包含一个单值扩展属性和以下属性:The first example creates a new event and a single-value extended property in the same POST operation. Apart from the properties you'd normally include for a new event, the request body includes the singleValueExtendedProperties collection that contains one single-value extended property, and the following for the property:

  • id 将属性类型指定为 String、GUID 和名为 Fun 的属性。id specifies the property type as String, the GUID, and the property named Fun.
  • valueFood 指定为 Fun 属性的值。value specifies Food as the value of the Fun property.
POST https://graph.microsoft.com/v1.0/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": [
     {
           "id":"String {66f5a359-4659-4830-9070-00040ec6ac6e} Name Fun",
           "value":"Food"
     }
  ]
}
响应 1Response 1

成功的响应由 HTTP 201 Created 响应代码表示,并在响应正文中包括新事件,类似于 仅创建事件 中的响应。该响应不包括任何新建的扩展属性。A successful response is indicated by an HTTP 201 Created response code, and includes the new event in the response body, similar to the response from creating just an event. The response does not include any newly created extended properties.

若要查看新建的扩展属性,请 获取通过扩展属性扩展的事件To see the newly created extended property, get the event expanded with the extended property.


请求 2Request 2

第二个示例为指定的现有邮件创建一个单值扩展属性。扩展属性是 singleValueExtendedProperties 数组中的唯一元素。请求正文包括扩展属性的以下参数:The second example creates one single-value extended property for the specified existing message. That extended property is the only element in the singleValueExtendedProperties array. The request body includes the following for the extended property:

  • id 将属性类型指定为 String、GUID 和名为 Color 的属性。id specifies the property type as String, the GUID, and the property named Color.
  • valueGreen 指定为 Color 属性的值。value specifies Green as the value of the Color property.
PATCH https://graph.microsoft.com/v1.0/me/messages/AAMkAGE1M2_bs88AACHsLqWAAA=

Content-Type: application/json

{
  "singleValueExtendedProperties": [
      {
         "id":"String {66f5a359-4659-4830-9070-00047ec6ac6e} Name Color",
         "value":"Green"
      }
    ]
}
响应 2Response 2

成功的响应由 HTTP 200 OK 响应代码表示,并在响应正文中包括指定的邮件,类似于 更新邮件 中的响应。该响应不包括新建的扩展属性。A successful response is indicated by an HTTP 200 OK response code, and includes the specified message in the response body, similar to the response from updating a message. The response does not include the newly created extended property.

若要查看新建的扩展属性,请 获取通过扩展属性扩展的邮件To see the newly created extended property, get the message expanded with the extended property.