使用 Microsoft Graph API 获取更改通知

命名空间:microsoft.graph

重要

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

警告

应更新将此功能与 baseTaskbaseTaskList 配合使用的现有应用,因为自 2022 年 5 月 31 日起,基于这些资源构建的待办事项 API 集已弃用。 该 API 集将于 2022 年 8 月 31 日停止返回数据。 请使用基于 todoTask 构建的 API 集。

Microsoft Graph REST API 可以通过各种终结点(包括 Webhook、事件中心和事件网格)将更改通知传递到客户端。 若要了解如何订阅和接收应用程序的通知,请参阅 设置用户数据更改通知

应用可以订阅表中所列 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 个订阅。
  • Teams callRecording 组织中的所有录制内容: communications/onlineMeetings/getAllRecordings

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

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

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

    在由特定用户组织的会议中可用的通话记录: users/{id}/onlineMeetings/getAllTranscripts
    最大订阅配额:
  • 每个应用和联机会议组合: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 -
    用户 对所有用户的更改: /users

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

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

    Azure AD B2C 租户不支持。

    注意: 创建和软删除用户也会触发 updatedchangeType
  • 注意: 许多资源对可针对该资源进行的订阅数有限制或配额。 超过该限制时,尝试创建订阅将导致 403 Forbidden 错误响应。 错误响应 的消息 属性将解释已超出的限制。

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

    注意:以 /users/{id} 开头的任何资源路径还可接受 /me 以引用已登录的用户。

    权限

    通常订阅操作需要拥有对资源的读取权限。 例如,若要获取邮件通知,应用需要 Mail.Read 权限。 创建订阅一文列出了各个资源类型所需的权限。 下表列出了将 webhook 用于特定资源类型时应用可以请求的权限类型。

    权限类型 支持的资源类型
    委派 - 工作或学校帐户 alertcallRecordingcallTranscriptchannelchatcontactconversation, conversationMemberdriveItemlisteventgroupmessageuserpresencechatMessage (preview) , teamtodoTaskbaseTask (已弃用)
    委派 - 个人 Microsoft 帐户 baseTask (已弃用) 、 联系人driveItemlist事件消息todoTask
    应用程序 alertcallRecordingcallTranscriptchannelchatcontactdriveItemlisteventgroupmessageusercallRecordchatMessageconversationMemberonlineMeetingprinterprintTaskDefinitionteam