创建订阅

命名空间:microsoft.graph

重要

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

订阅侦听器应用程序,以在 Microsoft Graph 中指定资源发生的更改属于请求的更改类型时接收更改通知。

要确定可以为其创建订阅的资源和订阅限制,请参阅设置 资源数据更改通知:支持的资源。

某些资源支持丰富的通知,即包含资源数据的通知。 有关这些资源的详细信息,请参阅 设置包含资源数据的更改通知:支持的资源。

此 API 可用于以下国家级云部署。

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国
✅ ✅ ✅ ✅

权限

创建订阅需要对资源具有读取权限。 例如,若要获取有关消息的更改通知,应用需要 Mail.Read 权限。

根据请求的资源和权限类型(委托或应用程序),下表中指定的权限为调用此 API 所需的最小权限。 要了解详细信息,包括在选择权限之前的 注意事项,可在 权限 中搜索以下权限。

注意

  • 由于安全限制,仅需要读取访问权限时,Microsoft Graph 订阅不支持写入访问权限。
  • 某些资源支持多种方案中的更改通知,每种方案可能需要不同的权限。 在这些情况下,请使用资源路径来区分方案。
支持的资源 委派(工作或学校帐户) 委派(个人 Microsoft 帐户) 应用程序
aiInsights
/copilot/users/{userId}/onlineMeetings/getAllAiInsights
特定用户参与的会议中的 Copilot AI 见解。
OnlineMeetingAiInsight.Read.All 不支持。 OnlineMeetingAiInsight.Read.All
aiInsights
/copilot/users/{userId}/onlineMeetings/{onlineMeetingId}/aiInsights
特定会议的 Copilot AI 见解。
OnlineMeetingAiInsight.Read.All 不支持。 OnlineMeetingAiInsight.Read.All
aiInteraction
copilot/users/{userId}/interactionHistory/getAllEnterpriseInteractions
特定用户所属的 Copilot AI 交互。
AiEnterpriseInteraction.Read 不支持。 AiEnterpriseInteraction.Read.All、AiEnterpriseInteraction.Read.User
aiInteraction
copilot/interactionHistory/getAllEnterpriseInteractions
组织中的 Copilot AI 交互。
不支持。 不支持。 AiEnterpriseInteraction.Read.All
approvalItems 不支持。 不支持。 ApprovalSolution.ReadWrite.All
callRecord 不支持。 不支持。 CallRecords.Read.All
callRecording
communications/onlineMeetings/getAllRecordings
任何录制内容在租户中都可用。
不支持。 不支持。 OnlineMeetingRecording.Read.All
callRecording
communications/onlineMeetings/{onlineMeetingId}/recordings
任何录制内容都可用于特定会议。
OnlineMeetingRecording.Read.All 不支持。 OnlineMeetingRecording.Read.All
callRecording
users/{userId}/onlineMeetings/getAllRecordings
在特定用户组织的会议中变为可用的通话录制。
OnlineMeetingRecording.Read.All 不支持。 OnlineMeetingRecording.Read.All
callRecording
appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings
在安装了特定 Teams 应用的会议中变为可用的通话录制。
不支持。 不支持。 OnlineMeetingRecording.Read.All, OnlineMeetingRecording.Read.对话助手
callTranscript
communications/onlineMeetings/getAllTranscripts
任何脚本在租户中变为可用。
不支持。 不支持。 OnlineMeetingTranscript.Read.All
callTranscript
communications/onlineMeetings/{onlineMeetingId}/transcripts
任何脚本都可用于特定会议。
OnlineMeetingTranscript.Read.All 不支持。 OnlineMeetingTranscript.Read.All
callTranscript
users/{userId}/onlineMeetings/getAllTranscripts
在特定用户组织的会议中变为可用的通话脚本。
OnlineMeetingTranscript.Read.All 不支持。 OnlineMeetingTranscript.Read.All
callTranscript
appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTranscripts
在安装了特定 Teams 应用的会议中变为可用的通话脚本。
不支持。 不支持。 OnlineMeetingTranscript.Read.All、OnlineMeetingTranscript.Read.对话助手
频道
/teams/getAllChannels
组织中的所有频道。
不支持。 不支持。 Channel.ReadBasic.All,ChannelSettings.Read.All
频道
/teams/{id}/channels
组织中特定团队中的所有频道。
Channel.ReadBasic.All,ChannelSettings.Read.All 不支持。 Channel.ReadBasic.All,ChannelSettings.Read.All
聊天
/chats
组织中的所有聊天。
不支持。 不支持。 Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
聊天
/chats/{id}
特定聊天。
Chat.ReadBasic, Chat.Read, Chat.ReadWrite 不支持。 ChatSettings.Read.对话助手,ChatSettings.ReadWrite。对话助手,对话助手。管理。对话助手,对话助手。ReadBasic.All,对话助手。Read.All,对话助手。ReadWrite.All
聊天
/appCatalogs/teamsApps/{id}/installedToChats
安装了特定 Teams 应用的组织中的所有聊天。
不支持。 不支持。 对话助手。ReadBasic.WhereInstalled,对话助手。Read.WhereInstalled,对话助手。ReadWrite.WhereInstalled
聊天
/users/{id}/chats
特定用户所属的所有聊天。
Chat.ReadBasic, Chat.Read, Chat.ReadWrite 不支持。 Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
chatMessage
/teams/{id}/channels/{id}/messages
特定频道中的所有消息和答复。
ChannelMessage.Read.All、Group.Read.All、Group.ReadWrite.All 不支持。 ChannelMessage.Read.Group、ChannelMessage.Read.All
chatMessage
/teams/getAllMessages
组织中的所有频道消息。
不支持。 不支持。 ChannelMessage.Read.All
chatMessage
/chats/{id}/messages
聊天中的所有消息。
Chat.Read、Chat.ReadWrite 不支持。 Chat.Read.All
chatMessage
/chats/getAllMessages
组织中的所有聊天消息。
不支持。 不支持。 Chat.Read.All
chatMessage
/users/{id}/chats/getAllMessages
特定用户所属的所有聊天的对话助手消息。
Chat.Read、Chat.ReadWrite 不支持。 Chat.Read.All、Chat.ReadWrite.All
chatMessage
/appCatalogs/teamsApps/{id}/installedToChats/getAllMessages
安装了特定 Teams 应用的组织中所有聊天的对话助手消息。
不支持。 不支持。 对话助手。Read.WhereInstalled,对话助手。ReadWrite.WhereInstalled
联系人 Contacts.Read Contacts.Read Contacts.Read
conversationMember
/chats/getAllMembers
组织中所有聊天的成员。
不支持。 不支持。 ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All.
conversationMember
/chats/{id}/members
特定聊天的成员。
ChatMember.Read, ChatMember.ReadWrite, Chat.ReadBasic, Chat.Read, Chat.ReadWrite 不支持。 ChatMember.Read.Chat、Chat.Manage.Chat、ChatMember.Read.All、ChatMember.ReadWrite.All、Chat.ReadBasic.All、Chat.Read.All、Chat.ReadWrite.All
conversationMember
/appCatalogs/teamsApps/{id}/installedToChats/getAllMembers
对话助手,适用于安装特定 Teams 应用的组织中所有聊天的成员。
不支持。 不支持。 ChatMember.Read.WhereInstalled、ChatMember.ReadWrite.WhereInstalled、对话助手。ReadBasic.WhereInstalled,对话助手。Read.WhereInstalled,对话助手。ReadWrite.WhereInstalled
conversationMember
/teams/getAllMembers
组织中所有团队的成员。
不支持。 不支持。 TeamMember.Read.All, TeamMember.ReadWrite.All
conversationMember
/teams/{id}/members
特定团队中的成员。
TeamMember.Read.All 不支持。 TeamMember.Read.All
conversationMember
/teams/{id}/channels/getAllMembers
特定团队的所有专用频道中的成员。
不支持。 不支持。 ChannelMember.Read.All
conversationMember
/teams/getAllChannels/getAllMembers
不支持。 不支持。 ChannelMember.Read.All
driveItem(用户的个人 OneDrive) 不支持。 Files.ReadWrite 不支持。
driveItem (OneDrive 工作或学校) Files.ReadWrite.All 不支持。 Files.ReadWrite.All
事件 Calendars.Read Calendars.Read Calendars.Read
组 Group.Read.All 不支持。 Group.Read.All
组对话 Group.Read.All 不支持。 不支持。
Microsoft Entra 运行状况监视警报
/reports/healthmonitoring/alerts
HealthMonitoringAlertConfig.ReadWrite.All 不支持。 HealthMonitoringAlertConfig.ReadWrite.All
列表 Sites.ReadWrite.All 不支持。 Sites.ReadWrite.All
邮件 Mail.ReadBasic、Mail.Read Mail.ReadBasic、Mail.Read Mail.Read
offerShiftRequest
/teams/{id}/schedule/offerShiftRequests
对团队中的任何优惠班次请求的更改。
Schedule.Read.All、Schedule.ReadWrite.All 不支持。 Schedule.Read.All、Schedule.ReadWrite.All
onlineMeeting 不支持。 不支持。 OnlineMeetings.Read.All、OnlineMeetings.ReadWrite.All
openShiftChangeRequest
/teams/{id}/schedule/openShiftChangeRequests
对团队中任何未完成班次请求的更改。
Schedule.Read.All、Schedule.ReadWrite.All 不支持。 Schedule.Read.All、Schedule.ReadWrite.All
状态 Presence.Read.All 不支持。 不支持。
打印机 不支持。 不支持。 打印机。阅读.All,Printer.ReadWrite.All
printTaskDefinition 不支持。 不支持。 PrintTaskDefinition.ReadWrite.All
安全警报 SecurityEvents.ReadWrite.All 不支持。 SecurityEvents.ReadWrite.All
shift
/teams/{id}/schedule/shifts
对团队中任何班次的更改。
Schedule.Read.All、Schedule.ReadWrite.All 不支持。 Schedule.Read.All、Schedule.ReadWrite.All
swapShiftsChangeRequest
/teams/{id}/schedule/swapShiftsChangeRequests
对团队中的任何交换班次请求的更改。
Schedule.Read.All、Schedule.ReadWrite.All 不支持。 Schedule.Read.All、Schedule.ReadWrite.All
团队
/teams
组织中的所有团队。
不支持。 不支持。 Team.ReadBasic.All,TeamSettings.Read.All
团队
/teams/{id}
特定团队。
Team.ReadBasic.All,TeamSettings.Read.All 不支持。 Team.ReadBasic.All,TeamSettings.Read.All
timeOffRequest
/teams/{id}/schedule/timeOffRequests
对团队中任何休假请求的更改。
Schedule.Read.All、Schedule.ReadWrite.All 不支持。 Schedule.Read.All、Schedule.ReadWrite.All
todoTask Tasks.ReadWrite Tasks.ReadWrite Tasks.ReadWrite.All
用户 User.Read.All User.Read.All User.Read.All
virtualEventWebinar VirtualEvent.Read 不支持。 VirtualEvent.Read.All
virtualEventTownhall VirtualEvent.Read 不支持。 VirtualEvent.Read.All
baseTask (已弃用) Tasks.ReadWrite Tasks.ReadWrite 不支持。

注意

以下权限使用 特定于资源的同意:

  • OnlineMeetingRecording.Read.对话助手
  • OnlineMeetingTranscript.Read.对话助手
  • ChatSettings.Read.Chat
  • ChatSettings.ReadWrite.Chat
  • Chat.Manage.Chat
  • ChannelMessage.Read.Group
  • ChatMember.Read.Chat
  • AiEnterpriseInteraction.Read.User

chatMessage

可以指定 chatMessage 订阅来包含资源数据 (includeResourceData 设置为 true) 。 在这种情况下,需要加密,如果未为此类订阅指定 encryptionCertificate ,则订阅创建将失败。

使用 Prefer: include-unknown-enum-members 请求标头获取 chatMessagemessageType可演变枚举中的以下值: systemEventMessage for /teams/{id}/channels/{id}/messages 和 /chats/{id}/messages resource。

conversationMember

可以指定 conversationMember 订阅来包括资源数据 (将 includeResourceData 设置为 true) 。 在这种情况下,需要加密,如果未为此类订阅指定 encryptionCertificate ,则订阅创建将失败。

团队、频道和聊天

可以指定团队、频道和聊天订阅来包括资源数据 (includeResourceData 设置为 true) 。 在这种情况下,需要加密,如果未为此类订阅指定 encryptionCertificate ,则订阅创建将失败。

订阅特定聊天中或用户级别的更改时,可以使用 notifyOnUserSpecificProperties 查询字符串参数。 在创建订阅期间将查询字符串参数 notifyOnUserSpecificPropertiestrue 设置为时,将向订阅者发送两种类型的有效负载。 一种类型包含用户特定的属性,而另一种类型则不包含这些属性。 有关详细信息,请参阅使用 Microsoft Graph 获取聊天的更改通知。

aiInsights

订阅 Copilot AI 见解需要有效的 Copilot 许可证,其中包括以下 Copilot 服务计划:

  • 智能 Microsoft 365 Copilot 副驾驶® 对话助手: 3f30311c-6b1e-48a4-ab79-725b469da960

aiInteraction

订阅 Copilot AI 交互需要有效的 Copilot 许可证,其中包括以下 Copilot 服务计划:

  • 智能 Microsoft 365 Copilot 副驾驶® 对话助手: 3f30311c-6b1e-48a4-ab79-725b469da960

对于面向特定用户所属的 Copilot AI 交互的订阅,资源路径中的用户必须以有效状态分配给他们的以前的服务计划。

对于面向整个租户的 Copilot AI 交互的订阅,租户必须预配了包括所有以前的 Copilot 服务计划在内的有效许可证。

driveItem

更多限制适用于 OneDrive 项的订阅。 这些限制适用于订阅的创建和管理(获取、更新和删除)。

在个人 OneDrive 上,可订阅根文件夹或该驱动器中的任何子文件夹。 在 OneDrive 工作或学校中,只能订阅根文件夹。 将针对订阅文件夹或其层次结构中的任何文件、文件夹或其他 driveItem 实例上请求的更改发送更改通知。 不能订阅非文件夹的 驱动器 或 driveItem 实例,例如单个文件。

工作或学校 OneDrive 和 SharePoint 支持向应用程序发送 driveItem 上发生的安全事件的通知。 若要订阅这些事件,请为请求添加 prefer:includesecuritywebhooks 标头以创建订阅。 创建订阅后,当项目权限更改时,你将收到通知。 此标头适用于 SharePoint 和 OneDrive 工作或学校帐户,但不适用于消费者 OneDrive 帐户。

联系人、事件和消息

可以订阅 Outlook 联系人、 事件或 消息 资源中的更改,并可选择在 POST 请求有效负载中指定是否在通知中包含加密资源数据。

创建和管理(获取、更新和删除)订阅需要资源的读取范围。 例如,若要获取有关邮件的更改通知,应用需要 Mail.Read 权限。 Outlook 更改通知支持委派和应用程序权限范围。 请注意以下限制:

  • 委托的权限仅支持订阅已登录用户的邮箱内文件夹中的项。 例如,不能使用委派权限 Calendars.Read 来订阅其他用户邮箱中的事件。

  • 订阅共享或委托文件夹中 Outlook 联系人、事件或邮件的更改通知:

    • 使用相应的应用程序权限订阅租户内任何用户的文件夹或邮箱中项目的更改。
    • 请勿 (Contacts.Read.Shared、Calendars.Read.Shared、Mail.Read.Shared 及其对应的读/写权限) 使用 Outlook 共享权限,因为它们 不 支持订阅共享或委派文件夹中项目的更改通知。

onlineMeetings, 状态

在为包含加密资源数据的通知创建订阅时,onlineMeetings 和状态上的订阅需要 encryptionCertificate 和 encryptionCertificateId 属性。 有关详细信息,请参阅 设置更改通知以包含资源数据。 有关联机会议订阅的详细信息,请参阅 获取联机会议的更改通知。

virtualEventWebinar 和 virtualEventTownhall

虚拟事件的订阅仅支持基本通知,并且仅限于虚拟事件的几个实体。 有关受支持的订阅类型的详细信息,请参阅获取 Microsoft Teams 虚拟事件更新的更改通知。

HTTP 请求

POST /subscriptions

请求标头

名称 类型 说明
Authorization string 持有者 {token}。 必填。 详细了解 身份验证和授权。

请求正文

在请求正文中,提供 subscription 对象的 JSON 表示形式。

响应

如果成功,此方法将在响应正文中返回响应 201 Created 代码和 订阅 对象。

要详细了解错误返回方式,请参阅错误响应。

示例

请求

在请求正文中,提供 subscription 对象的 JSON 表示形式。 clientState 和 latestSupportedTlsVersion 是可选字段。

此请求创建有关当前登录用户收到的新邮件的更改通知的订阅。

POST https://graph.microsoft.com/beta/subscriptions
Content-type: application/json

{
   "changeType": "created",
   "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
   "resource": "me/mailFolders('Inbox')/messages",
   "expirationDateTime":"2016-11-20T18:23:45.9356913Z",
   "clientState": "secretClientValue",
   "latestSupportedTlsVersion": "v1_2"
}

在请求正文中,提供 subscription 对象的 JSON 表示形式。 clientState 和 latestSupportedTlsVersion 是可选字段。

重复订阅行为

不允许重复订阅。 当订阅请求包含与现有订阅包含的相同 changeType 和 资源 值时,请求将失败,并显示 HTTP 错误代码 409 Conflict和错误消息 Subscription Id <> already exists for the requested combination。

资源示例

以下是资源属性的有效值。

资源类型 示例
approvalItems solution/approval/approvalItems
callRecord communications/callRecords
callRecording communications/onlineMeetings/getAllRecordings, communications/onlineMeetings/{onlineMeetingId}/recordings, users/{userId}/onlineMeetings/getAllRecordings, appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings
callTranscript communications/onlineMeetings/getAllTranscripts, communications/onlineMeetings/{onlineMeetingId}/transcripts, users/{userId}/onlineMeetings/getAllTranscripts, appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTranscripts
频道 /teams/getAllChannels, /teams/{id}/channels
聊天 /chats, /chats/{id}
chatMessage chats/{id}/messages, chats/getAllMessages, teams/{id}/channels/{id}/messages, teams/getAllMessages
联系人 me/contacts
conversationMember /chats/{id}/members, /chats/getAllMembers, /teams/{id}/members, /teams/getAllMembers, /teams/{id}/channels/getAllMembers
driveItem me/drive/root
事件 me/events
组 groups
组对话 groups('{id}')/conversations
运行状况监视警报 reports/healthmonitoring/alerts
列表 sites/{site-id}/lists/{list-id}
邮件 me/mailfolders('inbox')/messages, me/messages
onlineMeeting /communications/onlineMeetings/?$filter=JoinWebUrl eq '{JoinWebUrl}'
状态 /communications/presences/{id}(单个用户),/communications/presences?$filter=id in ('{id}','{id}',…)(多个用户)
打印机 print/printers/{id}/jobs
printTaskDefinition print/taskDefinitions/{id}/tasks
团队 /teams, /teams/{id}
user users
todoTask /me/todo/lists/{todoTaskListId}/tasks
安全警报 security/alerts?$filter=status eq 'NewAlert'
baseTask (已弃用) /me/tasks/lists/{Id}/tasks

注意

任何以 开 me 头的路径也可以用于 instead users/{id}me 来定位特定用户而不是当前用户。

响应

以下示例显示了相应的响应。

注意:为了提高可读性,可能缩短了此处显示的响应对象。

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#subscriptions/$entity",
  "id": "7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
  "resource": "me/mailFolders('Inbox')/messages",
  "applicationId": "24d3b144-21ae-4080-943f-7067b395b913",
  "changeType": "created",
  "clientState": "secretClientValue",
  "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
  "expirationDateTime": "2016-11-20T18:23:45.9356913Z",
  "creatorId": "8ee44408-0679-472c-bc2a-692812af3437",
  "latestSupportedTlsVersion": "v1_2",
  "notificationContentType": "application/json"
}

示例 2:创建面向 Web 推送终结点的订阅

以下示例创建一个订阅,用于将加密的更改通知传递到浏览器原生 Web 推送终结点 ((例如 web.push.apple.com、 或 fcm.googleapis.comupdates.push.services.mozilla.com) )。

在创建此订阅之前,基于浏览器的应用程序必须:

  1. 调用订阅集合上的 getVapidPublicKey 函数,以获取 Microsoft Graph 的 VAPID 公钥 (RFC 8292) 。
  2. 调用 PushManager.subscribe({ applicationServerKey: <vapidPublicKey> }) 以注册浏览器的推送服务。 浏览器返回包含 PushSubscriptionendpoint、 和p256dhauth值。

然后,应用程序创建订阅,其中 notificationUrl 设置为裸推送服务终结点 URL,并将 vapidPublicKey、 webPushEncryptionP256dhPublicKey 和 webPushEncryptionSecret 属性设置为浏览器返回的值。 创建后,Microsoft Graph 根据 RFC 8291 使用存储的密钥对每个通知进行加密,并在发布到推送服务之前使用 VAPID 对请求进行签名。

请求

POST https://graph.microsoft.com/beta/subscriptions
Content-type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://web.push.apple.com/QKmFUwSBFK8g7iY4t1...",
  "resource": "me/mailFolders('Inbox')/messages",
  "expirationDateTime": "2026-12-31T11:00:00.0000000Z",
  "clientState": "secretClientValue",
  "vapidPublicKey": "BNKm...base64url-encoded-server-vapid-public-key...",
  "webPushEncryptionP256dhPublicKey": "BNcR...base64url-encoded-client-public-key...",
  "webPushEncryptionSecret": "tBHI...base64url-encoded-auth-secret..."
}

注意:webPushEncryptionSecret 属性是只写的。 它永远不会在响应中 GET 返回 (作为) 返回 null 。 将值视为机密。

通知终结点验证

(notificationUrl 属性中指定的订阅通知终结点) 必须能够响应验证请求,如 设置用户数据更改的通知中所述。 如果验证失败,创建订阅请求返回错误“400 请求无效”。