获取订阅Get subscription

命名空间:microsoft.graphNamespace: microsoft.graph

检索订阅的属性和关系。Retrieve the properties and relationships of a subscription.

权限Permissions

根据请求的资源和权限类型(委托或应用程序),下表中指定的权限为调用此 API 所需的最小权限。Depending on the resource and the permission type (delegated or application) requested, the permission specified in the following table is the least privileged required to call this API. 若要了解详细信息,包括如何选择权限的信息,请参阅权限To learn more, including how to choose permissions, see Permissions.

支持的资源Supported resource 委派(工作或学校帐户)Delegated (work or school account) 委派(个人 Microsoft 帐户)Delegated (personal Microsoft account) 应用程序Application
callRecordcallRecord 不支持Not supported 不支持Not supported CallRecords.Read.AllCallRecords.Read.All
chatMessage (/teams/{id}/channels/{id}/messages)chatMessage (/teams/{id}/channels/{id}/messages) 不支持Not supported 不支持Not supported ChannelMessage.Read.Group*、ChannelMessage.Read.AllChannelMessage.Read.Group*, ChannelMessage.Read.All
chatMessage(/teams/getAllMessages -- 组织中所有频道消息)chatMessage (/teams/getAllMessages -- all channel messages in organization) 不支持Not supported 不支持Not supported ChannelMessage.Read.AllChannelMessage.Read.All
chatMessage (/chats/{id}/messages)chatMessage (/chats/{id}/messages) 不支持Not supported 不支持Not supported Chat.Read.AllChat.Read.All
chatMessage(/chats/getAllMessages -- 组织中所有聊天消息)chatMessage (/chats/getAllMessages -- all chat messages in organization) 不支持Not supported 不支持Not supported Chat.Read.AllChat.Read.All
contactcontact Contacts.ReadContacts.Read Contacts.ReadContacts.Read Contacts.ReadContacts.Read
driveItem(用户的个人 OneDrive)driveItem (user's personal OneDrive) 不支持Not supported Files.ReadWriteFiles.ReadWrite 不支持Not supported
driveItem (OneDrive for Business)driveItem (OneDrive for Business) Files.ReadWrite.AllFiles.ReadWrite.All 不支持Not supported Files.ReadWrite.AllFiles.ReadWrite.All
事件event Calendars.ReadCalendars.Read Calendars.ReadCalendars.Read Calendars.ReadCalendars.Read
group Group.Read.AllGroup.Read.All 不支持Not supported Group.Read.AllGroup.Read.All
组对话group conversation Group.Read.AllGroup.Read.All 不支持Not supported 不支持Not supported
列表list Sites.ReadWrite.AllSites.ReadWrite.All 不支持Not supported Sites.ReadWrite.AllSites.ReadWrite.All
邮件message Mail.ReadBasic、Mail.ReadMail.ReadBasic, Mail.Read Mail.ReadBasic、Mail.ReadMail.ReadBasic, Mail.Read Mail.ReadBasic、Mail.ReadMail.ReadBasic, Mail.Read
安全警报security alert SecurityEvents.ReadWrite.AllSecurityEvents.ReadWrite.All 不支持Not supported SecurityEvents.ReadWrite.AllSecurityEvents.ReadWrite.All
用户user User.Read.AllUser.Read.All User.Read.AllUser.Read.All User.Read.AllUser.Read.All

注意 :标有 * 的权限用于 特定于资源的同意Note : Permissions marked with * use resource-specific consent.

chatMessagechatMessage

具有应用程序权限的 chatMessage 订阅包含资源数据,并且需要进行 加密chatMessage subscriptions with application permissions include resource data, and require encryption. 如果未指定 encryptionCertificate,则订阅创建将失败。Subscription creation will fail if encryptionCertificate is not specified. 创建 chatMessage 订阅前,必须请求访问权限。Before creating a chatMessage subscription, you must request access. 有关详细信息,请参阅 Microsoft Teams 中的受保护 APIFor details, see Protected APIs in Microsoft Teams.

注意: /teams/getAllMessages/chats/getAllMessages 可供拥有 所需许可证的用户使用。Note: /teams/getAllMessages and /chats/getAllMessages are available to users that have the required licenses.

driveItemdriveItem

其他限制适用于 OneDrive 项目的订阅。Additional limitations apply for subscriptions on OneDrive items. 这些限制适用于订阅的创建和管理(获取、更新和删除)。The limitations apply to creating as well as managing (getting, updating, and deleting) subscriptions.

在个人 OneDrive 上,可订阅根文件夹或该驱动器中的任何子文件夹。On a personal OneDrive, you can subscribe to the root folder or any subfolder in that drive. 在 OneDrive for Business 上,只可以订阅根文件夹。On OneDrive for Business, you can subscribe to only the root folder. 对订阅的文件夹或者其层次结构中的任何文件、文件夹或其他 driveItem 实例所做更改属于请求的更改类型时,发送更改通知。Change notifications are sent for the requested types of changes on the subscribed folder, or any file, folder, or other driveItem instances in its hierarchy. 无法订阅不是文件夹的“ 驱动器 ”或“ driveItem ”实例,例如单个文件。You cannot subscribe to drive or driveItem instances that are not folders, such as individual files.

联系人、事件和消息contact, event, and message

其他限制适用于 Outlook 项目的订阅。Additional limitations apply for subscriptions on Outlook items. 这些限制适用于订阅的创建和管理(获取、更新和删除)。The limitations apply to creating as well as managing (getting, updating, and deleting) subscriptions.

  • 委托的权限仅支持订阅已登录用户的邮箱内文件夹中的项。Delegated permission supports subscribing to items in folders in only the signed-in user's mailbox. 例如,不能使用委托的权限 Calendars.Read 来订阅另一个用户邮箱中的事件。For example, you cannot use the delegated permission Calendars.Read to subscribe to events in another user’s mailbox.

  • 订阅 共享或委托 文件夹中 Outlook 联系人、事件或邮件的更改通知:To subscribe to change notifications of Outlook contacts, events, or messages in shared or delegated folders:

    • 使用相应的应用程序权限订阅租户内 任何 用户的文件夹或邮箱中项目的更改。Use the corresponding application permission to subscribe to changes of items in a folder or mailbox of any user in the tenant.
    • 切勿使用 Outlook 共享权限(Contacts.Read.Shared、Calendars.Read.Shared、Mail.Read.Shared 及其相应的读写权限),因为它们 支持订阅对共享或委托文件夹中的项的更改通知。Do not use the Outlook sharing permissions (Contacts.Read.Shared, Calendars.Read.Shared, Mail.Read.Shared, and their read/write counterparts), as they do not support subscribing to change notifications on items in shared or delegated folders.

HTTP 请求HTTP request

GET /subscriptions/{id}

可选的查询参数Optional query parameters

此方法支持 OData 查询参数 来帮助自定义响应。This method supports the OData Query Parameters to help customize the response.

请求标头Request headers

名称Name 类型Type 说明Description
AuthorizationAuthorization stringstring Bearer {token}。必需。Bearer {token}. Required.

请求正文Request body

请勿提供此方法的请求正文。Do not supply a request body for this method.

响应Response

如果成功,此方法在响应正文中返回 200 OK 响应代码和 subscription 对象。If successful, this method returns a 200 OK response code and subscription object in the response body.

示例Example

请求Request

下面是一个请求示例。Here is an example of the request.

GET https://graph.microsoft.com/v1.0/subscriptions/{id}
响应Response

下面是一个响应示例。Here is an example of the response.

HTTP/1.1 200 OK
Content-type: application/json
Content-length: 252

{
  "id":"7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
  "resource":"me/messages",
  "applicationId" : "string",
  "changeType":"created,updated",
  "clientState":"secretClientValue",
  "notificationUrl":"https://webhook.azurewebsites.net/api/send/myNotifyClient",
  "lifecycleNotificationUrl":"https://webhook.azurewebsites.net/api/send/lifecycleNotifications",
  "expirationDateTime":"2016-11-20T18:23:45.9356913Z",
  "creatorId": "string",
  "latestSupportedTlsVersion": "v1_2",
  "encryptionCertificate": "",
  "encryptionCertificateId": "",
  "includeResourceData": false
}