更新订阅

命名空间:microsoft.graph

重要

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

通过延长到期时间续订订阅。

“ 权限 ”部分中的表列出了支持订阅更改通知的资源。

订阅将在一段时间后过期,该时间长度因资源类型而异。 为了避免错过更改通知,应用应在订阅到期日期之前尽早续订其订阅。 有关每种资源类型的最大订阅长度,请参阅 订阅 。

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

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

权限

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

注意

某些资源支持多种方案中的更改通知,每种方案可能需要不同的权限。 在这些情况下,请使用资源路径来区分方案。

支持的资源 委派(工作或学校帐户) 委派(个人 Microsoft 帐户) 应用程序
aiInsights
/copilot/users/{userId}/onlineMeetings/getAllAiInsights
特定用户参与的会议中的 Copilot AI 见解。
OnlineMeetingAiInsight.Read.All 不支持。 OnlineMeetingAiInsight.Read.All
aiInsights
/copilot/users/{userId}/onlineMeetings/{onlineMeetingId}/aiInsights
特定会议的 Copilot AI 见解。
OnlineMeetingAiInsight.Read.All 不支持。 OnlineMeetingAiInsight.Read.All
aiInteraction
copilot/users/{userId}/interactionHistory/getAllEnterpriseInteractions
特定用户所属的 Copilot AI 交互。
AiEnterpriseInteraction.Read 不支持。 AiEnterpriseInteraction.Read.All、AiEnterpriseInteraction.Read.User
aiInteraction
copilot/interactionHistory/getAllEnterpriseInteractions
组织中的 Copilot AI 交互。
不支持。 不支持。 AiEnterpriseInteraction.Read.All
approvalItems 不支持。 不支持。 ApprovalSolution.ReadWrite.All
callRecord 不支持。 不支持。 CallRecords.Read.All
callRecording
communications/onlineMeetings/getAllRecordings
任何录制内容在租户中都可用。
不支持。 不支持。 OnlineMeetingRecording.Read.All
callRecording
communications/onlineMeetings/{onlineMeetingId}/recordings
任何录制内容都可用于特定会议。
OnlineMeetingRecording.Read.All 不支持。 OnlineMeetingRecording.Read.All
callRecording
users/{userId}/onlineMeetings/getAllRecordings
在特定用户组织的会议中变为可用的通话录制。
OnlineMeetingRecording.Read.All 不支持。 OnlineMeetingRecording.Read.All
callRecording
appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings
在安装了特定 Teams 应用的会议中变为可用的通话录制。
不支持。 不支持。 OnlineMeetingRecording.Read.All, OnlineMeetingRecording.Read.对话助手
callTranscript
communications/onlineMeetings/getAllTranscripts
任何脚本在租户中变为可用。
不支持。 不支持。 OnlineMeetingTranscript.Read.All
callTranscript
communications/onlineMeetings/{onlineMeetingId}/transcripts
任何脚本都可用于特定会议。
OnlineMeetingTranscript.Read.All 不支持。 OnlineMeetingTranscript.Read.All
callTranscript
users/{userId}/onlineMeetings/getAllTranscripts
在特定用户组织的会议中变为可用的通话脚本。
OnlineMeetingTranscript.Read.All 不支持。 OnlineMeetingTranscript.Read.All
callTranscript
appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTranscripts
在安装了特定 Teams 应用的会议中变为可用的通话脚本。
不支持。 不支持。 OnlineMeetingTranscript.Read.All、OnlineMeetingTranscript.Read.对话助手
频道
/teams/getAllChannels
组织中的所有频道。
不支持。 不支持。 Channel.ReadBasic.All,ChannelSettings.Read.All
频道
/teams/{id}/channels
组织中特定团队中的所有频道。
Channel.ReadBasic.All,ChannelSettings.Read.All 不支持。 Channel.ReadBasic.All,ChannelSettings.Read.All
聊天
/chats
组织中的所有聊天。
不支持。 不支持。 Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
聊天
/chats/{id}
特定聊天。
Chat.ReadBasic, Chat.Read, Chat.ReadWrite 不支持。 ChatSettings.Read.对话助手,ChatSettings.ReadWrite。对话助手,对话助手。管理。对话助手,对话助手。ReadBasic.All,对话助手。Read.All,对话助手。ReadWrite.All
聊天
/appCatalogs/teamsApps/{id}/installedToChats
安装了特定 Teams 应用的组织中的所有聊天。
不支持。 不支持。 对话助手。ReadBasic.WhereInstalled,对话助手。Read.WhereInstalled,对话助手。ReadWrite.WhereInstalled
聊天
/users/{id}/chats
特定用户所属的所有聊天。
Chat.ReadBasic, Chat.Read, Chat.ReadWrite 不支持。 Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
chatMessage
/teams/{id}/channels/{id}/messages
特定频道中的所有消息和答复。
ChannelMessage.Read.All、Group.Read.All、Group.ReadWrite.All 不支持。 ChannelMessage.Read.Group、ChannelMessage.Read.All
chatMessage
/teams/getAllMessages
组织中的所有频道消息。
不支持。 不支持。 ChannelMessage.Read.All
chatMessage
/chats/{id}/messages
聊天中的所有消息。
Chat.Read、Chat.ReadWrite 不支持。 Chat.Read.All
chatMessage
/chats/getAllMessages
组织中的所有聊天消息。
不支持。 不支持。 Chat.Read.All
chatMessage
/users/{id}/chats/getAllMessages
特定用户所属的所有聊天的对话助手消息。
Chat.Read、Chat.ReadWrite 不支持。 Chat.Read.All、Chat.ReadWrite.All
chatMessage
/appCatalogs/teamsApps/{id}/installedToChats/getAllMessages
安装了特定 Teams 应用的组织中所有聊天的对话助手消息。
不支持。 不支持。 对话助手。Read.WhereInstalled,对话助手。ReadWrite.WhereInstalled
联系人 Contacts.Read Contacts.Read Contacts.Read
conversationMember
/chats/getAllMembers
组织中所有聊天的成员。
不支持。 不支持。 ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All.
conversationMember
/chats/{id}/members
特定聊天的成员。
ChatMember.Read, ChatMember.ReadWrite, Chat.ReadBasic, Chat.Read, Chat.ReadWrite 不支持。 ChatMember.Read.Chat、Chat.Manage.Chat、ChatMember.Read.All、ChatMember.ReadWrite.All、Chat.ReadBasic.All、Chat.Read.All、Chat.ReadWrite.All
conversationMember
/appCatalogs/teamsApps/{id}/installedToChats/getAllMembers
对话助手,适用于安装特定 Teams 应用的组织中所有聊天的成员。
不支持。 不支持。 ChatMember.Read.WhereInstalled、ChatMember.ReadWrite.WhereInstalled、对话助手。ReadBasic.WhereInstalled,对话助手。Read.WhereInstalled,对话助手。ReadWrite.WhereInstalled
conversationMember
/teams/getAllMembers
组织中所有团队的成员。
不支持。 不支持。 TeamMember.Read.All, TeamMember.ReadWrite.All
conversationMember
/teams/{id}/members
特定团队中的成员。
TeamMember.Read.All 不支持。 TeamMember.Read.All
conversationMember
/teams/{id}/channels/getAllMembers
特定团队的所有专用频道中的成员。
不支持。 不支持。 ChannelMember.Read.All
conversationMember
/teams/getAllChannels/getAllMembers
不支持。 不支持。 ChannelMember.Read.All
driveItem(用户的个人 OneDrive) 不支持。 Files.ReadWrite 不支持。
driveItem (OneDrive 工作或学校) Files.ReadWrite.All 不支持。 Files.ReadWrite.All
事件 Calendars.Read Calendars.Read Calendars.Read
组 Group.Read.All 不支持。 Group.Read.All
组对话 Group.Read.All 不支持。 不支持。
Microsoft Entra 运行状况监视警报
/reports/healthmonitoring/alerts
HealthMonitoringAlertConfig.ReadWrite.All 不支持。 HealthMonitoringAlertConfig.ReadWrite.All
列表 Sites.ReadWrite.All 不支持。 Sites.ReadWrite.All
邮件 Mail.ReadBasic、Mail.Read Mail.ReadBasic、Mail.Read Mail.Read
offerShiftRequest
/teams/{id}/schedule/offerShiftRequests
对团队中的任何优惠班次请求的更改。
Schedule.Read.All、Schedule.ReadWrite.All 不支持。 Schedule.Read.All、Schedule.ReadWrite.All
联机会议 不支持。 不支持。 OnlineMeetings.Read.All、OnlineMeetings.ReadWrite.All
openShiftChangeRequest
/teams/{id}/schedule/openShiftChangeRequests
对团队中任何未完成班次请求的更改。
Schedule.Read.All、Schedule.ReadWrite.All 不支持。 Schedule.Read.All、Schedule.ReadWrite.All
状态 Presence.Read.All 不支持。 不支持。
打印机 不支持。 不支持。 打印机。阅读.All,Printer.ReadWrite.All
printTaskDefinition 不支持。 不支持。 PrintTaskDefinition.ReadWrite.All
安全警报 SecurityEvents.ReadWrite.All 不支持。 SecurityEvents.ReadWrite.All
shift
/teams/{id}/schedule/shifts
对团队中任何班次的更改。
Schedule.Read.All、Schedule.ReadWrite.All 不支持。 Schedule.Read.All、Schedule.ReadWrite.All
swapShiftsChangeRequest
/teams/{id}/schedule/swapShiftsChangeRequests
对团队中的任何交换班次请求的更改。
Schedule.Read.All、Schedule.ReadWrite.All 不支持。 Schedule.Read.All、Schedule.ReadWrite.All
团队
/teams
组织中的所有团队。
不支持。 不支持。 Team.ReadBasic.All,TeamSettings.Read.All
团队
/teams/{id}
特定团队。
Team.ReadBasic.All,TeamSettings.Read.All 不支持。 Team.ReadBasic.All,TeamSettings.Read.All
timeOffRequest
/teams/{id}/schedule/timeOffRequests
对团队中任何休假请求的更改。
Schedule.Read.All、Schedule.ReadWrite.All 不支持。 Schedule.Read.All、Schedule.ReadWrite.All
todoTask Tasks.ReadWrite Tasks.ReadWrite 不支持。
user User.Read.All User.Read.All User.Read.All
virtualEventWebinar VirtualEvent.Read 不支持。 VirtualEvent.Read.All
baseTask (已弃用) Tasks.ReadWrite Tasks.ReadWrite 不支持。

注意

以下权限使用 特定于资源的同意:

  • OnlineMeetingRecording.Read.对话助手
  • OnlineMeetingTranscript.Read.对话助手
  • ChatSettings.Read.Chat
  • ChatSettings.ReadWrite.Chat
  • Chat.Manage.Chat
  • ChannelMessage.Read.Group
  • ChatMember.Read.Chat
  • AiEnterpriseInteraction.Read.User

chatMessage

可以指定 chatMessage 订阅来包含资源数据 (includeResourceData 设置为 true) 。 在这种情况下,需要加密,如果未为此类订阅指定 encryptionCertificate ,则订阅创建将失败。

使用 Prefer: include-unknown-enum-members 请求标头获取 chatMessagemessageType可演变枚举中的以下值: systemEventMessage for /teams/{id}/channels/{id}/messages 和 /chats/{id}/messages resource。

conversationMember

可以指定 conversationMember 订阅来包括资源数据 (将 includeResourceData 设置为 true) 。 在这种情况下,需要加密,如果未为此类订阅指定 encryptionCertificate ,则订阅创建将失败。

团队、频道和聊天

可以指定团队、频道和聊天订阅来包括资源数据 (includeResourceData 设置为 true) 。 在这种情况下,需要加密,如果未为此类订阅指定 encryptionCertificate ,则订阅创建将失败。

订阅特定聊天中或用户级别的更改时,可以使用 notifyOnUserSpecificProperties 查询字符串参数。 在创建订阅期间将查询字符串参数 notifyOnUserSpecificPropertiestrue 设置为时,将向订阅者发送两种类型的有效负载。 一种类型包含用户特定的属性,而另一种类型则不包含这些属性。 有关详细信息,请参阅使用 Microsoft Graph 获取聊天的更改通知。

aiInsights

订阅 Copilot AI 见解需要有效的 Copilot 许可证,其中包括以下 Copilot 服务计划:

  • 智能 Microsoft 365 Copilot 副驾驶® 对话助手: 3f30311c-6b1e-48a4-ab79-725b469da960

aiInteraction

订阅 Copilot AI 交互需要有效的 Copilot 许可证,其中包括以下 Copilot 服务计划:

  • 智能 Microsoft 365 Copilot 副驾驶® 对话助手: 3f30311c-6b1e-48a4-ab79-725b469da960

对于面向特定用户所属的 Copilot AI 交互的订阅,资源路径中的用户必须以有效状态分配给他们的以前的服务计划。

对于面向整个租户的 Copilot AI 交互的订阅,租户必须预配了包括所有以前的 Copilot 服务计划在内的有效许可证。

driveItem

更多限制适用于 OneDrive 项的订阅。 这些限制适用于订阅的创建和管理(获取、更新和删除)。

在个人 OneDrive 上,可订阅根文件夹或该驱动器中的任何子文件夹。 在 OneDrive 工作或学校中,只能订阅根文件夹。 将针对订阅文件夹或其层次结构中的任何文件、文件夹或其他 driveItem 实例上请求的更改发送更改通知。 不能订阅非文件夹的 驱动器 或 driveItem 实例,例如单个文件。

联系人、事件和消息

可以订阅 Outlook 联系人、 事件或 消息 资源中的更改,并可选择在 POST 请求有效负载中指定是否在通知中包含加密资源数据。

创建和管理(获取、更新和删除)订阅需要资源的读取范围。 例如,若要获取有关邮件的更改通知,应用需要 Mail.Read 权限。 Outlook 更改通知支持委派和应用程序权限范围。 请注意以下限制:

  • 委托的权限仅支持订阅已登录用户的邮箱内文件夹中的项。 例如,不能使用委派权限 Calendars.Read 来订阅其他用户邮箱中的事件。

  • 订阅共享或委托文件夹中 Outlook 联系人、事件或邮件的更改通知:

    • 使用相应的应用程序权限订阅租户内任何用户的文件夹或邮箱中项目的更改。
    • 请勿 (Contacts.Read.Shared、Calendars.Read.Shared、Mail.Read.Shared 及其对应的读/写权限) 使用 Outlook 共享权限,因为它们 不 支持订阅共享或委派文件夹中项目的更改通知。

onlineMeetings, 状态

onlineMeetings 和 状态 订阅要求对包含资源数据的通知进行加密。 如果未指定 encryptionCertificate 和 encryptionCertificateId (如果通知中需要资源数据),则订阅创建失败。 有关更多信息,请参阅:

virtualEventWebinar

虚拟事件的订阅仅支持基本通知,并且仅限于虚拟事件的几个实体。 有关受支持的订阅类型的详细信息,请参阅获取 Microsoft Teams 虚拟事件更新的更改通知。

HTTP 请求

PATCH /subscriptions/{id}

请求标头

名称 类型 说明
Authorization string 持有者 {token}。 必填。 详细了解 身份验证和授权。

请求正文

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

下表指定可更新的属性。

请求正文必须包含 expirationDateTime OR notificationUrl 属性及其值。

名称 类型 说明
expirationDateTime DateTimeOffset 指定订阅到期的日期和时间(以 UTC 为单位)。 对于支持的最大订阅,时间长度因资源而异。 有关详细信息,请参阅 订阅生存期。
notificationUrl String 该 URL 必须使用 HTTPS 协议。 当 Microsoft Graph 发送更改通知时,notificationUrl 属性中包含的任何查询字符串参数都包含在 HTTP POST 请求中。

响应

如果成功,此方法在响应正文中返回 200 OK 响应代码和 subscription 对象。

注意

一个 404 Not Found 响应指示订阅不再存在。 例如,它已过期并被服务删除,或者已删除。 在此状态下无法续订订阅,因此重试更新始终失败。 要避免错过更改通知,请 创建新订阅 ,而不是重试更新。 要减少这种情况发生的频率,请在订阅到期前续订订阅,并使用 生命周期通知 主动续订订阅。

要详细了解错误返回方式,请参阅错误响应。

示例

请求

以下示例显示了一个请求。

PATCH https://graph.microsoft.com/beta/subscriptions/{id}
Content-type: application/json

{
   "expirationDateTime":"2016-11-22T18:23:45.9356913Z"
}

响应

以下示例显示了相应的响应。

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

{
  "id":"7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
  "resource":"me/messages",
  "applicationId": "24d3b144-21ae-4080-943f-7067b395b913",
  "changeType":"created,updated",
  "clientState":"secretClientValue",
  "notificationUrl":"https://webhook.azurewebsites.net/api/send/myNotifyClient",
  "lifecycleNotificationUrl":"https://webhook.azurewebsites.net/api/send/lifecycleNotifications",
  "expirationDateTime":"2016-11-22T18:23:45.9356913Z",
  "creatorId": "8ee44408-0679-472c-bc2a-692812af3437",
  "latestSupportedTlsVersion": "v1_2",
  "encryptionCertificate": "",
  "encryptionCertificateId": "",
  "includeResourceData": false,
  "notificationContentType": "application/json"
}