更改通知使应用程序能够在感兴趣的 Microsoft Graph 资源发生更改时接收警报;也即创建、更新或删除。 Microsoft Graph 将通知发送到指定的客户端终结点,客户端服务根据业务需求处理通知。 例如,服务可能会提取更多数据、更新其缓存和视图等。
重要
外部租户和 Azure AD B2C 租户中的 Microsoft Entra 外部 ID 不支持更改通知功能。
为什么会收到更改通知?
更改通知遵循事件驱动模型,在该模型中,客户在发生更改时收到警报,而不是轮询 Microsoft Graph。 根据业务逻辑,更改通知适用于以下情况:
- 你正在订阅频繁更改的资源。
- 你需要近乎实时地对更改做出反应。
- 你希望避免经常轮询 Microsoft Graph,这可能会导致达到限制。
下图显示了更改通知的工作原理以及与 更改跟踪的比较。
以下视频概述了 Microsoft Graph 中的更改通知。
更改通知的类型
Microsoft Graph 支持三种类型的更改通知:
- 基本通知:更改通知不包含除已更改资源的 ID 以外的资源数据。 当应用收到基本通知时,服务可以使用该 ID 查询更改的对象。
- 丰富通知:包含已更改对象的资源数据的更改通知。 有关丰富通知的详细信息,请参阅 丰富通知。
- 生命周期通知:当客户因订阅生命周期而面临错过更改通知的风险时提醒客户的通知。 有关生命周期通知的详细信息,请参阅 生命周期通知。
接收更改通知
Microsoft Graph 可以通过以下渠道向客户端传递更改通知。
- Webhooks。 有关详细信息,请参阅 通过 Webhook 接收更改通知。
- Azure 事件中心。 有关详细信息,请参阅通过 Azure 事件中心接收更改通知。
- Azure 事件网格。 有关详细信息,请参阅通过 Azure 事件网格接收更改通知。
管理订阅
客户端可以创建订阅、续订订阅和删除订阅。 当订阅处于活动状态并且订阅资源中发生更改时,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 见解的最大订阅配额:
特定会议的 AI 见解的最大订阅配额:
|
| Copilot aiInteraction | 特定用户参与的 Copilot AI 交互: copilot/users/{userId}/interactionHistory/getAllEnterpriseInteractions 组织中的 Copilot AI 交互: copilot/interactionHistory/getAllEnterpriseInteractions |
最大订阅配额:
|
| OneDrive(个人版)上的 driveItem | 对 任何文件夹的层次结构中的内容的更改: /users/{id}/drive/root |
- |
| 工作或学校 OneDrive 上的 driveItem |
对根文件夹层次结构中内容的更改: /drives/{id}/root ,/users/{id}/drive/root |
- |
| 组 | 对所有组的更改: /groups 对特定组的更改: /groups/{id} 对特定组所有者的更改: /groups/{id}/owners 对特定组成员的更改: /groups/{id}/members |
最大订阅配额:
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 |
最大订阅配额:
|
| Teams callRecord | 更改 所有 呼叫记录: /communications/callRecords 对筛选的呼叫记录的更改: /communications/callRecords?$filter={parameters} |
有关详细信息,请参阅 更改通话记录的通知。 最大订阅配额:
注意: 通话记录的创建也会触发 updatedchangeType。 |
| Teams callRecording | 组织中的所有录制内容: communications/onlineMeetings/getAllRecordings 特定会议的所有录制内容: communications/onlineMeetings/{onlineMeetingId}/recordings 在特定用户组织的会议中可用的通话录音: users/{id}/onlineMeetings/getAllRecordings 在安装了特定 Teams 应用的会议中变为可用的通话录制: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings * |
最大订阅配额:
|
| Teams callTranscript | 组织中的所有脚本: communications/onlineMeetings/getAllTranscripts 特定会议的所有脚本: communications/onlineMeetings/{onlineMeetingId}/transcripts 在特定用户组织的会议中变为可用的通话脚本: users/{id}/onlineMeetings/getAllTranscripts 在安装了特定 Teams 应用的会议中变为可用的通话脚本: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTrancripts * |
最大订阅配额:
|
| Teams 聊天 | 对租户中任何聊天的更改: /chats 对特定聊天的更改: /chats/{id} 使用 notifyOnUserSpecificProperties 查询参数对特定聊天进行的更改: /chats/{id}?notifyOnUserSpecificProperties={Boolean} 对安装了特定 Teams 应用的组织中的所有聊天的更改: /appCatalogs/teamsApps/{id}/installedToChats 对特定用户所属的所有聊天的更改: /users/{id}/chats 使用 notifyOnUserSpecificProperties 查询参数对特定用户所属的所有聊天进行更改: /users/{id}/chats?notifyOnUserSpecificProperties={Boolean} |
最大订阅配额:
|
| Teams chatMessage | 对所有团队所有频道中的聊天消息的更改: /teams/getAllMessages 特定频道中的聊天消息更改: /teams/{id}/channels/{id}/messages 所有聊天中的聊天消息更改: /chats/getAllMessages 特定聊天中的聊天消息更改: /chats/{id}/messages 特定用户参与的所有聊天中的聊天消息更改: /users/{id}/chats/getAllMessages 对安装了特定 Teams 应用的组织中所有聊天的聊天消息的更改: /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages |
最大订阅配额:
|
| Teams 频道 | 对所有团队中的频道的更改: /teams/getAllChannels 对特定团队中的频道的更改: /teams/{id}/channels |
最大订阅配额:
|
| Teams conversationMember | 对特定团队成员身份的更改: /teams/{id}/members 对特定团队下所有频道成员资格的更改: teams/{id}/channels/getAllMembers 特定聊天中成员身份的更改: /chats/{id}/members 对安装了特定 Teams 应用的组织中所有聊天的成员身份的更改: /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers 更改所有聊天中的成员身份: /chats/getAllMembers |
最大订阅配额:
|
| 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} |
最大订阅配额:
|
| Teams 排班 offerShiftRequest | 对团队中任何优惠班次请求的更改: /teams/{id}/schedule/offerShiftRequests |
最大订阅配额:
|
| Teams 排班 openShiftChangeRequest | 对团队中的任何未完成班次请求的更改: /teams/{id}/schedule/openShiftChangeRequests |
最大订阅配额:
|
| Teams 排班 | 对团队中任何班次的更改: /teams/{id}/schedule/shifts |
最大订阅配额:
|
| Teams 排班 swapShiftsChangeRequest | 对团队中的任何交换班次请求的更改: /teams/{id}/schedule/swapShiftsChangeRequests |
最大订阅配额:
|
| Teams 排班 timeOffRequest | 对团队中任何休假请求的更改: /teams/{id}/schedule/timeOffRequests |
最大订阅配额:
|
| todoTask | 对特定任务列表中所有任务的更改: /me/todo/lists/{todoTaskListId}/tasks |
- |
| user | 对所有用户的更改: /users 对特定用户的更改: /users/{id} |
最大订阅配额:
不支持个人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 上获取以下代码示例。
- Microsoft Graph 培训模块 - 在 Microsoft Graph 中使用变更通知和变更跟踪
- 面向 Node.js 的 Microsoft Graph Webhooks 示例
- 适用于 ASP.NET Core 的 Microsoft Graph Webhook 示例
- 面向 Java Spring 的 Microsoft Graph Webhooks 示例