订阅资源类型

  • 项目

命名空间：microsoft.graph

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

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

方法

方法 返回类型 说明
列出订阅 订阅 列出有效订阅。
创建订阅 订阅 订阅侦听器应用程序，在 Microsoft Graph 数据发生更改时接收变更通知。
获取订阅 订阅 读取 subscription 对象的属性和关系。
更新订阅 订阅 汇报续订的订阅到期时间和/或更新 notificationUrl 以供传递。
删除订阅 无 删除订阅对象。
重新授权 无 收到重新授权要求质询时 重新授权 订阅。

属性

属性 类型 说明
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 callRecord 4,230 分钟 (不到 3 天)
    Teams callRecording 4,320 分钟 (3 天)
    Teams callTranscript 4,320 分钟 (3 天)
    Teams 频道 4,320 分钟 (3 天)
    Teams 聊天 4,320 分钟 (3 天)
    Teams chatMessage 4,320 分钟 (3 天)
    Teams conversationMember 4,320 分钟 (3 天)
    Teams onlineMeeting 4,320 分钟 (3 天)
    Teams 团队 4,320 分钟 (3 天)
    组对话 4,230 分钟 (不到 3 天)
    OneDrive driveItem 42,300 分钟 (不到 30 天)
    SharePoint 列表 42,300 分钟 (不到 30 天)
    Outlook 邮件、事件、联系人 4,230 分钟 (不到 3 天)
    用户、组、其他目录资源 29 天内 (41,760 分钟)
    onlineMeeting 4,230 分钟 (不到 3 天)
    状态 60 分钟（1 小时）
    打印 打印机 4,230 分钟 (不到 3 天)
    打印 printTaskDefinition 4,230 分钟 (不到 3 天)
    todoTask 4,230 分钟 (不到 3 天)

    此资源的 Webhook 仅在全局终结点中可用，而不能在国家云中使用。
    baseTask (已弃用) 4,230 分钟 (不到 3 天)

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

    延迟

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

    资源 平均延迟 最大延迟
    警报1 少于 3 分钟 5 分钟
    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 分钟
    onlineMeeting 少于 10 秒 1 分钟
    状态 少于 10 秒 1 分钟
    打印机 小于 1 分钟 5 分钟
    printTaskDefinition 小于 1 分钟 5 分钟
    团队 少于 10 秒 60 分钟
    todoTask 少于 2 分钟 15 分钟
    用户 少于 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"
}