Share via

使用 Microsoft Graph 获取聊天的更改通知

  • 项目

更改通知使你能够订阅聊天的更改（创建和更新）。 每当创建或更新 聊天 时，你都可以收到通知。 你还可以在通知中获取资源数据，因此避免调用 API 来获取有效负载。

继续阅读有关 聊天 资源方案的文章。 或者，了解 其他 Microsoft Teams 资源的更改通知。

注意

如果请求的订阅 expirationDateTime 在未来超过 1 小时，则必须通过在订阅请求中包含 lifecycleNotificationUrl 属性来订阅生命周期通知。 否则，订阅请求将失败并显示以下错误消息： 当 expirationDateTime 值设置为大于 1 小时时，lifecycleNotificationUrl 是在此资源上创建订阅所需的属性。

在租户级别订阅任何聊天中的更改

要获取与租户中任何聊天相关的所有更改（创建、更新和删除）的更改通知，请订阅 /chats。 此资源支持在通知中包括资源数据。

权限

权限类型 权限（从最低特权到最高特权）
委派（工作或学校帐户） 不支持。
委派（个人 Microsoft 帐户） 不支持。
Application Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All

示例

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

订阅特定聊天中的更改

要获取特定聊天相关的所有更改的更改通知，请订阅 /chats/{id}。 此资源支持在通知中包含 资源数据 ，并在用户上下文中 提供 notifyOnUserSpecificProperties 查询字符串参数 。

权限

权限类型 权限（从最低特权到最高特权）
委派（工作或学校帐户） Chat.ReadBasic, Chat.Read, Chat.ReadWrite
委派（个人 Microsoft 帐户） 不支持。
应用程序 ChatSettings.Read.Chat*、ChatSettings.ReadWrite.Chat*、Chat.Manage.Chat*、Chat.ReadBasic.All、Chat.Read.All、Chat.ReadWrite.All

注意：标有 * 的权限用于特定于资源的同意。

示例 1：订阅特定聊天中的更改

以下示例演示如何订阅以接收特定聊天中更改的通知。

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{id}",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

示例 2：使用 notifyOnUserSpecificProperties 查询参数订阅特定聊天中的更改 (预览)

以下示例演示如何通过提供 notifyOnUserSpecificProperties 查询参数来订阅以接收特定聊天中更改的通知。

POST https://graph.microsoft.com/beta/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{id}?notifyOnUserSpecificProperties=true",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2024-04-22T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

在用户级别订阅任何聊天更改 (预览)

若要获取特定用户所属的所有聊天中所有更改的更改通知，请订阅 /users/{user-id}/chats。 此资源支持在通知中包含 资源数据 ，并在用户上下文中 提供 notifyOnUserSpecificProperties 查询字符串参数 。

注意：此 API 具有许可和付款要求。 它支持 model=B 查询参数。 如果未指定模型，将使用评估模式。

权限

权限类型 权限（从最低特权到最高特权）
委派（工作或学校帐户） Chat.ReadBasic, Chat.Read, Chat.ReadWrite
委派（个人 Microsoft 帐户） 不支持。
Application Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All

示例 1：订阅用户级聊天中的更改

以下示例演示如何订阅特定用户所属的所有聊天中接收更改通知。

POST https://graph.microsoft.com/beta/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/users/456bbcdb-1e1c-4f3f-b7d0-ad7b9abcdefc/chats",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2024-04-22T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

示例 2：使用路径订阅用户级聊天中的 me 更改

以下示例演示如何订阅以在已登录用户所属的所有聊天中接收更改通知。

POST https://graph.microsoft.com/beta/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/me/chats",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2024-04-22T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

示例 3：使用 notifyOnUserSpecificProperties 查询参数订阅用户级聊天中的更改

以下示例演示如何通过提供 notifyOnUserSpecificProperties 查询参数，订阅在特定用户所属的所有聊天中接收更改通知。

POST https://graph.microsoft.com/beta/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/users/456bbcdb-1e1c-4f3f-b7d0-ad7b9abcdefc/chats?notifyOnUserSpecificProperties=true",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2024-04-22T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

订阅安装了 Teams 应用的租户中任何聊天中的更改

若要获取与安装了特定 Teams 应用的租户中的任何聊天相关的所有更改通知，请 /appCatalogs/teamsApps/{teams-app-id}/installedToChats订阅 。 此资源支持在通知中包括资源数据。

注意：此 API 具有许可和付款要求。 它支持 model=B 查询参数。 如果未指定模型，将使用评估模式。

权限

权限类型 权限（从最低特权到最高特权）
委派（工作或学校帐户） 不支持。
委派（个人 Microsoft 帐户） 不支持。
应用程序 Chat.ReadBasic.WhereInstalled、Chat.Read.WhereInstalled、Chat.ReadWrite.WhereInstalled

示例

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/appCatalogs/teamsApps/386bbcdb-1e1c-4f3f-b7d0-ad7b9ea6cf7c/installedToChats",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

通知有效负载

包含资源数据的通知

对于包含资源数据的通知，负载如下所示。 此有效负载用于聊天中的属性更改。

{
    "value": [{
        "subscriptionId": "352887e3-9be0-4b6f-a4e6-dec118d857db",
        "changeType": "Created",
        "clientState": "<<--SpecifiedClientState-->>",
        "subscriptionExpirationDateTime": "2021-06-03T09:50:37.719033+00:00",
        "resource": "chats('19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces')",
        "resourceData": {
            "id": "19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces",
            "@odata.type": "#microsoft.graph.chat",
            "@odata.id": "chats('19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces')"
        },
        "EncryptedContent": {
            "data": "<<--EncryptedContent-->>",
            "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
            "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
            "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        }
            "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
        }],
    "validationTokens": ["<<--ValidationTokens-->>"]
}

有关如何验证令牌和解密负载的详细信息，请参阅设置包含资源数据的更改通知。

解密的通知负载如下所示。 有效负载符合 聊天 架构。 该负载类似于 GET 操作返回的负载。

{
  "id": "19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces",
  "topic": null,
  "createdDateTime": "2021-06-03T14:25:04+05:30",
  "lastUpdatedDateTime": "2021-06-03T14:25:04.387Z",
  "chatType": "oneOnOne",
  "webUrl": "https://teams.microsoft.com/l/chat/19%3A1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438%40unq.gbl.spaces/0?tenantId=27d53d29-3606-45dd-bc86-a532f3f38b8c",
  "tenantId": "2432b57b-0abd-43db-aa7b-16eadd115d34",
  "isHiddenForAllMembers": false,
  "lastMessagePreview": null,
  "onlineMeetingInfo": null,
  "members": [
    {
      "userId": "976f4b31-fd01-4e0b-9178-29cc40c14438",
      "email": null,
      "tenantId": "2432b57b-0abd-43db-aa7b-16eadd115d34",
      "id": "MCMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOToxMjczYTAxNi0yMDFkLTRmOTUtODA4My0xYjdmOTliM2VkZWJfOTc2ZjRiMzEtZmQwMS00ZTBiLTkxNzgtMjljYzQwYzE0NDM4QHVucS5nYmwuc3BhY2VzIyM5NzZmNGIzMS1mZDAxLTRlMGItOTE3OC0yOWNjNDBjMTQ0Mzg=",
      "roles": [],
      "displayName": null,
      "visibleHistoryStartDateTime": "1970-01-01T00:00:00Z",
      "user": null
    },
    {
      "userId": "ee723d3d-22d0-4394-9c32-5764d68f4672",
      "email": null,
      "tenantId": "2432b57b-0abd-43db-aa7b-16eadd115d34",
      "id": "MCMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOToxMjczYTAxNi0yMDFkLTRmOTUtODA4My0xYjdmOTliM2VkZWJfOTc2ZjRiMzEtZmQwMS00ZTBiLTkxNzgtMjljYzQwYzE0NDM4QHVucS5nYmwuc3BhY2VzIyNlZTcyM2QzZC0yMmQwLTQzOTQtOWMzMi01NzY0ZDY4ZjQ2NzI=",
      "roles": [],
      "displayName": null,
      "visibleHistoryStartDateTime": "1970-01-01T00:00:00Z",
      "user": null
    }
  ],
  "messages": [],
  "installedApps": [],
  "tabs": [],
  "permissionGrants": [],
  "operations": [],
  "assignedSensitivityLabel": null,
  "pinnedMessages": []
}

用户特定属性的通知有效负载

如果在创建订阅期间向查询字符串参数 notifyOnUserSpecificProperties 提供值 true ，则会向订阅服务器发送两种类型的具有不同信息集的有效负载。 一种类型包含特定于用户的属性;另一个不包含特定于用户的属性。

注意：查询字符串参数 notifyOnUserSpecificProperties 仅支持用户上下文中的聊天订阅，特别是特定聊天或用户级别的订阅。

以下有效负载描述了请求中包含用户特定属性的通知中发送的信息。 有效负载包含 聊天 架构中的一部分属性，包括具有非 null 值的 views 属性，特定于订阅用户。 从 聊天 架构中省略其他属性并不意味着其值发生任何更改。

注意：当用户在 Teams 客户端中隐藏聊天时，他们会收到一条带有 isHidden: true观点 属性的通知;但是，当聊天在新消息到达后再次可见时，不会发送带有 的通知 isHidden: false 。 若要确定聊天是否不再隐藏，订阅者必须将观点属性中的 lastMessageReadDateTime 与新消息的 createdDateTime 进行比较。 如果 createdDateTime 晚于 lastMessageReadDateTime，则聊天可见。 订阅者必须具有活动订阅才能接收有关聊天中消息的 更改通知 ，以便收到隐藏聊天中新消息的通知。 当用户随后打开聊天并阅读新消息时，将发送通知，并在isHidden: false“观点”属性中更新了 lastMessageReadDateTime。

{
  "id": "19:a1d516d162d441f38cd474916913c806@thread.v2",
  "topic": "Feature Crew",
  "createdDateTime": "2024-04-22T15:14:04.624Z",
  "lastUpdatedDateTime": "2024-04-23T14:37:53.87Z",
  "chatType": "group",
  "tenantId": "27d53d29-3606-45dd-bc86-a532f3f38b8c",
  "viewpoint": {
    "isHidden": false,
    "lastMessageReadDateTime": "2024-04-22T15:18:59.228Z"
  }
}

以下有效负载描述了请求中发送的通知中不包含用户特定属性的信息。 有效负载不包括 视点 属性;但是，这种情况并不表示用户更改其值。

{
  "id": "19:2a81219665e6448da23022ddb949f693@thread.v2",
  "topic": "Group chat",
  "createdDateTime": "2024-04-22T15:02:57Z",
  "lastUpdatedDateTime": "2024-04-23T14:55:20.545Z",
  "chatType": "group",
  "webUrl": "https://teams.microsoft.com/l/chat/19%3A2a81219665e6448da23022ddb949f693%40thread.v2/0?tenantId=27d53d29-3606-45dd-bc86-a532f3f38b8c",
  "tenantId": "27d53d29-3606-45dd-bc86-a532f3f38b8c",
  "isHiddenForAllMembers": false,
  "lastMessagePreview": null,
  "onlineMeetingInfo": null,
  "members": [
    {
      "@odata.type": "#microsoft.graph.aadUserConversationMember",
      "userId": "4595d2f2-7b31-446c-84fd-9b795e63114b",
      "email": null,
      "tenantId": "27d53d29-3606-45dd-bc86-a532f3f38b8c",
      "id": "id",
      "roles": [
        "owner"
      ],
      "displayName": null,
      "visibleHistoryStartDateTime": "0001-01-01T00:00:00Z",
      "user": null
    },
    {
      "@odata.type": "#microsoft.graph.aadUserConversationMember",
      "userId": "7d898072-792c-4006-bb10-5ca9f2590649",
      "email": null,
      "tenantId": "27d53d29-3606-45dd-bc86-a532f3f38b8c",
      "id": "id",
      "roles": [
        "owner"
      ],
      "displayName": null,
      "visibleHistoryStartDateTime": "0001-01-01T00:00:00Z",
      "user": null
    },
    {
      "@odata.type": "#microsoft.graph.aadUserConversationMember",
      "userId": "c27c1b19-3904-4822-9813-4f6bdaab2eae",
      "email": null,
      "tenantId": "27d53d29-3606-45dd-bc86-a532f3f38b8c",
      "id": "id",
      "roles": [
        "owner"
      ],
      "displayName": null,
      "visibleHistoryStartDateTime": "0001-01-01T00:00:00Z",
      "user": null
    }
  ],
  "messages": [],
  "installedApps": [],
  "tabs": [],
  "permissionGrants": [],
  "operations": [],
  "assignedSensitivityLabel": null,
  "pinnedMessages": []
}

不含资源数据的通知

以下解密的有效负载描述了在请求通知中发送的信息，而没有资源数据。 此特定有效负载表示已创建新的聊天。

{
  "subscriptionId": "8d85051d-779d-45bc-be92-e433f0a5d8ac",
  "changeType": "Created",
  "tenantId": "<<--TenantForWhichNotificationWasSent-->>",
  "clientState": "<<--SpecifiedClientState-->>",
  "subscriptionExpirationDateTime": "2021-06-03T10:26:09.8959595+00:00",
  "resource": "chats('19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces')",
  "resourceData": {
    "id": "19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces",
    "@odata.type": "#microsoft.graph.chat",
    "@odata.id": "chats('19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces')"
  }
}

resource 和 @odata.id 属性可用于对 Microsoft Graph 进行调用以获取消息详细信息负载。 GET 调用始终返回聊天详细信息的当前状态。 如果在发送通知和检索聊天详细信息之间更新了聊天详细信息，则操作将返回更新的聊天详细信息。

相关内容