创建订阅

命名空间:microsoft.graph

重要

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

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

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

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

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

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

权限

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

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

注意

  • 由于安全限制,当仅需要读取访问权限时,Microsoft Graph 订阅不支持写入访问权限。
  • 某些资源在多种方案中支持更改通知,其中每个方案可能需要不同的权限。 在这些情况下,请使用资源路径来区分方案。
支持的资源 委派(工作或学校帐户) 委派(个人 Microsoft 帐户) 应用程序
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.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
聊天
/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 应用的组织中所有聊天的聊天消息。
不支持。 不支持。 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 work or school) 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
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 不支持。
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/getAllMessagesmodel=B支持 。model=A 如果未在查询中指定付款模型,将使用默认 评估模式

注意

若要为已订阅的更改通知资源添加或更改付款模型,必须使用新的付款模型创建新的更改通知订阅;更新现有更改通知不起作用。

conversationMember

可以指定 conversationMember 订阅以包含资源数据。 如果指定为包含资源数据(将 includeResourceData 设置为 true),则需要 encryption。 如果未指定 encryptionCertificate,则订阅创建将失败。

注意

/teams/getAllMembers/chats/getAllMembers/appCatalogs/teamsApps/{id}/installedToChats/getAllMembers 是按流量计费的 API; 付款模式和许可要求 可能适用。 /teams/getAllMembers/chats/getAllMembersmodel=A 支持 和 model=B 支付模型。 /appCatalogs/teamsApps/{id}/installedToChats/getAllMembersmodel=B支持 。 如果未在查询中指定付款模型,将使用默认 评估模式

注意

若要为已订阅的更改通知资源添加或更改付款模型,必须使用新的付款模型创建新的更改通知订阅;更新现有更改通知不起作用。

团队、频道和聊天

可以指定团队频道聊天订阅以包含资源数据。 如果指定为包含资源数据(将 includeResourceData 设置为 true),则需要 encryption。 如果未指定 encryptionCertificate,则订阅创建将失败。

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

注意

/appCatalogs/teamsApps/{id}/installedToChats 具有 许可和付款要求,特别是仅 model=B支持 。 如果未指定模型,将使用评估模式

注意

若要为已订阅的更改通知资源添加或更改付款模型,必须使用新的付款模型创建新的更改通知订阅;更新现有更改通知不起作用。

请求示例

在请求正文中的 资源 内指定 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 work 或 School 上,只能订阅根文件夹。 对于订阅的文件夹或其层次结构中的任何文件、文件夹或其他 driveItem 实例,将发送更改通知。 不能订阅不是文件夹的 驱动器driveItem 实例,例如单个文件。

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

联系人、事件和消息

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

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

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

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

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

onlineMeetings, 状态

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

virtualEventWebinar

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

HTTP 请求

POST /subscriptions

请求标头

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

请求正文

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

响应

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

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

示例

请求

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

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

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 表示形式。 clientStatelatestSupportedTlsVersion 是可选字段。

重复订阅行为

不允许重复订阅。 当订阅请求包含与现有订阅包含的 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
列表 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 请求无效”。