命名空间:microsoft.graph
订阅侦听器应用程序,以在 Microsoft Graph 中指定资源发生的更改属于请求的更改类型时接收更改通知。
若要确定可为其创建订阅的资源和订阅限制,请参阅 设置资源数据更改通知:支持的资源。
某些资源支持丰富的通知,即包含资源数据的通知。 有关这些资源的详细信息,请参阅 设置包含资源数据的更改通知:支持的资源。
此 API 可用于以下国家级云部署。
| 全局服务 | 美国政府 L4 | 美国政府 L5 (DOD) | 由世纪互联运营的中国 |
|---|---|---|---|
| ✅ | ✅ | ✅ | ✅ |
权限
若要创建订阅,应用必须具有对该资源的读取权限。 例如,若要获取消息的更改通知,你的应用需要 Mail.Read 权限。
根据请求的资源和权限类型(委托或应用程序),下表中指定的权限为调用此 API 所需的最小权限。 要了解详细信息,包括在选择权限之前的 注意事项,可在 权限 中搜索以下权限。
| 支持的资源 | 委派(工作或学校帐户) | 委派(个人 Microsoft 帐户) | 应用程序 |
|---|---|---|---|
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 |
| callRecord (/communications/callRecords) | 不支持 | 不支持 | 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 |
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 |
| 频道(/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.Chat*、ChatSettings.ReadWrite.Chat*、Chat.Manage.Chat*、Chat.ReadBasic.All、Chat.Read.All、Chat.ReadWrite.All |
|
聊天 /appCatalogs/teamsApps/{id}/installedToChats 安装了特定 Teams 应用的组织中所有聊天。 |
不支持 | 不支持 | Chat.ReadBasic.WhereInstalled、Chat.Read.WhereInstalled、Chat.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 | 不支持 | 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 应用的组织中所有聊天的聊天消息。 |
不支持 | 不支持 | Chat.Read.WhereInstalled、Chat.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、Chat.ReadBasic.WhereInstalled、Chat.Read.WhereInstalled、Chat.ReadWrite.WhereInstalled |
| conversationMember (/teams/{id}/members) | TeamMember.Read.All | 不支持 | TeamMember.Read.All |
| conversationMember (/teams/{id}/channels/getAllMembers) | 不支持 | 不支持 | ChannelMember.Read.All |
| driveItem(用户的个人 OneDrive) | 不支持 | Files.Read | 不支持 |
| driveItem (OneDrive for Business) | Files.Read.All | 不支持 | Files.Read.All |
| 事件 | Calendars.Read | Calendars.Read | Calendars.Read |
| 组 | Group.Read.All | 不支持 | Group.Read.All |
| 组对话 | Group.Read.All | 不支持 | 不支持 |
| 列表 | Sites.Read.All | 不支持 | Sites.Read.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 |
|
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 | 不支持 |
| user | User.Read.All | User.Read.All | User.Read.All |
| virtualEventWebinar | VirtualEvent.Read | 不支持。 | VirtualEvent.Read.All |
| virtualEventTownhall | VirtualEvent.Read | 不支持。 | VirtualEvent.Read.All |
建议使用上表中记载的权限。 由于安全限制,当仅需要读取访问权限时,Microsoft Graph 订阅不支持写入访问权限。
注意:标有 * 的权限用于特定于资源的同意。
chatMessage
可以将 chatMessage 订阅指定为包含资源数据 (includeResourceData 设置为 true) 。 在这种情况下,需要加密,如果未为此类订阅指定 encryptionCertificate ,则订阅创建会失败。
使用 Prefer: include-unknown-enum-members 请求标头在 chatMessagemessageType可进化枚举中获取以下值: systemEventMessage for /teams/{id}/channels/{id}/messages 和 /chats/{id}/messages resource。
注意
/teams/getAllMessages、 /chats/getAllMessages、 /me/chats/getAllMessages、 /users/{id}/chats/getAllMessages和 /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages 是按流量计费的 API; 付款模式和许可要求 可能适用。
/teams/getAllMessages和 /chats/getAllMessages 都支持 和 model=B 支付模型、/me/chats/getAllMessages、 /users/{id}/chats/getAllMessages和 /appCatalogs/teamsApps/{id}/installedToChats/getAllMessages 仅model=B支持 。model=A
如果未在查询中指定付款模型,则使用默认 评估模式 。
注意
若要为已订阅的更改通知资源添加或更改付款模型,必须使用新的付款模型创建新的更改通知订阅;更新现有更改通知不起作用。
conversationMember
可以将 conversationMember 订阅指定为包含资源数据 (includeResourceData 设置为 true) 。 在这种情况下,需要加密,如果未为此类订阅指定 encryptionCertificate ,则订阅创建会失败。
注意
/teams/getAllMembers、 /chats/getAllMembers和 /appCatalogs/teamsApps/{id}/installedToChats/getAllMembers 是按流量计费的 API; 付款模式和许可要求 可能适用。
/teams/getAllMembers 和 /chats/getAllMembers 都 model=A 支持 和 model=B 支付模型。
/appCatalogs/teamsApps/{id}/installedToChats/getAllMembers 仅 model=B支持 。
如果未在查询中指定付款模型,则使用默认 评估模式 。
注意
若要为已订阅的更改通知资源添加或更改付款模型,必须使用新的付款模型创建新的更改通知订阅;更新现有更改通知不起作用。
团队、频道和聊天
可以将团队、频道和聊天订阅指定为包含资源数据, (includeResourceData 设置为 true) 。 在这种情况下,需要加密,如果未为此类订阅指定 encryptionCertificate ,则订阅创建会失败。
订阅特定聊天或用户级别的更改时,可以使用 notifyOnUserSpecificProperties 查询字符串参数。 在创建订阅期间将查询字符串参数 notifyOnUserSpecificPropertiestrue 设置为 时,会将两种类型的有效负载发送到订阅服务器。 一种类型包含特定于用户的属性,另一种类型在发送时不使用它们。 有关详细信息,请参阅 使用 Microsoft Graph 获取聊天更改通知。
注意
若要为已订阅的更改通知资源添加或更改付款模型,必须使用新的付款模型创建新的更改通知订阅;更新现有更改通知不起作用。
请求示例
在请求正文中的 资源 内指定 model 查询参数。
POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json
{
"changeType": "created",
"notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
"resource": "chats/getAllMessages?model=A",
"expirationDateTime":"2016-11-20T18:23:45.9356913Z",
"clientState": "secretClientValue",
"latestSupportedTlsVersion": "v1_2"
}
aiInteraction
Copilot AI 交互上的订阅需要有效的 Copilot 许可证,其中包括以下 Copilot 服务计划:
- 智能 Microsoft 365 Copilot 副驾驶® 对话助手:3f30311c-6b1e-48a4-ab79-725b469da960
对于面向特定用户所属的 Copilot AI 交互的订阅,资源路径中的用户必须具有以有效状态分配给他们的以前的服务计划。
对于面向整个租户的 Copilot AI 交互的订阅,租户必须预配了包含所有以前的 Copilot 服务计划的有效许可证。
driveItem
其他限制适用于 OneDrive 项目的订阅。 这些限制适用于订阅的创建和管理(获取、更新和删除)。
在个人 OneDrive 上,可订阅根文件夹或该驱动器中的任何子文件夹。 在 OneDrive for Business 上,只可以订阅根文件夹。 对订阅的文件夹或者其层次结构中的任何文件、文件夹或其他 driveItem 实例所做更改属于请求的更改类型时,发送更改通知。 不能订阅不是文件夹的 驱动器 或 driveItem 实例,例如单个文件。
OneDrive for Business 和 SharePoint 支持向应用程序发送有关在 driveItem 上发生的安全事件通知。 若要订阅这些事件,请为请求添加 prefer:includesecuritywebhooks 标头以创建订阅。 创建订阅后,当项目权限更改时,你将收到通知。 此标头适用于 SharePoint 和 OneDrive for Business 帐户,但不适用于 OneDrive 消费者版本的帐户。
联系人、事件和消息
你可以订阅 Outlook 联系人、事件或消息资源中的更改。
创建和管理(获取、更新和删除)订阅需要资源的读取范围。 例如,若要获取有关邮件的更改通知,应用需要 Mail.Read 权限。 Outlook 更改通知支持委派和应用程序权限范围。 请注意以下限制:
委托的权限仅支持订阅已登录用户的邮箱内文件夹中的项。 例如,不能使用委托的权限 Calendars.Read 订阅其他用户邮箱中的事件。
订阅共享或委托文件夹中 Outlook 联系人、事件或邮件的更改通知:
- 使用相应的应用程序权限订阅租户内任何用户的文件夹或邮箱中项目的更改。
- 请勿使用 Outlook 共享权限 (Contacts.Read.Shared、Calendars.Read.Shared、Mail.Read.Shared 及其读/写权限) ,因为它们 不支持 订阅共享或委派文件夹中项目的更改通知。
状态
状态 上的订阅要求对更改通知中包含的任何资源数据进行加密。 在 创建订阅 时始终指定 encryptionCertificate 参数以避免失败。 请参阅有关 设置更改通知以包含资源数据 的详细信息。
virtualEventWebinar 和 virtualEventTownhall
虚拟事件的订阅仅支持基本通知,并且仅限于虚拟事件的几个实体。 有关支持的订阅类型的详细信息,请参阅 获取Microsoft Teams 虚拟事件更新的更改通知。
HTTP 请求
POST /subscriptions
请求标头
| 名称 | 类型 | 说明 |
|---|---|---|
| Authorization | string | 持有者 {token}。 必填。 详细了解 身份验证和授权。 |
请求正文
在请求正文中,提供 subscription 对象的 JSON 表示形式。
响应
如果成功,此方法在响应正文中返回 201 Created 响应代码和 subscription 对象。
要详细了解错误返回方式,请参阅错误响应。
示例
请求
以下示例演示了在用户收到新邮件时发送更改通知的请求。
POST https://graph.microsoft.com/v1.0/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。
资源示例
订阅资源属性的有效值如下:
| 资源类型 | 示例 |
|---|---|
| 通话记录 | communications/callRecords |
| callRecording |
communications/onlineMeetings/getAllRecordings, communications/onlineMeetings/{onlineMeetingId}/recordings, users/{userId}/onlineMeetings/getAllRecordings |
| callTranscript |
communications/onlineMeetings/getAllTranscripts, communications/onlineMeetings/{onlineMeetingId}/transcripts, users/{userId}/onlineMeetings/getAllTranscripts |
| 聊天消息 |
chats/{id}/messages, chats/getAllMessages, teams/{id}/channels/{id}/messages, teams/getAllMessages |
| 联系人 | me/contacts |
| 对话 | groups('{id}')/conversations |
| 驱动器 | me/drive/root |
| 事件 | me/events |
| 组 | groups |
| 列表 | sites/{site-id}/lists/{list-id} |
| 邮件 |
me/mailfolders('inbox')/messages, me/messages |
| 状态 |
/communications/presences/{id}(单个用户),/communications/presences?$filter=id in ('{id}','{id}',…)(多个用户) |
| 打印机 | print/printers/{id}/jobs |
| PrintTaskDefinition | print/taskDefinitions/{id}/tasks |
| 安全警报 | security/alerts?$filter=status eq 'New' |
| todoTask | /me/todo/lists/{todoTaskListId}/tasks |
| 用户 | users |
注意:以
me开头的任何路径也可与users/{id}(而不是me)一起使用,从而以特定用户为目标,而不是以当前用户为目标。
响应
以下示例显示了相应的响应。
注意:为了提高可读性,可能缩短了此处显示的响应对象。
HTTP/1.1 201 Created
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$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"
}
通知终结点验证
通知终结点(于 notificationUrl 属性中指定)必须能够响应验证请求,如设置用户数据更改的通知中所述。 如果验证失败,创建订阅请求返回错误“400 请求无效”。