创建单值扩展属性

项目
10/02/2023

命名空间：microsoft.graph

重要

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

警告

Outlook 任务在 2022 年 8 月 10 日已弃用并停止返回数据。通过 Outlook 任务更新使用此功能的现有应用。

在新建或现有的资源实例中创建一个或多个单值扩展属性。

支持以下用户资源：

支持以下组资源：

组日历
组事件
组帖子

有关何时使用开放扩展或扩展属性，以及如何指定扩展属性的详细信息，请参阅扩展属性概述。

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

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

权限

根据要创建扩展属性的资源以及请求 (委托或应用程序) 的权限类型，下表中指定的权限是调用此 API 所需的最低权限。若要了解详细信息，包括如何选择权限的信息，请参阅权限。

支持的资源	委派（工作或学校帐户）	委派（个人 Microsoft 帐户）	应用程序
calendar	Calendars.ReadWrite	Calendars.ReadWrite	Calendars.ReadWrite
联系人	Contacts.ReadWrite	Contacts.ReadWrite	Contacts.ReadWrite
contactFolder	Contacts.ReadWrite	Contacts.ReadWrite	Contacts.ReadWrite
事件	Calendars.ReadWrite	Calendars.ReadWrite	Calendars.ReadWrite
组日历	Group.ReadWrite.All	不支持	不支持
组事件	Group.ReadWrite.All	不支持	不支持
组帖子	Group.ReadWrite.All	不支持	不支持
mailFolder	Mail.ReadWrite	Mail.ReadWrite	Mail.ReadWrite
邮件	Mail.ReadWrite	Mail.ReadWrite	Mail.ReadWrite
Outlook 任务	Tasks.ReadWrite	Tasks.ReadWrite	不支持
Outlook 任务文件夹	Tasks.ReadWrite	Tasks.ReadWrite	不支持

HTTP 请求

可以在新建或现有的资源实例中创建扩展属性。

若要在新的资源实例中创建一个或多个扩展属性，请使用与创建实例相同的 REST 请求，并包括新资源实例的属性和请求正文中的扩展属性。某些资源支持以多种方式创建。有关创建这些资源实例的详细信息，请参阅有关创建邮件、 mailFolder、事件、日历、联系人、 contactFolder、 Outlook 任务、 Outlook 任务、Outlook 任务文件夹、组事件和组帖子的相应主题。

以下是请求的语法。

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 /me/outlook/tasks
POST /users/{id|userPrincipalName}/outlook/tasks
POST /me/outlook/taskFolders/{id}/tasks
POST /users/{id|userPrincipalName}/outlook/taskFolders/{id}/tasks
POST /me/outlook/taskGroups/{id}/taskFolders/{id}/tasks
POST /users/{id|userPrincipalName}/outlook/taskGroups/{id}/taskFolders/{id}/tasks

POST /me/outlook/taskFolders
POST /users/{id|userPrincipalName}/outlook/taskFolders
POST /me/outlook/taskGroups/{id}/taskFolders
POST /users/{id|userPrincipalName}/outlook/taskGroups/{id}/taskFolders

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

若要在现有资源实例中创建一个或多个扩展属性，请在请求中指定实例，并在请求正文中包括扩展属性。

注意无法在现有组帖子中创建扩展属性。

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 /me/outlook/tasks/{id}
PATCH /users/{id|userPrincipalName}/outlook/tasks/{id}
PATCH /me/outlook/taskFolders/{id}/tasks/{id}
PATCH /users/{id|userPrincipalName}/outlook/taskFolders/{id}/tasks/{id}
PATCH /me/outlook/taskGroups/{id}/taskFolders/{id}/tasks/{id}
PATCH /users/{id|userPrincipalName}/outlook/taskGroups/{id}/taskFolders/{id}/tasks/{id}

PATCH /me/outlook/taskFolders/{id}
PATCH /users/{id|userPrincipalName}/outlook/taskFolders/{id}
PATCH /me/outlook/taskGroups/{id}/taskFolders/{id}
PATCH /users/{id|userPrincipalName}/outlook/taskGroups/{id}/taskFolders/{id}

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

请求标头

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

请求正文

提供每个 singleValueLegacyExtendedProperty 对象在资源实例的 singleValueExtendedProperties 集合属性中的 JSON 正文。

属性	类型	说明
singleValueExtendedProperties	singleValueLegacyExtendedProperty 集合	一个或多个单值扩展属性的数组。
id	String	对于 singleValueExtendedProperties 集合中的每个属性，请指定此参数以标识属性。它必须遵照其中一种支持的格式。有关详细信息，请参阅 Outlook 扩展属性概述。必需。
值	string	对于 singleValueExtendedProperties 集合中的每个属性，请指定属性值。必填。

在新的资源实例中创建扩展属性时，除了新的 singleValueExtendedProperties 集合，请提供资源实例的 JSON 表示形式（即邮件、mailFolder、事件等）。

响应

响应代码

在新建资源实例中成功创建扩展属性的操作返回 201 Created（在新的组帖子中除外），根据所用的方法，该操作可以返回 200 OK 或 202 Accepted。

在现有的资源实例中，成功的创建操作返回 200 OK。

响应正文

创建扩展属性时，该响应只包括新建或现有的实例，但不包括新的扩展属性。若要查看新创建的扩展属性，请获取通过扩展属性扩展的实例。

通过回复线程或帖子在新组帖子中创建扩展属性时，响应仅包括响应代码，但不包括新帖子和扩展属性。

示例

请求 1

第一个示例在相同的 POST 操作中创建一个新事件和一个单值扩展属性。除了通常要包括的新事件的属性，请求正文还包括 singleValueExtendedProperties 集合，该集合包含一个单值扩展属性和以下属性：

id 将属性类型指定为 String、GUID 和名为 Fun 的属性。
value 将 Food 指定为 Fun 属性的值。

POST https://graph.microsoft.com/beta/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"
     }
  ]
}

响应 1

成功的响应由 HTTP 201 Created 响应代码表示，并在响应正文中包括新事件，类似于仅创建事件中的响应。响应不包括任何新创建的扩展属性。

若要查看新建的扩展属性，请获取通过扩展属性扩展的事件。

请求 2

第二个示例为指定的现有邮件创建一个单值扩展属性。扩展属性是 singleValueExtendedProperties 数组中的唯一元素。请求正文包括扩展属性的以下参数：

id 将属性类型指定为 String、GUID 和名为 Color 的属性。
value 将 Green 指定为 Color 属性的值。

PATCH https://graph.microsoft.com/beta/me/messages('AAMkAGE1M2_bs88AACHsLqWAAA=')

Content-Type: application/json

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

响应 2

成功的响应由 HTTP 200 OK 响应代码表示，并在响应正文中包括指定的邮件，类似于更新邮件中的响应。响应不包括新创建的扩展属性。

若要查看新建的扩展属性，请获取通过扩展属性扩展的邮件。

通过