订阅资源类型
命名空间：microsoft.graph
表示允许客户端应用接收有关 Microsoft Graph 中数据更改的更改通知的订阅。
有关订阅和更改通知（包括支持更改通知的资源）的详细信息，请参阅 设置资源数据更改通知。
方法
| 方法 | 返回类型 | Description |
|---|---|---|
| List | 订阅 | 列出有效订阅。 |
| 创建 | 订阅 | 订阅侦听器应用程序，在 Microsoft Graph 数据发生更改时接收变更通知。 |
| Get | 订阅 | 读取 subscription 对象的属性和关系。 |
| 更新 | 订阅 | 汇报续订的订阅到期时间和/或更新 notificationUrl 以供传递。 |
| 删除 | 无 | 删除订阅对象。 |
| 重新授权 | None | 收到重新授权要求质询时 重新授权 订阅。 |
属性
| 属性 | 类型 | 说明 |
|---|---|---|
| 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 时间，可以是距离订阅创建的一段时间（因订阅资源不同而异）。 有关支持的订阅最长时间长度，请参阅 订阅生存期。 |
| 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 资源;可选，否则为 。 接收生命周期通知的终结点的 URL，包括 subscriptionRemoved、 reauthorizationRequired和 missed 通知。 该 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 | 字符串 | 必填。 指定监视更改的资源。 不要 () https://graph.microsoft.com/v1.0/ 包含基 URL。 查看各支持资源的可能资源路径值。 |
订阅生命周期
订阅的生命周期有限。 应用需要在过期时间之前续订其订阅;否则，他们需要创建新订阅。 应用还可以随时取消订阅，以停止接收更改通知。
下表显示了 Microsoft Graph 中每个资源订阅的最大过期时间。
| Resource | 最大过期时间 |
|---|---|
| 安全警报 | 30 天内 (43,200 分钟) |
| Teams 审批 | 30 天内 (43,200 分钟) |
| Teams callRecord | 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 | 4,320 分钟 (3 天) |
| Teams Shifts offerShiftRequest | 360 分钟 (6 小时) |
| Teams Shifts openShiftChangeRequest | 360 分钟 (6 小时) |
| 团队班 次班次 | 360 分钟 (6 小时) |
| Teams 班次 swapShiftsChangeRequest | 360 分钟 (6 小时) |
| Teams Shifts timeOffRequest | 360 分钟 (6 小时) |
| 组对话 | 4,230 分钟 (不到三天) |
| OneDrive driveItem | 42,300 分钟 (不到 30 天) |
| SharePoint 列表 | 42,300 分钟 (不到 30 天) |
| Outlook 邮件、事件、联系人 | 7 天内 (10,080 分钟) |
| 用户、组、其他目录资源 | 29 天内 (41,760 分钟) |
| onlineMeeting | 4,230 分钟 (不到三天) |
| 状态 | 60 分钟（1 小时） |
| 打印 打印机 | 4,230 分钟 (不到三天) |
| 打印 printTaskDefinition | 4,230 分钟 (不到三天) |
| todoTask | 4,230 分钟 (不到三天) 此资源的 Webhook 仅在全局终结点中可用，而不能在国家云中使用。 |
| baseTask (已弃用) | 4,230 分钟 (不到三天) |
注意：现有和新的应用都不得超过支持的这一上限值。 今后，任何超出最大值的订阅创建或续订请求都将失败。
延迟
下表列出了服务中发生的事件与传递更改通知之间的预计延迟时间。
| 资源 | 平均延迟 | 最大延迟 |
|---|---|---|
| 警报1 | 少于 3 分钟 | 5 分钟 |
| 批准 | 少于 10 秒 | 40 秒 |
| calendar | 小于 1 分钟 | 3 分钟 |
| callRecord | 少于 15 分钟 | 60 分钟 |
| callRecording | 少于 10 秒 | 60 分钟 |
| callTranscript | 少于 10 秒 | 60 分钟 |
| 频道 | 少于 10 秒 | 60 分钟 |
| 聊天 | 少于 10 秒 | 60 分钟 |
| chatMessage | 少于 10 秒 | 1 分钟 |
| 联系人 | 小于 1 分钟 | 3 分钟 |
| 对话 | 未知 | 未知 |
| conversationMember | 少于 10 秒 | 60 分钟 |
| driveItem | 小于 1 分钟 | 5 分钟 |
| 事件 | 未知 | 未知 |
| 组 | 未知 | 未知 |
| 列表 | 小于 1 分钟 | 5 分钟 |
| 邮件 | 小于 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 分钟 |
| 用户 | 未知 | 未知 |
1 为 警报 资源提供的延迟仅在创建警报后适用。 它不包括规则根据数据创建警报所需的时间。
关系
无。
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"
}