更新 openTypeExtension

命名空间:microsoft.graph

重要

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

警告

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

(受支持的资源类型上的 openTypeExtension 对象) 更新打开的扩展。

  • 如果请求正文中的属性与现有属性在扩展中的名称相匹配,则更新扩展中的数据。
  • 否则,该属性及其数据将添加到扩展。

扩展中的数据可以是基元类型或基元类型的数组。 作为目录对象的资源与其他资源的作行为不同。

有关支持开放扩展的资源列表,请参阅 权限 部分中的表。

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

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

权限

根据创建扩展的资源以及 (委托的权限类型或请求的应用程序) 类型,下表中指定的权限是调用此 API 所需的最低特权。 若要了解其他信息, 特权权限之前要特别小心,在"权限" 中搜索

支持的资源 委派(工作或学校帐户) 委派(个人 Microsoft 帐户) 应用程序
设备 Directory.AccessAsUser.All 不支持。 Device.ReadWrite.All
driveItem Files.ReadWrite Files.ReadWrite 不支持。
事件 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
site Sites.ReadWrite.All 不支持。 不支持。
todoTask Tasks.ReadWrite Tasks.ReadWrite 不支持。
todoTasklist Tasks.ReadWrite Tasks.ReadWrite 不支持。
用户 User.ReadWrite 不支持。 User.ReadWrite.All
baseTask (已弃用) Tasks.ReadWrite Tasks.ReadWrite 不支持。
baseTasklist (已弃用) Tasks.ReadWrite Tasks.ReadWrite 不支持。

HTTP 请求

在请求中,标识资源实例,使用资源实例的 extensions 导航属性标识扩展插件,然后对此扩展插件实例执行 PATCH

PATCH /administrativeUnits/{administrativeUnitId}/extensions/{extensionId}
PATCH /devices/{deviceId}/extensions/{extensionId}
PATCH /users/{userId|userPrincipalName}/events/{eventId}/extensions/{extensionId}
PATCH /groups/{groupId}/extensions/{extensionId}
PATCH /groups/{groupId}/events/{eventId}/extensions/{extensionId}
PATCH /groups/{groupId}/threads/{threadId}/posts/{postId}/extensions/{extensionId}
PATCH /users/{userId|userPrincipalName}/messages/{messageId}/extensions/{extensionId}
PATCH /organization/{organizationId}/extensions/{extensionId}
PATCH /users/{userId|userPrincipalName}/contacts/{contactId}/extensions/{extensionId}
PATCH /users/{userId|userPrincipalName}/extensions/{extensionId}
PATCH /users/me/todo/lists/{listId}/tasks/{taskId}/extensions/{extensionId}
PATCH /users/me/todo/lists/{listId}/extensions/{extensionId}
PATCH /users/me/tasks/lists/{listId}/tasks/{taskId}/extensions/{extensionId}
PATCH /users/me/tasks/lists/{listId}/extensions/{extensionId}
PATCH /drive/items/{itemId}/extensions/{extensionId}
PATCH /sites/{siteId}/extensions/{extensionId}

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

若要了解如何在请求正文中添加任意自定义数据来进行更改或添加到扩展插件,请参阅请求正文部分。

请求标头

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

请求正文

在请求正文中, 提供要更新的属性的值。 请求正文中未包含的现有属性会保留其以前的值,或者根据对其他属性值的更改重新计算。

下表指定可更新的属性。

提供 openTypeExtension 对象的 JSON 正文(具有以下所需的名称-值对)以及要更改或添加到该扩展中的任意定义数据。

属性 类型 说明
@odata.type String 必须是 #microsoft.graph.openTypeExtension。 必填。
extensionName String 如果未提供 ID ,则为必需。 更新。
id String 如果未提供 ID ,则为必需。 只读。

对于目录 (Microsoft Entra ID) 对象的资源:

  • 若要更新打开的扩展对象中的任何属性,必须在请求正文中指定 所有 属性;否则,Microsoft Graph 删除未指定的属性。
  • 若要从打开的扩展对象中的属性中删除数据,但保留该属性,请将其值设置为 null
  • 若要从打开的扩展对象中删除属性,请不要在 PATCH 请求正文中传递该属性,Microsoft Graph 将其删除。
  • 若要从打开的扩展对象中的所有属性中删除数据,但保留打开的扩展对象,请将所有属性的值更新为 null

对于Microsoft消息等 365 个资源:

  • 可以在请求正文中指定属性的子集来更新它们。 将保留省略的属性及其值。
  • null 不允许使用 值。

响应

如果成功,此方法返回 204 No Content 目录对象的响应代码或 200 OK 响应代码,并为其他资源返回更新的 openTypeExtension 对象。

示例

请求 1

第一个示例展示如何在邮件中更新扩展。 该扩展最初由以下 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.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
    "extensionName": "Com.Contoso.Referral",
    "id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
    "companyName": "Wingtip Toys",
    "dealValue": 500050,
    "expirationDate": "2015-12-03T10:00:00Z"
}

可以按其名称引用该扩展,

PATCH https://graph.microsoft.com/beta/me/messages/AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===/extensions/Com.Contoso.Referral

或者,也可以通过其完全限定的名称引用扩展:

PATCH https://graph.microsoft.com/beta/me/messages/AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===/extensions/Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral

可以通过以下方法,使用示例请求和以下请求正文更新以上扩展:

  • companyNameWingtip Toys 更改为 Wingtip Toys (USA)
  • dealValue500050 更改为 500100
  • 将新数据添加为自定义属性 updated
{
    "@odata.type": "microsoft.graph.openTypeExtension",
    "extensionName": "Com.Contoso.Referral",
    "companyName": "Wingtip Toys (USA)",
    "dealValue": "500100",
    "expirationDate": "2015-12-03T10:00:00.000Z",
    "updated": "2015-10-29T11:00:00.000Z"
} 

响应 1

无论用于引用扩展的方式如何,该响应都相同。

HTTP/1.1 200 OK
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.OutlookServices.OpenTypeExtension.Com.Contoso.Referral')",
    "id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Referral",
    "extensionName": "Com.Contoso.Referral",
    "companyName": "Wingtip Toys (USA)",
    "dealValue": 500100,
    "expirationDate": "2015-12-03T10:00:00Z",
    "updated": "2015-10-29T11:00:00.000Z"
}

请求 2

第二个示例展示如何在组帖子中更新扩展。 该扩展最初由以下 JSON 负载表示,其中的 expirationDate 的值为 2015-07-03T13:04:00Z

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups('37df2ff0-0de0-4c33-8aee-75289364aef6')/threads('AAQkADJizZJpEWwqDHsEpV_KA%3D%3D')/posts('AAMkADJiUg96QZUkA-ICwMubAADDEd7UAAA%3D')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Estimate",
    "extensionName": "Com.Contoso.Estimate",
    "companyName": "Contoso",
    "expirationDate": "2015-07-03T13:04:00Z",
    "DealValue": 1010100,
    "Strings@odata.type": "#Collection(String)",
    "topPicks": [
        "Employees only",
        "Add spouse or guest",
        "Add family"
    ]
}

以下是要将 expirationDate 更改为 2016-07-30T11:00:00Z 的请求和请求正文:

PATCH https://graph.microsoft.com/beta/groups/37df2ff0-0de0-4c33-8aee-75289364aef6/threads/AAQkADJizZJpEWwqDHsEpV_KA==/posts/AAMkADJiUg96QZUkA-ICwMubAADDEd7UAAA=/extensions/Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Estimate
Content-type: application/json

{
   "@odata.type": "#microsoft.outlookServices.openTypeExtension",
   "extensionName": "Com.Contoso.Estimate",
   "companyName": "Contoso",
   "expirationDate": "2016-07-30T11:00:00.000Z",
   "DealValue": 1010100,
   "topPicks": [
       "Employees only",
       "Add spouse or guest",
       "Add family"
    ]
}

响应 2

下面是第二个示例的响应,显示了扩展中更新的 expirationDate

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#groups('37df2ff0-0de0-4c33-8aee-75289364aef6')/threads('AAQkADJizZJpEWwqDHsEpV_KA%3D%3D')/posts('AAMkADJiUg96QZUkA-ICwMubAADDEd7UAAA%3D')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "id": "Microsoft.OutlookServices.OpenTypeExtension.Com.Contoso.Estimate",
    "extensionName": "Com.Contoso.Estimate",
    "companyName": "Contoso",
    "expirationDate": "2016-07-30T11:00:00Z",
    "DealValue": 1010100,
    "Strings@odata.type": "#Collection(String)",
    "topPicks": [
        "Employees only",
        "Add spouse or guest",
        "Add family"
    ]
}

请求 3

以下示例演示如何更新 driveItem 上的开放扩展。

PATCH https://graph.microsoft.com/beta/drive/items/01FWCEC553UUOHTOAGBVE2IXBQTIZY3JZQ/extensions/Com.Contoso.Estimate
Content-type: application/json

{
  "extensionName": "newExtensionName",
  "myCustomString": "Contoso data",
  "myCustomBool": false
}

响应 3

以下示例显示了在扩展中包含更新的 extensionName 的响应。

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

{
  "id": "extensionId",
  "extensionName": "newExtensionName",
  "myCustomString": "Contoso data",
  "myCustomBool": false
}

请求 4

以下示例演示如何更新 网站上的打开的扩展。

PATCH https://graph.microsoft.com/beta/sites/8f52f9ad-4f4f-4739-b682-7c0283207937/extensions/Com.Contoso.Estimate
Content-type: application/json

{
  "extensionName": "newExtensionName",
  "myCustomString": "Contoso data",
  "myCustomBool": false
}

响应 4

以下示例显示了在扩展中包含更新的 extensionName 的响应。

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

{
  "id": "extensionId",
  "extensionName": "newExtensionName",
  "myCustomString": "Contoso data",
  "myCustomBool": false
}