创建订阅
命名空间：microsoft.graph
重要
Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用，请使用 版本 选择器。
订阅侦听器应用程序，以在 Microsoft Graph 中指定资源发生的更改属于请求的更改类型时接收更改通知。
若要确定可为其创建订阅的资源和订阅限制，请参阅 设置资源数据更改通知：支持的资源。
某些资源支持丰富的通知，即包含资源数据的通知。 有关这些资源的详细信息，请参阅 设置包含资源数据的更改通知：支持的资源。
此 API 可用于以下国家级云部署。
| 全局服务 | 美国政府 L4 | 美国政府 L5 (DOD) | 由世纪互联运营的中国 |
|---|---|---|---|
| ✅ | ✅ | ✅ | ✅ |
权限
创建订阅需要对资源的读取权限。 例如，若要获取有关邮件的更改通知，应用需要 Mail.Read 权限。
根据请求的资源和权限类型（委托或应用程序），下表中指定的权限为调用此 API 所需的最小权限。 要了解详细信息，包括在选择权限之前的 注意事项，可在 权限 中搜索以下权限。
注意
- 由于安全限制，当仅需要读取访问权限时，Microsoft Graph 订阅不支持写入访问权限。
- 某些资源在多种方案中支持更改通知，其中每个方案可能需要不同的权限。 在这些情况下，请使用资源路径来区分方案。
| 支持的资源 | 委派（工作或学校帐户） | 委派（个人 Microsoft 帐户） | 应用程序 |
|---|---|---|---|
| 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.Chat |
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.Chat |
频道 /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 |
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 应用的组织中所有聊天的聊天消息。 |
不支持。 | 不支持。 | Chat.Read.WhereInstalled、Chat.ReadWrite.WhereInstalled |
| contact | 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/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 for Business) | Files.ReadWrite.All | 不支持。 | Files.ReadWrite.All |
| 事件 | Calendars.Read | Calendars.Read | Calendars.Read |
| 组 | Group.Read.All | 不支持。 | Group.Read.All |
| 组对话 | Group.Read.All | 不支持。 | 不支持。 |
| 列表 | Sites.ReadWrite.All | 不支持。 | Sites.ReadWrite.All |
| 邮件 | Mail.ReadBasic、Mail.Read | Mail.ReadBasic、Mail.Read | Mail.Read |
| onlineMeeting | 不支持。 | 不支持。 | OnlineMeetings.Read.All、OnlineMeetings.ReadWrite.All |
| 状态 | Presence.Read.All | 不支持。 | 不支持。 |
| 打印机 | 不支持。 | 不支持。 | 打印机。阅读.All，Printer.ReadWrite.All |
| printTaskDefinition | 不支持。 | 不支持。 | PrintTaskDefinition.ReadWrite.All |
| 安全警报 | SecurityEvents.ReadWrite.All | 不支持。 | SecurityEvents.ReadWrite.All |
团队 /teams 组织中的所有团队。 |
不支持。 | 不支持。 | Team.ReadBasic.All，TeamSettings.Read.All |
团队 /teams/{id} 特定团队。 |
Team.ReadBasic.All，TeamSettings.Read.All | 不支持。 | Team.ReadBasic.All，TeamSettings.Read.All |
| todoTask | Tasks.ReadWrite | Tasks.ReadWrite | 不支持。 |
| user | User.Read.All | User.Read.All | User.Read.All |
| virtualEventWebinar | VirtualEvent.Read | 不支持。 | VirtualEvent.Read.All |
| baseTask (已弃用) | Tasks.ReadWrite | Tasks.ReadWrite | 不支持。 |
注意
以下权限使用 特定于资源的许可：
- OnlineMeetingRecording.Read.Chat
- OnlineMeetingTranscript.Read.Chat
- ChatSettings.Read.Chat
- ChatSettings.ReadWrite.Chat
- Chat.Manage.Chat
- ChannelMessage.Read.Group
- ChatMember.Read.Chat
chatMessage
可以指定 chatMessage 订阅以包含资源数据。 如果指定为包含资源数据（将 includeResourceData 设置为 true），则需要 encryption。 如果没有为此类订阅指定 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），则需要 encryption。 如果未指定 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），则需要 encryption。 如果未指定 encryptionCertificate，则订阅创建将失败。
注意
若要为已订阅的更改通知资源添加或更改付款模型，必须使用新的付款模型创建新的更改通知订阅;更新现有更改通知不起作用。
请求示例
在请求正文中的 资源 内指定 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"
}
driveItem
更多限制适用于 OneDrive 项的订阅。 这些限制适用于订阅的创建和管理（获取、更新和删除）。
在个人 OneDrive 上，可订阅根文件夹或该驱动器中的任何子文件夹。 在 OneDrive for Business 上，只可以订阅根文件夹。 对于订阅的文件夹或其层次结构中的任何文件、文件夹或其他 driveItem 实例，将发送更改通知。 不能订阅不是文件夹的 驱动器 或 driveItem 实例，例如单个文件。
OneDrive for Business 和 SharePoint 支持向应用程序发送有关在 driveItem 上发生的安全事件通知。 若要订阅这些事件，请为请求添加 prefer:includesecuritywebhooks 标头以创建订阅。 创建订阅后，当项目权限更改时，你将收到通知。 此标头适用于 SharePoint 和 OneDrive for Business 但不适用于使用者 OneDrive 帐户。
联系人、事件和消息
您可以订阅 Outlook 联系人、 事件或 邮件 资源中的更改，并在 POST 请求有效负载中选择性地指定是否在通知中包含加密的资源数据。
创建和管理（获取、更新和删除）订阅需要资源的读取范围。 例如，若要获取有关邮件的更改通知，应用需要 Mail.Read 权限。 Outlook 更改通知支持委派和应用程序权限范围。 请注意以下限制：
委托的权限仅支持订阅已登录用户的邮箱内文件夹中的项。 例如，不能使用委托的权限 Calendars.Read 订阅其他用户邮箱中的事件。
订阅共享或委托文件夹中 Outlook 联系人、事件或邮件的更改通知：
- 使用相应的应用程序权限订阅租户内任何用户的文件夹或邮箱中项目的更改。
- 请勿使用 Outlook 共享权限 (Contacts.Read.Shared、Calendars.Read.Shared、Mail.Read.Shared 及其读/写权限) ，因为它们 不支持 订阅共享或委派文件夹中项目的更改通知。
onlineMeetings， 状态
在为包含加密资源数据的通知创建订阅时，onlineMeetings 和状态上的订阅需要 encryptionCertificate 和 encryptionCertificateId 属性。 有关详细信息，请参阅 设置更改通知以包含资源数据。 有关联机会议订阅的详细信息，请参阅 获取联机会议的更改通知。
virtualEventWebinar
虚拟事件的订阅仅支持基本通知，并且仅限于虚拟事件的几个实体。 有关支持的订阅类型的详细信息，请参阅 获取 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。
资源示例
下面是资源属性的有效值。
| 资源类型 | 示例 |
|---|---|
| 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 |
| 列表 | 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 开头的路径也可以与 一起使用 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"
}
通知终结点验证
在 notificationUrl 属性中指定的订阅通知终结点 () 必须能够响应验证请求，如 设置用户数据更改通知中所述。 如果验证失败，创建订阅请求返回错误“400 请求无效”。
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈