订阅资源类型
命名空间：microsoft.graph
重要
Microsoft Graph版本下的 /beta API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用，请使用 版本 选择器。
注意
应更新将此功能与 baseTask 或 baseTaskList 配合使用的现有应用，因为基于这些资源构建的待办 API 集自 2022 年 5 月 31 日起已弃用。 该 API 集将于 2022 年 8 月 31 日停止返回数据。 请使用 基于 todoTask 构建的 API 集。
借助订阅，客户端应用可以接收有关 Microsoft Graph 数据更改的变更通知。 目前，已为以下资源启用订阅。
注意 仅终结点支持使用星号 (*) 标记的
/beta订阅。
- Microsoft Graph 安全性 API 中的警报。
- Microsoft To Do.* 中已弃用用户的 baseTask () 。
- Microsoft Teams 中的通话或会议后生成的 callRecord。
- Microsoft Teams 中的 频道 。
- Microsoft Teams 中的 聊天 。
- 通过 Microsoft Teams 中的团队或频道发送的 chatMessage。
- Microsoft 365 组中的对话。
- 团队、频道或 Microsoft Teams 中聊天的 conversationMember 。
- OneDrive for Business 中根文件夹driveItem 的层次结构中的内容，或用户个人 OneDrive 中的根文件夹或子文件夹 driveItem 的层次结构中的内容。
- Azure Active Directory 中的 组。
- SharePoint site下的list。
- Outlook 中的邮件、事件或[联系人][]。
- Microsoft Teams 中的 联机会议 。*
- Microsoft Teams 中的用户 状态 。*
- Microsoft Teams 中的 团队 。
- 通用打印中的 打印机 (当打印机的打印作业进入 JobFetchable 状态 - 准备好提取以打印时)和 printTaskDefinition。有关详细信息，请参阅 订阅来自云打印 API 的更改通知。
- Microsoft 待办事项中用户的 todoTask 。
- 在 Azure Active Directory 中的 用户。
关于每个支持资源的可能资源路径值，请参阅使用 Microsoft Graph API 获取更改通知。 若要了解如何使用生命周期通知，请参阅“减少缺失的订阅和更改通知”。
方法
| 方法 | 返回类型 | 说明 |
|---|---|---|
| 创建订阅 | 订阅 | 订阅侦听器应用程序，在 Microsoft Graph 数据发生更改时接收变更通知。 |
| 更新订阅 | 订阅 | 通过更新订阅的过期时间来续订订阅。 |
| 列出订阅 | 订阅 | 列出有效订阅。 |
| 获取订阅 | 订阅 | 读取订阅对象的属性和关系。 |
| 删除订阅 | 无 | 删除订阅对象。 |
属性
| 属性 | 类型 | 说明 | 支持的资源 |
|---|---|---|---|
| applicationId | String | 可选。用于创建订阅的应用程序的标识符。只读。 | 全部 |
| changeType | 字符串 | 必填。指示订阅资源中将引发更改通知的更改类型。支持的值是：created、updated、deleted。可以使用以逗号分隔的列表组合多个值。注意： updated changeType。 updated 和 deleted changeType。 |
全部 |
| clientState | String | 可选。 指定服务在每个更改通知中发送 的 clientState 属性的值。 最大长度为 255 个字符。 客户端可以通过将发送的客户 端State 属性的值与每个更改通知中收到的 clientState 属性的值进行比较来检查更改通知是否来自服务。 | 全部 |
| creatorId | String | 可选。 已创建订阅的用户或服务主体的标识符。 如果应用使用委派的权限创建订阅，则此字段包含代表该应用调用的已登录用户的 ID。 如果应用使用了应用程序权限，则此字段包含与应用对应的服务主体的 ID。 只读。 | 全部 |
| encryptionCertificate | String | 可选。带有公钥的证书的 base64 编码表示形式(用于在更改通知中加密资源数据)。可选，但当 includeResourceData 为 true 时，为必需项。 |
全部 |
| encryptionCertificateId | String | 可选。 自定义应用提供的标识符，用于帮助识别解密资源数据所需的证书。 如果 includeResourceData 为 true. |
全部 |
| expirationDateTime | DateTimeOffset | 必需项。指定 Webhook 订阅的过期日期和时间。时间为 UTC，且可以是从订阅创建(因订阅资源而异)开始的一段时间。有关受支持的最大订阅时长，请参阅 下表。 | 全部 |
| id | String | 可选。订阅的唯一标识符。只读。 | 全部 |
| includeResourceData | 布尔值 | 可选。当设置为 true 时，更改通知 包含资源数据 (例如聊天消息的内容)。 |
全部 |
| latestSupportedTlsVersion | 字符串 | 可选。指定由 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 | 可选。 接收生命周期通知（包括 subscriptionRemoved 和 missed 通知）的终结点的 URL。 该 URL 必须使用 HTTPS 协议。 |
全部 |
| notificationContentType | String | 可选。 Microsoft Graph 所需的 内容类型 为更改支持的资源类型变更通知。 默认内容类型为 application/json。 |
全部 |
| notificationQueryOptions | String | 可选。 用于指定目标资源值的 OData 查询选项。 当资源达到与此处提供的查询选项匹配的状态时，客户端会收到通知。 借助订阅创建有效负载中的此新属性以及所有现有属性，每当资源达到 notificationQueryOptions 属性中提到的所需状态时，Webhook 就会提供通知。 例如，打印作业完成时或打印作业资源属性值 isFetchable 变为 true 等时。 |
通用打印服务 |
| notificationUrl | String | 必填。 接收更改通知的终结点的 URL。 该 URL 必须使用 HTTPS 协议。 | 全部 |
| notificationUrlAppId | String | 可选。 订阅服务可用于生成验证令牌的应用 ID。 这允许客户端验证收到的通知的真实性。 | 全部 |
| resource | 字符串 | 必填。 指定要被监视以进行更改的资源。 不包含的基 URL (https://graph.microsoft.com/beta/)。 查看各支持资源的可能资源路径值。 |
全部 |
每个资源类型的最长订阅有效期
| Resource | 最大过期时间 |
|---|---|
| 安全 警报 | 43200分钟（不到 30 天） |
| Teams callRecord | 4230 分钟（不到 3 天） |
| Teams 频道 | 60 分钟（1 小时） |
| Teams 聊天 | 60 分钟（1 小时） |
| Teams chatMessage | 60 分钟（1 小时） |
| Teams conversationMember | 60 分钟（1 小时） |
| Teams onlineMeeting | 4320 分钟 (3 天) |
| Teams 团队 | 60 分钟（1 小时） |
| 组 对话 | 4230 分钟（不到 3 天） |
| OneDrive driveItem | 42300 分钟（不到 30 天） |
| SharePoint 列表 | 42300 分钟（不到 30 天） |
| Outlook 邮件、事件、联系人 | 4230 分钟（不到 3 天） |
| 用户、组、其他目录资源 | 4230 分钟（不到 29 天） |
| onlineMeeting | 4230 分钟（不到 3 天） |
| 状态 | 60 分钟（1 小时） |
| 打印 打印机 | 4230 分钟（不到 3 天） |
| 打印 printTaskDefinition | 4230 分钟（不到 3 天） |
| todoTask | 4230 分钟（不到 3 天） |
| baseTask (已弃用) | 4230 分钟（不到 3 天） |
注意： 现有和新的应用都不得超过支持的这一上限值。 今后，任何超出最大值的订阅创建或续订请求都将失败。
关系
无。
JSON 表示形式
下面是资源的 JSON 表示形式。
{
"@odata.type": "#microsoft.graph.subscription",
"id": "String (identifier)",
"resource": "String",
"changeType": "String",
"clientState": "String",
"notificationUrl": "String",
"expirationDateTime": "String (timestamp)",
"applicationId": "String",
"creatorId": "String",
"includeResourceData": "Boolean",
"lifecycleNotificationUrl": "String",
"encryptionCertificate": "String",
"encryptionCertificateId": "String",
"latestSupportedTlsVersion": "String",
"notificationQueryOptions": "String",
"notificationContentType": "String",
"notificationUrlAppId": "String"
}
反馈
提交和查看相关反馈