设置资源数据更改的通知

更改通知使应用程序能够在感兴趣的 Microsoft Graph 资源发生更改时接收警报;也即创建、更新或删除。 Microsoft Graph 将通知发送到指定的客户端终结点,客户端服务根据业务需求处理通知。 例如,服务可能会提取更多数据、更新其缓存和视图等。

重要

外部租户和 Azure AD B2C 租户中的 Microsoft Entra 外部 ID 不支持更改通知功能。

为什么会收到更改通知?

更改通知遵循事件驱动模型,在该模型中,客户在发生更改时收到警报,而不是轮询 Microsoft Graph。 根据业务逻辑,更改通知适用于以下情况:

  • 你正在订阅频繁更改的资源。
  • 你需要近乎实时地对更改做出反应。
  • 你希望避免经常轮询 Microsoft Graph,这可能会导致达到限制。

下图显示了更改通知的工作原理以及与 更改跟踪的比较。

更改通知和增量查询服务的插图

以下视频概述了 Microsoft Graph 中的更改通知。

更改通知的类型

Microsoft Graph 支持三种类型的更改通知:

  • 基本通知:更改通知不包含除已更改资源的 ID 以外的资源数据。 当应用收到基本通知时,服务可以使用该 ID 查询更改的对象。
  • 丰富通知:包含已更改对象的资源数据的更改通知。 有关丰富通知的详细信息,请参阅 丰富通知。
  • 生命周期通知:当客户因订阅生命周期而面临错过更改通知的风险时提醒客户的通知。 有关生命周期通知的详细信息,请参阅 生命周期通知。

接收更改通知

Microsoft Graph 可以通过以下渠道向客户端传递更改通知。

管理订阅

客户端可以创建订阅、续订订阅和删除订阅。 当订阅处于活动状态并且订阅资源中发生更改时,Microsoft Graph 会向指定的通知终结点发送更改通知。

使用 订阅资源类型 及其相关方法管理订阅。 Microsoft Graph 在 changeNotificationCollection 资源类型中定义的结构中发送更改通知。

支持的资源

应用可以订阅对表中列出的 Microsoft Graph 资源所做的更改。 标有星号 () * 的资源订阅仅在终结点上 /beta 可用。

注意

对于 Microsoft Teams 资源, 每个组织总订阅数为 10,000 个的限制 将在租户中的所有 Teams 更改通知订阅 中累积共享。 它包括为不同 Teams 资源创建的订阅,例如聊天、聊天消息、通话记录、通话录音、频道、团队和对话成员, 所有这些都计入同一组织配额。 当活动 Teams 订阅的总数达到此限制时, Teams 资源的任何其他订阅创建请求都将失败 并 403 Forbidden 显示错误。

资源 支持的资源路径 限制
云打印 打印机 当打印作业可供下载时发生的更改 (jobFetchable 事件) : /print/printers/{id}/jobs -
云打印 printTaskDefinition 当队列中有有效作业时的更改 (jobStarted 事件) : /print/printtaskdefinition/{id}/tasks -
Copilot aiInsights Copilot AI 对特定用户参与的会议的见解: /copilot/users/{userId}/onlineMeetings/getAllAiInsights

特定会议的 Copilot AI 见解: /copilot/users/{userId}/onlineMeetings/{onlineMeetingId}/aiInsights
用户在所有会议中获得 AI 见解的最大订阅配额:
  • 每个应用和用户组合:1
  • 每个用户 (委派的) :10
  • 每个组织:总计 10,000 个订阅。


特定会议的 AI 见解的最大订阅配额:
  • 每个应用和用户 + 会议组合:1
  • 每个用户和会议组合 (委派的) :1
  • 每个组织:总计 10,000 个订阅 (共享)
Copilot aiInteraction 特定用户参与的 Copilot AI 交互: copilot/users/{userId}/interactionHistory/getAllEnterpriseInteractions

组织中的 Copilot AI 交互: copilot/interactionHistory/getAllEnterpriseInteractions
最大订阅配额:
  • 跨租户跟踪 AI 交互的订阅的每个应用和租户组合 () :1
  • 针对订阅的每个应用和用户组合 (跟踪特定用户所属的 AI 交互) :1
  • 订阅的每个用户 (跟踪 AI 交互 特定用户属于) :10 个订阅。
  • 每个组织:总计 10,000 个订阅。
OneDrive(个人版)上的 driveItem 对 任何文件夹的层次结构中的内容的更改: /users/{id}/drive/root -
工作或学校 OneDrive 上的 driveItem 对根文件夹层次结构中内容的更改: /drives/{id}/root ,/users/{id}/drive/root -
组 对所有组的更改: /groups

对特定组的更改: /groups/{id}

对特定组所有者的更改: /groups/{id}/owners

对特定组成员的更改: /groups/{id}/members
最大订阅配额:
  • 所有租户的每个应用 (总) :总订阅 50,000 个。
  • 所有应用程序的每个租户 (总) :所有应用的总订阅数为 1,000 个。
  • 每个应用和租户组合:总共 100 个订阅。


Azure AD B2C 租户不支持。

注意: 组的创建和软删除也会触发 updatedchangeType。
Microsoft Entra 运行状况监视警报 所有运行状况监视警报的更改: /reports/healthmonitoring/alerts

对特定类型警报的更改: /reports/healthmonitoring/alert 将 notificationQueryOptions 请求有效负载中的属性设置为 $filter=alertType eq '{alertType}'
-
SharePoint 网站下的列表 对列表中内容的更改:/sites/{site-id}/lists/{list-id} -
Microsoft 365 组对话 组对话的更改: groups/{id}/conversations -
Outlook 邮件 更改用户邮箱中的所有邮件: /users/{id}/messages , /me/messages

用户收件箱中的邮件更改: /users/{id}/mailFolders('inbox')/messages , /me/mailFolders('inbox')/messages
对于所有应用程序,允许每个邮箱最多有 1,000 个活动订阅。
Outlook 事件 更改用户邮箱中的所有事件: /users/{id}/events , /me/events 对于所有应用程序,允许每个邮箱最多有 1,000 个活动订阅。
Outlook 个人联系人 更改用户邮箱中的所有个人联系人: /users/{id}/contacts , /me/contacts 对于所有应用程序,允许每个邮箱最多有 1,000 个活动订阅。
安全警报 对特定警报的更改: /security/alerts/{id}

对筛选警报的更改: /security/alerts/?$filter={parameters}
有关详细信息,请参阅 安全性 API 警报。
Teams 审批 对租户中所有审批的更改: /solutions/approval/approvalItems 最大订阅配额:
  • 每个租户(适用于所有组合的应用):总计 1000 个所有应用订阅
  • 每个应用和租户组合:1 个订阅。
Teams callRecord 更改 所有 呼叫记录: /communications/callRecords

对筛选的呼叫记录的更改: /communications/callRecords?$filter={parameters}
有关详细信息,请参阅 更改通话记录的通知。

最大订阅配额:
  • 每个组织:总计 100 个订阅。


注意: 通话记录的创建也会触发 updatedchangeType。
Teams callRecording 组织中的所有录制内容: communications/onlineMeetings/getAllRecordings

特定会议的所有录制内容: communications/onlineMeetings/{onlineMeetingId}/recordings

在特定用户组织的会议中可用的通话录音: users/{id}/onlineMeetings/getAllRecordings

在安装了特定 Teams 应用的会议中变为可用的通话录制: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings *
最大订阅配额:
  • 每个应用和联机会议组合:1
  • 每个应用和用户组合:1
  • 每个用户 (订阅跟踪用户组织的所有 onlineMeetings 中的录制内容) :10 个订阅。
  • 每个组织:总计 10,000 个订阅。
Teams callTranscript 组织中的所有脚本: communications/onlineMeetings/getAllTranscripts

特定会议的所有脚本: communications/onlineMeetings/{onlineMeetingId}/transcripts

在特定用户组织的会议中变为可用的通话脚本: users/{id}/onlineMeetings/getAllTranscripts

在安装了特定 Teams 应用的会议中变为可用的通话脚本: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTrancripts *
最大订阅配额:
  • 每个应用和联机会议组合:1
  • 每个应用和用户组合:1
  • 每个用户 (订阅跟踪用户组织的所有 onlineMeetings 中的脚本) :10 个订阅。
  • 每个组织:总计 10,000 个订阅。
Teams 聊天 对租户中任何聊天的更改: /chats

对特定聊天的更改: /chats/{id}

使用 notifyOnUserSpecificProperties 查询参数对特定聊天进行的更改: /chats/{id}?notifyOnUserSpecificProperties={Boolean}

对安装了特定 Teams 应用的组织中的所有聊天的更改: /appCatalogs/teamsApps/{id}/installedToChats

对特定用户所属的所有聊天的更改: /users/{id}/chats

使用 notifyOnUserSpecificProperties 查询参数对特定用户所属的所有聊天进行更改: /users/{id}/chats?notifyOnUserSpecificProperties={Boolean}
最大订阅配额:
  • 每个应用和聊天组合:1 个订阅。
  • 每个组织:总计 10,000 个订阅。
  • 订阅的每个用户 (跟踪特定用户所属的所有聊天) :10 个订阅。
Teams chatMessage 对所有团队所有频道中的聊天消息的更改: /teams/getAllMessages

特定频道中的聊天消息更改: /teams/{id}/channels/{id}/messages

所有聊天中的聊天消息更改: /chats/getAllMessages

特定聊天中的聊天消息更改: /chats/{id}/messages

特定用户参与的所有聊天中的聊天消息更改: /users/{id}/chats/getAllMessages

对安装了特定 Teams 应用的组织中所有聊天的聊天消息的更改: /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages
最大订阅配额:
  • 每个应用和频道或聊天组合:1 个订阅。
  • 每个用户 (订阅跟踪用户所属所有聊天中的聊天消息) :10 个订阅。
  • 每个组织:总计 10,000 个订阅。
Teams 频道 对所有团队中的频道的更改: /teams/getAllChannels

对特定团队中的频道的更改: /teams/{id}/channels
最大订阅配额:
  • 每个应用和团队组合:1 个订阅。
  • 每个组织:总计 10,000 个订阅。
Teams conversationMember 对特定团队成员身份的更改: /teams/{id}/members

对特定团队下所有频道成员资格的更改: teams/{id}/channels/getAllMembers

特定聊天中成员身份的更改: /chats/{id}/members

对安装了特定 Teams 应用的组织中所有聊天的成员身份的更改: /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers

更改所有聊天中的成员身份: /chats/getAllMembers
最大订阅配额:
  • 每个应用和团队组合:1 个订阅。
  • 每个组织:总计 10,000 个订阅。
Teams onlineMeeting* 对联机会议的更改: /communications/onlineMeetings(joinWebUrl='{encodedJoinWebUrl}')/meetingCallEvents 不支持用于 $select 仅返回所选属性。 丰富通知包含已更改实例的所有属性。 每个联机会议每个应用程序允许一个订阅。 有关详细信息,请参阅获取 Microsoft Teams 会议呼叫事件更新的更改通知。
Teams 状态 对单个用户状态的更改: /communications/presences/{id}

更改多个用户的状态: /communications/presences?$filter=id in ({id},{id}...)
多个用户状态的订阅限制为 650 个不同的用户。 不支持用于 $select 仅返回所选属性。 丰富通知包含已更改实例的所有属性。 每个委派用户每个应用程序允许一个订阅。 有关详细信息,请参阅 获取 Microsoft Teams 中状态更新的更改通知。
Teams 团队 对租户中任何团队的更改: /teams

对特定团队的更改: /teams/{id}
最大订阅配额:
  • 每个应用和团队组合:1 个订阅。
  • 每个组织:总计 10,000 个订阅。
Teams 排班 offerShiftRequest 对团队中任何优惠班次请求的更改: /teams/{id}/schedule/offerShiftRequests 最大订阅配额:
  • 每个应用和资源路径组合:每个租户 1 个订阅。
  • 每个资源路径和用户组合:每个租户 10 个委派用户订阅。
Teams 排班 openShiftChangeRequest 对团队中的任何未完成班次请求的更改: /teams/{id}/schedule/openShiftChangeRequests 最大订阅配额:
  • 每个应用和资源路径组合:每个租户 1 个订阅。
  • 每个用户和资源路径组合:10 个订阅。
  • 每个组织:总计 10,000 个订阅。
Teams 排班 对团队中任何班次的更改: /teams/{id}/schedule/shifts 最大订阅配额:
  • 每个应用和资源路径组合:每个租户 1 个订阅。
  • 每个用户和资源路径组合:10 个订阅。
  • 每个组织:总计 10,000 个订阅。
Teams 排班 swapShiftsChangeRequest 对团队中的任何交换班次请求的更改: /teams/{id}/schedule/swapShiftsChangeRequests 最大订阅配额:
  • 每个应用和资源路径组合:每个租户 1 个订阅。
  • 每个用户和资源路径组合:10 个订阅。
  • 每个组织:总计 10,000 个订阅。
Teams 排班 timeOffRequest 对团队中任何休假请求的更改: /teams/{id}/schedule/timeOffRequests 最大订阅配额:
  • 每个应用和资源路径组合:每个租户 1 个订阅。
  • 每个用户和资源路径组合:10 个订阅。
  • 每个组织:总计 10,000 个订阅。
todoTask 对特定任务列表中所有任务的更改: /me/todo/lists/{todoTaskListId}/tasks -
user 对所有用户的更改: /users

对特定用户的更改: /users/{id}
最大订阅配额:
  • 所有租户的每个应用 (总) :总订阅 50,000 个。
  • 所有应用程序的每个租户 (总) :所有应用的总订阅数为 1,000 个
  • 每个应用和租户组合:总共 100 个订阅。


不支持个人Microsoft帐户(如 outlook.com)。

Azure AD B2C 租户不支持。

注意: 创建和软删除用户也会触发 updatedchangeType。

注意

许多资源对可针对该资源进行的订阅数有限制或配额。 超过该限制时,尝试创建订阅将导致 403 Forbidden 错误响应。 错误响应的 message 属性将解释已超出的限制。

其中一些资源支持丰富的通知 () 资源数据的通知。 有关其详细信息,请参阅 设置包含资源数据的更改通知。

订阅生命周期

订阅的生命周期有限。 应用需要在到期时间之前续订其订阅;否则,他们需要创建新的订阅。 应用还可以随时取消订阅,以停止接收更改通知。

下表显示了 Microsoft Graph 中每个资源的订阅的最大到期时间。

Resource 最大过期时间
Copilot aiInteraction 三天) (4,320 分钟
安全警报 43,200 分钟 (30 天以下)
Teams 审批 43,200 分钟 (30 天以下)
Teams callRecord 3 天) 内 (4,230 分钟
Teams callRecording 三天) (4,320 分钟
Teams callTranscript 三天) (4,320 分钟
Teams 频道 三天) (4,320 分钟
Teams 聊天 三天) (4,320 分钟
Teams chatMessage 三天) (4,320 分钟
Teams conversationMember 三天) (4,320 分钟
Teams onlineMeeting 三天) (4,320 分钟
Teams 团队 三天) (4,320 分钟
Teams teamsAppInstallation 3 天) (4,320 分钟
Teams 排班 offerShiftRequest 360 分钟 (6 小时)
Teams 排班 openShiftChangeRequest 360 分钟 (6 小时)
Teams 排班 360 分钟 (6 小时)
Teams 排班 swapShiftsChangeRequest 360 分钟 (6 小时)
Teams 排班 timeOffRequest 360 分钟 (6 小时)
组对话 3 天) 内 (4,230 分钟
OneDrive driveItem 30 天内 (42,300 分钟)
SharePoint 列表 30 天内 (42,300 分钟)
Outlook 邮件、事件、联系人 7 天内 (10,080 分钟)

对于包含资源数据 (丰富通知订阅) 的订阅,订阅生存期为 1440 分钟 (不到一天) 。
用户、组、其他目录资源 41,760 分钟 (29 天)
onlineMeeting 3 天) 内 (4,230 分钟
状态 60 分钟(1 小时)
打印 打印机 3 天) 内 (4,230 分钟
打印 printTaskDefinition 3 天) 内 (4,230 分钟
todoTask 3 天) 内 (4,230 分钟

此资源的 Webhook 仅在全球终结点中可用,在国家云中不可用。
Microsoft Entra 运行状况监视警报 30 天内 (42,300 分钟)
baseTask (已弃用) 3 天) 内 (4,230 分钟

注意:现有和新的应用都不得超过支持的这一上限值。 今后,任何超出最大值的订阅创建或续订请求都将失败。

延迟

下表列出了服务中发生的事件与传递更改通知之间的预计延迟时间。

资源 平均延迟 最大延迟
aiInteraction 少于 10 秒 60 分钟
警报1 少于 3 分钟 5 分钟
审批 少于 10 秒 40 秒
calendar 小于 1 分钟 3 分钟
callRecord2 不到 30 分钟 150 分钟
callRecording 少于 10 秒 240 分钟 3
callTranscript 少于 10 秒 240 分钟 3
频道 少于 10 秒 60 分钟
聊天 少于 10 秒 60 分钟
chatMessage 少于 10 秒 1 分钟
联系人 小于 1 分钟 3 分钟
对话 未知 未知
conversationMember 少于 10 秒 60 分钟
driveItem 小于 1 分钟 6 小时
事件 未知 未知
组 未知 未知
运行状况监视警报 未知 未知
列表 小于 1 分钟 6 小时
邮件 小于 1 分钟 3 分钟
offerShiftRequest 小于 1 分钟 60 分钟
onlineMeeting 少于 10 秒 1 分钟
openShiftChangeRequest 小于 1 分钟 60 分钟
状态 少于 10 秒 1 分钟
打印机 小于 1 分钟 5 分钟
printTaskDefinition 小于 1 分钟 5 分钟
shift 小于 1 分钟 60 分钟
swapShiftsChangeRequest 小于 1 分钟 60 分钟
团队 少于 10 秒 60 分钟
teamsAppInstallation 少于 10 秒 60 分钟
timeOffRequest 小于 1 分钟 60 分钟
todoTask 少于 2 分钟 15 分钟
用户 未知 未知

1 为 警报 资源提供的延迟仅在警报创建后适用。 它不包括规则根据数据创建警报所需的时间。
2 为 callRecord 资源提供的延迟仅适用于调用记录的第一个版本。 通话记录的后续版本可能会在超出规定的延迟时间之后更新。
3通话录制 和 通话脚本 的更改通知通常在录制和脚本生成后的 10 秒内发送,这可能会在通话结束后的几分钟内发送。

代码示例

可在 GitHub 上获取以下代码示例。