设置资源数据更改的通知

  • 项目

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

为什么会收到更改通知？

更改通知遵循事件驱动模型，客户在发生更改时接收警报，而不是轮询 Microsoft Graph。 更改通知适用于以下情况，具体取决于业务逻辑：

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

更改通知的类型

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

  • 基本通知：更改不包含已更改的资源 ID 以外的资源数据的通知。 当应用收到基本通知时，服务可以使用 ID 查询更改的对象。
  • 丰富通知：更改通知，包括已更改的对象的资源数据。 有关丰富通知的详细信息，请参阅 丰富通知。
  • 生命周期通知：当客户由于订阅的生命周期而面临丢失更改通知的风险时发出警报的通知。 有关生命周期通知的详细信息，请参阅 生命周期通知。

接收更改通知

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

管理订阅

客户端可以创建订阅、续订订阅和删除订阅。 当订阅处于活动状态且订阅的资源发生更改时，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 for Business 上的 driveItem 对 根文件夹层次结构中内容的更改： /drives/{id}/root 、 /users/{id}/drive/root -
组 对所有组的更改： /groups

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

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

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

    Azure AD B2C 租户不支持。

    注意： 组的创建和软删除也会触发 updatedchangeType。
    		•
    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 callRecord 更改 所有 呼叫记录： /communications/callRecords 最大订阅配额：
  • 每个组织：总共 100 个订阅。

    注意： 创建呼叫记录也会触发 updatedchangeType。
    		•
    Teams callRecording 组织中的所有录制内容： communications/onlineMeetings/getAllRecordings

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

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

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

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

    在由特定用户组织的会议中可用的通话记录： users/{id}/onlineMeetings/getAllTranscripts

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

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

    对安装了特定 Teams 应用的组织中所有聊天的更改： /appCatalogs/teamsApps/{id}/installedToChats    		 最大订阅配额：
  • 每个应用和聊天组合：1 个订阅。
  • 每个组织：总共 10,000 个订阅。
    		•
    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/?$filter=JoinWebUrl eq {joinWebUrl}
    Teams 状态 对单个用户状态的更改： /communications/presences/{id}

    对多个用户状态的更改： /communications/presences?$filter=id in ({id},{id}...)
    Teams 团队 对租户中任何团队的更改： /teams

    对特定团队的更改： /teams/{id}    		 最大订阅配额：
  • 每个应用和团队组合：1 个订阅。
  • 每个组织：总共 10,000 个订阅。
    		•
    todoTask 对特定任务列表中所有任务的更改： /me/todo/lists/{todoTaskListId}/tasks -
    user 对所有用户的更改： /users

    对特定用户的更改： /users/{id}    		 最大订阅配额：
  • 每个应用 (所有租户的总) ：50,000 个订阅总数。
  • 每个租户（适用于所有组合的应用）：总计 1000 个所有应用订阅
  • 每个应用和租户组合：总共 100 个订阅。

    个人 Microsoft 帐户（如 outlook.com）不受支持。

    Azure AD B2C 租户不支持。

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

    注意

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

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

    订阅生命周期

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

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

    Resource 最大过期时间
    安全警报 30 天内 (43,200 分钟)
    Teams callRecord 4,230 分钟 (不到 3 天)
    Teams callRecording 4,320 分钟 (3 天)
    Teams callTranscript 4,320 分钟 (3 天)
    Teams 频道 4,320 分钟 (3 天)
    Teams 聊天 4,320 分钟 (3 天)
    Teams chatMessage 4,320 分钟 (3 天)
    Teams conversationMember 4,320 分钟 (3 天)
    Teams onlineMeeting 4,320 分钟 (3 天)
    Teams 团队 4,320 分钟 (3 天)
    组对话 4,230 分钟 (不到 3 天)
    OneDrive driveItem 42,300 分钟 (不到 30 天)
    SharePoint 列表 42,300 分钟 (不到 30 天)
    Outlook 邮件、事件、联系人 4,230 分钟 (不到 3 天)
    用户、组、其他目录资源 29 天内 (41,760 分钟)
    onlineMeeting 4,230 分钟 (不到 3 天)
    状态 60 分钟（1 小时）
    打印 打印机 4,230 分钟 (不到 3 天)
    打印 printTaskDefinition 4,230 分钟 (不到 3 天)
    todoTask 4,230 分钟 (不到 3 天)

    此资源的 Webhook 仅在全局终结点中可用，而不能在国家云中使用。
    baseTask (已弃用) 4,230 分钟 (不到 3 天)

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

    延迟

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

    资源 平均延迟 最大延迟
    警报1 少于 3 分钟 5 分钟
    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 分钟
    onlineMeeting 少于 10 秒 1 分钟
    状态 少于 10 秒 1 分钟
    打印机 小于 1 分钟 5 分钟
    printTaskDefinition 小于 1 分钟 5 分钟
    团队 少于 10 秒 60 分钟
    todoTask 少于 2 分钟 15 分钟
    用户 少于 2 分钟 15 分钟

    1 为 警报 资源提供的延迟仅在创建警报后适用。 它不包括规则根据数据创建警报所需的时间。

    代码示例

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

    相关内容