通过

创建单值扩展属性

  • 项目

命名空间：microsoft.graph

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

支持以下用户资源：

以下组资源：

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

此 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

HTTP 请求

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

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

以下是请求的语法。

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

注意

调用 /me 终结点需要已登录的用户，因此需要委派权限。 使用 /me 终结点时，不支持应用程序权限。

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

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

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}

注意

调用 /me 终结点需要已登录的用户，因此需要委派权限。 使用 /me 终结点时，不支持应用程序权限。

请求标头

名称 值
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/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"
     }
  ]
}

响应

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

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

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('c71-86a-a0-92-906ba')/events/$entity",
    "@odata.etag": "W/\"oBeN/g==\"",
    "id": "AAMkADI4Yzc5AABVNeEhAAA=",
    "createdDateTime": "2023-06-26T15:46:00.9307807Z",
    "lastModifiedDateTime": "2023-06-26T15:46:02.0775731Z",
    "changeKey": "oBEEg==",
    "categories": [],
    "transactionId": null,
    "originalStartTimeZone": "Pacific Standard Time",
    "originalEndTimeZone": "Pacific Standard Time",
    "iCalUId": "04049ACBF84A7AC7CB34D",
    "reminderMinutesBeforeStart": 15,
    "isReminderOn": true,
    "hasAttachments": false,
    "subject": "Celebrate Thanksgiving",
    "bodyPreview": "Let's get together!",
    "importance": "normal",
    "sensitivity": "normal",
    "isAllDay": false,
    "isCancelled": false,
    "isOrganizer": true,
    "responseRequested": true,
    "seriesMasterId": null,
    "showAs": "busy",
    "type": "singleInstance",
    "webLink": "https://outlook.office365.com/owa/?itemid=AAMkAA%3D&exvsurl=1&path=/calendar/item",
    "onlineMeetingUrl": null,
    "isOnlineMeeting": false,
    "onlineMeetingProvider": "unknown",
    "allowNewTimeProposals": true,
    "occurrenceId": null,
    "isDraft": false,
    "hideAttendees": false,
    "responseStatus": {
        "response": "organizer",
        "time": "0001-01-01T00:00:00Z"
    },
    "body": {
        "contentType": "html",
        "content": "<html><head><meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\"></head><body>Let's get together!</body></html>"
    },
    "start": {
        "dateTime": "2015-11-26T18:00:00.0000000",
        "timeZone": "Pacific Standard Time"
    },
    "end": {
        "dateTime": "2015-11-26T23:00:00.0000000",
        "timeZone": "Pacific Standard Time"
    },
    "location": {
        "displayName": "",
        "locationType": "default",
        "uniqueIdType": "unknown",
        "address": {},
        "coordinates": {}
    },
    "locations": [],
    "recurrence": null,
    "attendees": [
        {
            "type": "required",
            "status": {
                "response": "none",
                "time": "0001-01-01T00:00:00Z"
            },
            "emailAddress": {
                "name": "Terrie Barrera",
                "address": "Terrie@contoso.com"
            }
        }
    ],
    "organizer": {
        "emailAddress": {
            "name": "MOD Administrator",
            "address": "admin@contoso.com"
        }
    },
    "onlineMeeting": null
}

示例 2：为消息创建单值扩展属性

请求

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

  • id 将属性类型指定为 String、GUID 和名为 Color 的属性。
  • value 将 Green 指定为 Color 属性的值。
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"
      }
    ]
}

响应

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

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

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('3cc-ad3-4b9-9a-54')/messages/$entity",
    "@odata.etag": "W/\"CQAAABTiMty\"",
    "id": "AAMkADQzZ1NzItKbS4P8E6VEAAA3LwToAAA=",
    "createdDateTime": "2023-05-12T15:55:56Z",
    "lastModifiedDateTime": "2023-06-23T17:45:43Z",
    "changeKey": "CQAAAAABTiMty",
    "categories": [],
    "receivedDateTime": "2023-05-12T15:55:57Z",
    "sentDateTime": "2023-05-12T15:55:48Z",
    "hasAttachments": false,
    "internetMessageId": "<odspmicro-PlannerDueDate-06c7f00e-6b5f793846-DispatchToRecipients-PreprocessPayload-r0-SendEmail@59C185B>",
    "subject": "You have upcoming tasks due",
    "bodyPreview": "Hi Alex. You have 2 tasks due.        You have upcoming tasksSubmit your expensesIn the plan  Event Plan        5/19/2023Due in 7 daysSubmit your expensesIn the plan  Event Plan        5/19/2023Due in 7 daysView tasks in  Microsoft To ",
    "importance": "normal",
    "parentFolderId": "AQMkc0BAIptLg-wTpUQAAAIBDAAAAA==",
    "conversationId": "AAQkADQzZmJLgzlRSFD0=",
    "conversationIndex": "AQHIUPQ==",
    "isDeliveryReceiptRequested": null,
    "isReadReceiptRequested": false,
    "isRead": false,
    "isDraft": false,
    "webLink": "https://outlook.office365.com/owa/?ItemID=AAP8E6vsurl=1&viewmodel=ReadMessageItem",
    "inferenceClassification": "focused",
    "body": {
        "contentType": "html",
        "content": "<html aria-hidden=\"true\" role=\"presentation\" height=\"1\" width=\"1\"></html>"
    },
    "sender": {
        "emailAddress": {
            "name": "Microsoft on behalf of your organization",
            "address": "noreply@planner.office365.com"
        }
    },
    "from": {
        "emailAddress": {
            "name": "Microsoft on behalf of your organization",
            "address": "noreply@planner.office365.com"
        }
    },
    "toRecipients": [
        {
            "emailAddress": {
                "name": "Alex Wilber",
                "address": "AlexW@contoso.com"
            }
        }
    ],
    "ccRecipients": [],
    "bccRecipients": [],
    "replyTo": [],
    "flag": {
        "flagStatus": "notFlagged"
    }
}