设置资源数据更改的通知
更改通知使应用程序能够在Microsoft Graph 资源对更改感兴趣时接收警报;即,已创建、更新或删除。 Microsoft Graph 会将通知发送到指定的客户端终结点,客户端服务将根据业务要求处理通知。 例如,服务可能会提取更多数据、更新其缓存和视图等。
为什么会收到更改通知?
更改通知遵循事件驱动模型,客户在发生更改时接收警报,而不是Microsoft Graph 轮询。 更改通知适用于以下情况,具体取决于业务逻辑:
- 你订阅了经常更改的资源。
- 你需要近乎实时地对更改做出反应。
- 你希望避免频繁轮询Microsoft Graph,这可能会使你达到限制。
更改通知的类型
Microsoft Graph 支持三种类型的更改通知:
- 基本通知:更改不包含已更改的资源 ID 以外的资源数据的通知。 当应用收到基本通知时,服务可以使用 ID 查询更改的对象。
- 丰富通知:更改通知,包括已更改的对象的资源数据。 有关丰富通知的详细信息,请参阅 丰富通知。
- 生命周期通知:当客户由于订阅的生命周期而面临丢失更改通知的风险时发出警报的通知。 有关生命周期通知的详细信息,请参阅 生命周期通知。
接收更改通知
Microsoft Graph 可以通过以下渠道向客户端传递更改通知。
- Webhook。 有关详细信息,请参阅 通过 Webhook 接收更改通知。
- Azure 事件中心。 有关详细信息,请参阅通过Azure 事件中心接收更改通知。
- Azure 事件网格 (预览) 。 有关详细信息,请参阅通过Azure 事件网格接收更改通知。
管理订阅
客户端可以创建订阅、续订订阅和删除订阅。 当订阅处于活动状态且订阅的资源发生更改时,Microsoft Graph 会将更改通知发送到指定的通知终结点。
使用订阅 资源类型 及其相关方法管理订阅。 Microsoft Graph 在 changeNotificationCollection 资源类型中定义的结构中发送更改通知。
支持的资源
应用可以订阅表中所列Microsoft Graph 资源的更改。
注意
对标有星号 () *
的资源的订阅仅在终结点上 /beta
可用。
资源 | 支持的资源路径 | 限制 |
---|---|---|
云打印 打印机 | 当打印作业准备好下载 (jobFetchable 事件) 时更改: /print/printers/{id}/jobs |
- |
云打印 printTaskDefinition | 当队列中存在有效作业时 (jobStarted 事件) 的更改: /print/printtaskdefinition/{id}/tasks |
- |
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 租户不支持。 注意: 组的创建和软删除也会触发 updated changeType。 |
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} |
有关详细信息,请参阅 呼叫记录的更改通知。 最大订阅配额: 注意: 创建呼叫记录也会触发 updated changeType。 |
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 Shifts offerShiftRequest | 对团队中任何产品/服务转移请求的更改: /teams/{id}/schedule/offerShiftRequests |
最大订阅配额: |
Teams Shifts openShiftChangeRequest | 对团队中任何打开的班次请求的更改: /teams/{id}/schedule/openShiftChangeRequests |
最大订阅配额: |
团队班 次班次 | 对团队中任何班次的更改: /teams/{id}/schedule/shifts |
最大订阅配额: |
Teams 班次 swapShiftsChangeRequest | 对团队中任何交换班次请求的更改: /teams/{id}/schedule/swapShiftsChangeRequests |
最大订阅配额: |
Teams Shifts timeOffRequest | 对团队中任何休假请求的更改: /teams/{id}/schedule/timeOffRequests |
最大订阅配额: |
todoTask | 对特定任务列表中所有任务的更改: /me/todo/lists/{todoTaskListId}/tasks |
- |
user | 对所有用户的更改: /users 对特定用户的更改: /users/{id} |
最大订阅配额: 个人Microsoft帐户(如 outlook.com)不受支持。 Azure AD B2C 租户不支持。 注意: 创建和软删除用户也会触发 updated changeType。 |
注意
许多资源对可针对该资源进行的订阅数有限制或配额。 超过该限制时,尝试创建订阅将导致 403 Forbidden
错误响应。 错误响应 的消息 属性将解释已超出的限制。
其中一些资源支持包含资源数据) 的丰富通知 (通知。 有关支持丰富通知的资源的详细信息,请参阅 设置包含资源数据的更改通知。
订阅生命周期
订阅的生命周期有限。 应用需要在过期时间之前续订其订阅;否则,他们需要创建新订阅。 应用还可以随时取消订阅,以停止接收更改通知。
下表显示了 Microsoft Graph 中每个资源订阅的最大过期时间。
Resource | 最大过期时间 |
---|---|
安全警报 | 30 天内 (43,200 分钟) |
Teams 审批 | 30 天内 (43,200 分钟) |
Teams callRecord | 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 | 4,320 分钟 (3 天) |
Teams Shifts offerShiftRequest | 360 分钟 (6 小时) |
Teams Shifts openShiftChangeRequest | 360 分钟 (6 小时) |
团队班 次班次 | 360 分钟 (6 小时) |
Teams 班次 swapShiftsChangeRequest | 360 分钟 (6 小时) |
Teams Shifts timeOffRequest | 360 分钟 (6 小时) |
组对话 | 4,230 分钟 (不到三天) |
OneDrive driveItem | 42,300 分钟 (不到 30 天) |
SharePoint 列表 | 42,300 分钟 (不到 30 天) |
Outlook 邮件、事件、联系人 | 7 天内 (10,080 分钟) |
用户、组、其他目录资源 | 29 天内 (41,760 分钟) |
onlineMeeting | 4,230 分钟 (不到三天) |
状态 | 60 分钟(1 小时) |
打印 打印机 | 4,230 分钟 (不到三天) |
打印 printTaskDefinition | 4,230 分钟 (不到三天) |
todoTask | 4,230 分钟 (不到三天) 此资源的 Webhook 仅在全局终结点中可用,而不能在国家云中使用。 |
baseTask (已弃用) | 4,230 分钟 (不到三天) |
注意:现有和新的应用都不得超过支持的这一上限值。 今后,任何超出最大值的订阅创建或续订请求都将失败。
延迟
下表列出了服务中发生的事件与传递更改通知之间的预计延迟时间。
资源 | 平均延迟 | 最大延迟 |
---|---|---|
警报1 | 少于 3 分钟 | 5 分钟 |
批准 | 少于 10 秒 | 40 秒 |
calendar | 小于 1 分钟 | 3 分钟 |
callRecord | 少于 15 分钟 | 60 分钟 |
callRecording | 少于 10 秒 | 60 分钟 |
callTranscript | 少于 10 秒 | 60 分钟 |
频道 | 少于 10 秒 | 60 分钟 |
聊天 | 少于 10 秒 | 60 分钟 |
chatMessage | 少于 10 秒 | 1 分钟 |
联系人 | 小于 1 分钟 | 3 分钟 |
对话 | 未知 | 未知 |
conversationMember | 少于 10 秒 | 60 分钟 |
driveItem | 小于 1 分钟 | 5 分钟 |
事件 | 未知 | 未知 |
组 | 未知 | 未知 |
列表 | 小于 1 分钟 | 5 分钟 |
邮件 | 小于 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 为 警报 资源提供的延迟仅在创建警报后适用。 它不包括规则根据数据创建警报所需的时间。
代码示例
可在 GitHub 上获取以下代码示例。
- Microsoft Graph 培训模块 - 在 Microsoft Graph 中使用变更通知和变更跟踪
- 面向 Node.js 的 Microsoft Graph Webhooks 示例
- 适用于 ASP.NET Core 的 Microsoft Graph Webhook 示例
- 面向 Java Spring 的 Microsoft Graph Webhooks 示例