创建订阅

命名空间:microsoft.graph

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

请参阅" 权限 部分中的表格,了解支持订阅以更改通知的资源列表。

某些资源支持在更改通知中包括加密资源数据的选项。 这些资源包括 chatMessage联系人事件消息状态。 有关详细信息,请参阅设置包含资源数据的更改通知Microsoft Graph 中 Outlook 资源的更改通知

权限

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

根据请求的资源和权限类型(委托或应用程序),下表中指定的权限为调用此 API 所需的最小权限。 若要了解其他信息, 特权权限之前要特别小心,在"权限" 中搜索

支持的资源 委派(工作或学校帐户) 委派(个人 Microsoft 帐户) 应用程序
callRecord (/communications/callRecords) 不支持 不支持 CallRecords.Read.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.All
chatMessage(/chats/getAllMessages -- 组织中所有聊天消息) 不支持 不支持 Chat.Read.All
contact Contacts.Read Contacts.Read Contacts.Read
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.ReadBasic、Mail.Read
状态 Presence.Read.All 不支持 不支持
打印机 不支持 不支持 打印机。阅读.All,Printer.ReadWrite.All
printTaskDefinition 不支持 不支持 PrintTaskDefinition.ReadWrite.All
安全警报 SecurityEvents.ReadWrite.All 不支持 SecurityEvents.ReadWrite.All
用户 User.Read.All User.Read.All User.Read.All

注意:标有 * 的权限用于 特定于资源的同意

chatMessage

可以指定 chatMessage 订阅以包含资源数据。 如果指定为包含资源数据(将 includeResourceData 设置为 true),则需要 encryption。 如果没有为此类订阅指定 encryptionCertificate,则订阅创建将失败。 在可以使用应用程序权限创建 chatMessage 订阅之前,可能需要请求访问权限。 有关详细信息,请参阅 Microsoft Teams 中的受保护 API

必须使用 Prefer: include-unknown-enum-members 请求标头以 chatMessage messageType evolvable enum 中获取以下值:适用于 /teams/{id}/channels/{id}/messages/chats/{id}/messagessystemEventMessage

备注

/teams/getAllMessages/chats/getAllMessages/me/chats/getAllMessages/users/{id}/chats/getAllMessages具有许可和付款要求/teams/getAllMessages/chats/getAllMessages支持model=Amodel=B查询参数,/me/chats/getAllMessages/users/{id}/chats/getAllMessages仅支持model=B。 如果未指定模型,将使用评估模式

conversationMember

备注

/teams/getAllMembers/chats/getAllMembers 具有 许可和付款要求/teams/getAllMembers/chats/getAllMembers 同时支持 model=Amodel=B 查询参数。 如果未指定模型,将使用评估模式

请求示例

在请求正文中的 资源 内指定 model 查询参数。

POST https://graph.microsoft.com/beta/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 联系人事件消息 资源中的更改。

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

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

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

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

状态

状态 上的订阅要求对更改通知中包含的任何资源数据进行加密。 在 创建订阅 时始终指定 encryptionCertificate 参数以避免失败。 请参阅有关 设置更改通知以包含资源数据 的详细信息。

HTTP 请求

POST /subscriptions

请求标头

名称 类型 说明
Authorization string Bearer {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 表示形式。clientStatelatestSupportedTlsVersion 字段是可选的。

资源示例

订阅资源属性的有效值如下:

资源类型 示例
通话记录 communications/callRecords
聊天消息 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'
用户 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 请求无效”。