订阅资源类型

命名空间：microsoft.graph

表示允许客户端应用接收有关 Microsoft Graph 中数据更改的更改通知的订阅。

有关订阅和更改通知（包括支持更改通知的资源）的更多信息，请参阅为资源数据中的更改设置通知。

方法

方法	返回类型	Description
List	订阅	列出有效订阅。
创建	订阅	订阅侦听器应用程序，在 Microsoft Graph 数据发生更改时接收变更通知。每次订阅资源发生更改时，Microsoft Graph 都会向应用发送至少一个 changeNotificationCollection 对象。
Get	订阅	读取 subscription 对象的属性和关系。
更新	订阅	汇报订阅到期时间以进行续订和/或更新 notificationUrl 以进行传递。
删除	无	删除订阅对象。
重新授权	无	收到 reauthorizationRequired 质询时重新授权订阅。
获取 VAPID	String	获取自愿应用程序服务器标识 (VAPID) 公钥，以便根据 RFC 8292 创建订阅。

属性

属性	类型	说明
applicationId	String	可选。用于创建订阅的应用程序的标识符。只读。
changeType	字符串	必填。指示已订阅资源中引发更改通知的更改类型。支持的值是：`created`、`updated`、`deleted`。可以使用以逗号分隔的列表组合多个值。注意：驱动器根项和列表变更通知仅支持 `updated` changeType。用户和组的变更通知支持 `updated` 和 `deleted` changeType。用于 `updated` 在创建、更新或软删除用户或组时接收通知。用于 `deleted` 在永久删除用户或组时接收通知。
clientState	String	可选。指定服务为每个变更通知发送的 `clientState` 属性的值。最大长度为 128 个字符。通过对比与订阅一起发送的 `clientState` 属性值和与每个变更通知一起接收的 `clientState` 属性值，客户端可以检查变更通知是否是由服务发送。
creatorId	String	可选。已创建订阅的用户或服务主体的标识符。如果应用使用委派的权限创建订阅，则此字段将包含应用代表调用的已登录用户的 ID。如果应用使用了应用程序权限，则此字段包含与应用对应的服务主体的 ID。只读。
encryptionCertificate	String	可选。带有公钥的证书的base64 编码表示形式，用于对更改通知中的资源数据进行加密。可选，但在 includeResourceData 是 `true` 时是必需的。
encryptionCertificateId	String	可选。自定义应用提供的标识符，用于帮助识别解密资源数据所需的证书。
expirationDateTime	DateTimeOffset	必需。指定 webhook 订阅过期的日期和时间。时间为 UTC 时间，可以是距离订阅创建的一段时间（因订阅资源不同而异）。请求时间后 45 分钟内的任何值都将自动设置为请求时间后 45 分钟。有关支持的最长订阅时间长度，请参阅订阅生存期。
id	String	可选。订阅的唯一标识符。只读。
includeResourceData	布尔值	可选。设置为 `true` 时，更改通知包括资源数据（例如聊天消息的内容）。
latestSupportedTlsVersion	String	可选。指定由 notificationUrl指定的通知端点支持的 "传输层安全性 (TLS)" 的最新版本。可能的值包括 `v1_0`、`v1_1`、`v1_2`、`v1_3`。对于通知终结点支持低于当前建议版本 TLS 1.2) 版本 (订阅者，通过一组时间线指定此属性将允许他们在完成升级到 TLS 1.2 之前暂时使用其已弃用的 TLS 版本。对于这些订阅者，不按时间线设置此属性会导致订阅操作失败。对于通知终结点已支持 TLS 1.2 的订阅者，设置此属性是可选的。在这种情况下，Microsoft Graph 将属性默认设置为 `v1_2`。
lifecycleNotificationUrl	String	如果值是距现在起 1 个小时以上，则 `expirationDateTime` 对于 Teams 资源是必需的;否则为可选。接收生命周期通知（包括 `subscriptionRemoved`、 `reauthorizationRequired`和 `missed` 通知）的终结点的 URL。该 URL 必须使用 HTTPS 协议。有关详细信息，请参阅减少缺少的订阅和更改通知。
notificationQueryOptions	String	可选。用于指定目标资源值的 OData 查询选项。当资源达到与此处所提供的查询选项相匹配的状态时，客户端会收到通知。通过订阅创建有效负载中的此新属性以及所有现有属性，每当资源达到 notificationQueryOptions 属性中所述的所需状态时，Webhook 就会发送通知。例如，打印作业完成时或打印作业资源属性值 `isFetchable` 变为 `true` 等时。仅通用打印服务支持。有关详细信息，请参阅使用 Microsoft Graph 订阅来自云打印 API 的更改通知。
notificationUrl	String	必填。接收更改通知的终结点的 URL。该 URL 必须使用 HTTPS 协议。当 Microsoft Graph 发送更改通知时，notificationUrl 属性中包含的任何查询字符串参数都包含在 HTTP POST 请求中。
notificationUrlAppId	String	可选。订阅服务可用于生成验证令牌的应用 ID。该值允许客户端验证接收到的通知的真实性。
resource	字符串	必填。指定监视更改的资源。不要包含基 URL (`https://graph.microsoft.com/v1.0/`) 。查看各支持资源的可能资源路径值。
vapidPublicKey	String	可选。应用程序服务器的 VAPID 公钥，base64url 编码 (P-256 未压缩点，65 字节预编码) 。通过调用订阅集合上的 getVapidPublicKey 函数获取。浏览器将此值传递给 `PushManager.subscribe({ applicationServerKey: vapidPublicKey })` ，以将推送订阅绑定到此服务器标识。如果在标准 Webhook 订阅中提供，则 notificationUrl 以已知的 Web 推送服务源 (`*.push.apple.com`例如、 `fcm.googleapis.comupdates.push.services.mozilla.com` 、) ;拒绝时`400 Bad Request`需要。有关更多信息，请参阅 RFC 8292。
webPushEncryptionP256dhPublicKey	String	可选。订阅者的 ECDH 公钥，base64url 编码 (P-256 未压缩点，65 字节预编码) 。通过从浏览器 `PushSubscription.getKey('p256dh')`获取。在 ECDH 密钥协议期间用作对等公钥，以派生 RFC 8291 有效负载加密的每消息内容加密密钥。当 notificationUrl 以已知的 Web 推送服务源为目标时需要;如果在标准 Webhook 订阅中提供，则拒绝。`400 Bad Request` 有关详细信息，请参阅 RFC 8291 第 3 节。
webPushEncryptionSecret	String	可选。订阅者的身份验证机密，base64url 编码 (16 字节预编码) 。通过从浏览器 `PushSubscription.getKey('auth')`获取。用作 HKDF 组合步骤的 HMAC-SHA-256 盐，该步骤派生 RFC 8291 有效负载加密的密钥材料。只写：此值永远不会在 GET 响应中返回 (作为) 返回 `null` 。视为机密。当 notificationUrl 以已知的 Web 推送服务源为目标时需要;如果在标准 Webhook 订阅中提供，则拒绝。`400 Bad Request` 有关详细信息，请参阅 RFC 8291 第 3 节。

订阅生命周期

订阅的生命周期有限。应用需要在到期时间之前续订其订阅;否则，他们需要创建新的订阅。应用还可以随时取消订阅，以停止接收更改通知。

此外，expirationDateTime 设置为请求时间后 45 分钟以下的任何请求都将自动设置为请求时间后 45 分钟。

下表显示了 Microsoft Graph 中每个资源的订阅的最大到期时间。

Resource	最大过期时间
Copilot aiInteraction	三天) (4,320 分钟
安全警报	43,200 分钟 (30 天以下)
Teams 审批	43,200 分钟 (30 天以下)
Teams callRecord	3 天) 内 (4,230 分钟
Teams callRecording	三天) (4,320 分钟
Teams callTranscript	三天) (4,320 分钟
Teams 频道	三天) (4,320 分钟
Teams 聊天	三天) (4,320 分钟
Teams chatMessage	三天) (4,320 分钟
Teams conversationMember	三天) (4,320 分钟
Teams onlineMeeting	三天) (4,320 分钟
Teams 团队	三天) (4,320 分钟
Teams teamsAppInstallation	3 天) (4,320 分钟
Teams 排班 offerShiftRequest	360 分钟 (6 小时)
Teams 排班 openShiftChangeRequest	360 分钟 (6 小时)
Teams 排班	360 分钟 (6 小时)
Teams 排班 swapShiftsChangeRequest	360 分钟 (6 小时)
Teams 排班 timeOffRequest	360 分钟 (6 小时)
组对话	3 天) 内 (4,230 分钟
OneDrive driveItem	30 天内 (42,300 分钟)
SharePoint 列表	30 天内 (42,300 分钟)
Outlook 邮件、事件、联系人	7 天内 (10,080 分钟) 对于包含资源数据 (丰富通知订阅) 的订阅，订阅生存期为 1440 分钟 (不到一天) 。
用户、组、其他目录资源	41,760 分钟 (29 天)
onlineMeeting	3 天) 内 (4,230 分钟
状态	60 分钟（1 小时）
打印打印机	3 天) 内 (4,230 分钟
打印 printTaskDefinition	3 天) 内 (4,230 分钟
todoTask	3 天) 内 (4,230 分钟此资源的 Webhook 仅在全球终结点中可用，在国家云中不可用。
Microsoft Entra 运行状况监视警报	30 天内 (42,300 分钟)
baseTask (已弃用)	3 天) 内 (4,230 分钟

注意：现有和新的应用都不得超过支持的这一上限值。今后，任何超出最大值的订阅创建或续订请求都将失败。

延迟

下表列出了服务中发生的事件与传递更改通知之间的预计延迟时间。

资源	平均延迟	最大延迟
aiInteraction	少于 10 秒	60 分钟
警报¹	少于 3 分钟	5 分钟
审批	少于 10 秒	40 秒
calendar	小于 1 分钟	3 分钟
callRecord²	不到 30 分钟	150 分钟
callRecording	少于 10 秒	60 分钟
callTranscript	少于 10 秒	60 分钟
频道	少于 10 秒	60 分钟
聊天	少于 10 秒	60 分钟
chatMessage	少于 10 秒	1 分钟
联系人	小于 1 分钟	3 分钟
对话	未知	未知
conversationMember	少于 10 秒	60 分钟
driveItem	小于 1 分钟	6 小时
事件	未知	未知
组	未知	未知
运行状况监视警报	未知	未知
列表	小于 1 分钟	6 小时
邮件	小于 1 分钟	3 分钟
offerShiftRequest	小于 1 分钟	60 分钟
onlineMeeting	少于 10 秒	1 分钟
openShiftChangeRequest	小于 1 分钟	60 分钟
状态	少于 10 秒	1 分钟
打印机	小于 1 分钟	5 分钟
printTaskDefinition	小于 1 分钟	5 分钟
shift	小于 1 分钟	60 分钟
swapShiftsChangeRequest	小于 1 分钟	60 分钟
团队	少于 10 秒	60 分钟
teamsAppInstallation	少于 10 秒	60 分钟
timeOffRequest	小于 1 分钟	60 分钟
todoTask	少于 2 分钟	15 分钟
用户	未知	未知

¹ 为警报资源提供的延迟仅在警报创建后适用。它不包括规则根据数据创建警报所需的时间。 ² 为 callRecord 资源提供的延迟仅适用于调用记录的第一个版本。通话记录的后续版本可能会在超出规定的延迟时间之后更新。

关系

无。

JSON 表示形式

以下 JSON 表示形式显示资源类型。

{
  "@odata.type": "#microsoft.graph.subscription",
  "applicationId": "String",
  "changeType": "String",
  "clientState": "String",
  "creatorId": "String",
  "encryptionCertificate": "String",
  "encryptionCertificateId": "String",
  "expirationDateTime": "String (timestamp)",
  "id": "String (identifier)",
  "includeResourceData": "Boolean",
  "latestSupportedTlsVersion": "String",
  "lifecycleNotificationUrl": "String",
  "notificationQueryOptions": "String",
  "notificationUrl": "String",
  "notificationUrlAppId": "String",
  "resource": "String",
  "vapidPublicKey": "String",
  "webPushEncryptionP256dhPublicKey": "String",
  "webPushEncryptionSecret": "String"
}

反馈

此页面是否有帮助？

上次更新时间为 2026-09-17

订阅资源类型

方法

属性

订阅生命周期

延迟

关系

JSON 表示形式

反馈

其他资源