使用 Microsoft Graph 获取团队和频道的更改通知

项目
09/09/2023

通过更改通知，可以订阅对团队和频道所做的更改（创建、更新和删除）。每当创建、更新或删除团队或频道时，你都可以收到通知。你还可以在通知中获取资源数据，因此避免调用 API 来获取有效负载。

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

注意

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

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

权限

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

示例

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

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

要获取与租户中特定团队相关的所有更改的更改通知，请订阅 /teams/{team-id}。此资源支持在通知中包括资源数据。

权限

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

注意： 带有 * 标记的权限作为资源特定的许可的一部分受到支持。

示例

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

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

若要获取与租户中的任何通道相关的所有更改 (创建、更新和删除) 的更改通知，请 /teams/getAllChannels订阅。此资源支持在通知中包括资源数据。

继续阅读本文，了解频道或聊天上下文的方案。或者，了解其他Microsoft Teams 资源的更改通知。

权限

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

示例

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

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

要获取与特定团队中任何频道相关的所有更改的更改通知，请订阅 /teams/{team-id}/channels。此资源支持在通知中包括资源数据。

下面是为此资源生成通知的事件示例：

频道显示名称在团队中更新。
在团队中创建专用频道。
此团队拥有的共享频道与其他团队共享或未共享。
另一个团队拥有的共享频道与该团队共享。
通道的属性（如 isFavoriteByDefault 或 description）已更新。
已删除频道。

注意： 对于委托上下文，只有授权用户才会收到专用/共享频道的通知。例如，除来宾) 之外属于团队 (的任何人都可以在委派上下文中订阅此资源，但只有有权访问专用频道和共享频道的用户才会收到有关这些频道中发生的事件的通知。

权限

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

注意： 带有 * 标记的权限作为资源特定的许可的一部分受到支持。

示例

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

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

包含资源数据的通知

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

{
    "value": [{
        "subscriptionId": "10493aa0-4d29-4df5-bc0c-ef742cc6cd7f",
        "changeType": "created",
        "clientState": "<<--SpecifiedClientState-->>",
        "subscriptionExpirationDateTime": "2021-02-02T10:30:34.9097561-08:00",
        "resource": "teams('fb82c19a-0f6d-41ed-90f0-cbb29a476ede')",
        "resourceData": {
            "id": "1612289765949",
            "@odata.type": "#Microsoft.Graph.Team",
            "@odata.id": "teams('fb82c19a-0f6d-41ed-90f0-cbb29a476ede')"
        },
        "encryptedContent": {
            "data": "<<--EncryptedContent-->",
            "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
            "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
            "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        },
        "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
    }],
    "validationTokens": ["<<--ValidationTokens-->>"]
}

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

注意：discoverySettings 和 classSettings 不会在有效负载数据中公开。

{
  "id": "4c533ad3-e1dd-4277-a672-92ab64ed225c",
  "createdDateTime": "2021-03-18T10:31:14.597Z",
  "displayName": "Sample name",
  "description": "Sample description",
  "internalId": "19:2077546f765a42c1ba71236f4df70aa2@thread.tacv2",
  "specialization": "none",
  "visibility": "public",
  "webUrl": "https://teams.microsoft.com/l/team/19:2077546f724a42c1ba71236f4df79aa2%40thread.tacv2/conversations?groupId=4c533ad3-e1dd-4277-a672-92ab64ed225c&tenantId=0f2e8f59-862a-483b-9ca8-82a10665e17d",
  "isArchived": false,
  "isMembershipLimitedToOwners": false,
  "memberSettings": {
    "allowCreateUpdateChannels": true,
    "allowCreatePrivateChannels": true,
    "allowDeleteChannels": true,
    "allowAddRemoveApps": true,
    "allowCreateUpdateRemoveTabs": true,
    "allowCreateUpdateRemoveConnectors": true
  },
  "guestSettings": {
    "allowCreateUpdateChannels": false,
    "allowDeleteChannels": false
  },
  "messagingSettings": {
    "allowUserEditMessages": true,
    "allowUserDeleteMessages": true,
    "allowOwnerDeleteMessages": true,
    "allowTeamMentions": true,
    "allowChannelMentions": true
  },
  "funSettings": {
    "allowGiphy": true,
    "giphyContentRating": "moderate",
    "allowStickersAndMemes": true,
    "allowCustomMemes": true
  }
}

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

{
    "value": [{
        "subscriptionId": "10493aa0-4d29-4df5-bc0c-ef742cc6cd7f",
        "changeType": "created",
        "clientState": "<<--SpecifiedClientState-->>",
        "subscriptionExpirationDateTime": "2021-02-02T10:30:34.9097561-08:00",
        "resource": "teams('fb82c19a-0f6d-41ed-90f0-cbb29a476ede')/channels('19:01f39f5ac52f45fb9a7ce01cedd57b1f@thread.tacv2')",
        "resourceData": {
            "id": "19:01f39f5ac52f45fb9a7ce01cedd57b1f@thread.tacv2",
            "@odata.type": "#Microsoft.Graph.Channel",
            "@odata.id": "teams('fb82c19a-0f6d-41ed-90f0-cbb29a476ede')/channels('19:01f39f5ac52f45fb9a7ce01cedd57b1f@thread.tacv2')"
        },
        "encryptedContent": {
            "data": "<<--EncryptedContent-->",
            "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
            "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
            "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        },
        "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
    }],
    "validationTokens": ["<<--ValidationTokens-->>"]
}

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

{
  "id": "19:a3f841d969cd4ae0a7cbe847fc10b371@thread.tacv2",
  "createdDateTime": "2020-02-14T01:10:03.592Z",
  "displayName": "General",
  "description": "Sample Channel description",
  "isFavoriteByDefault": true,
  "email": "",
  "webUrl": "https://teams.microsoft.com/l/channel/19%3Aa3f841d969cd4ae0a7cbe847fc10b371%40thread.tacv2/General?groupId=7ed9bdab-9c7d-4c10-a25d-3f4ff0e34577&tenantId=0f2d8f49-862a-493b-9ca8-82a10637e17d",
  "membershipType": "standard",
  "moderationSettings": null
}

不含资源数据的通知

不含资源数据的通知为你提供了足够的信息来进行 GET 调用以获取消息内容。没有资源数据的通知订阅不需要加密证书 (，因为 Microsoft Graph 不会) 发送实际资源数据。

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

{
  "subscriptionId": "9f9d1ed0-c9cc-42e7-8d80-a7fc4b0cda3c",
  "changeType": "created",
  "tenantId": "<<--TenantForWhichNotificationWasSent-->>",
  "clientState": "<<--SpecifiedClientState-->>",
  "subscriptionExpirationDateTime": "2021-02-02T11:26:41.0537895-08:00",
  "resource": "teams('fbe2bf47-16c8-47cf-b4a5-4b9b187c508b')",
  "resourceData": {
    "id": "1612293113399",
    "@odata.type": "#Microsoft.Graph.Teams",
    "@odata.id": "teams('fbe2bf47-16c8-47cf-b4a5-4b9b187c508b')"
  }
}

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

注意： 有效负载中不返回频道电子邮件地址。

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

{
  "id": "19:a3f841d969cd4ae0a7cbe847fc10b371@thread.tacv2",
  "createdDateTime": "2020-02-14T01:10:03.592Z",
  "displayName": "General",
  "description": "Sample Channel description",
  "isFavoriteByDefault": true,
  "email": "",
  "webUrl": "https://teams.microsoft.com/l/channel/19%3Aa3f841d969cd4ae0a7cbe847fc10b371%40thread.tacv2/General?groupId=7ed9bdab-9c7d-4c10-a25d-3f4ff0e34577&tenantId=0f2d8f49-862a-493b-9ca8-82a10637e17d",
  "membershipType": "standard",
  "moderationSettings": null
}

通过

使用 Microsoft Graph 获取团队和频道的更改通知

权限

示例

权限

示例

权限

示例

权限

示例

包含资源数据的通知

不含资源数据的通知

反馈

反馈

其他资源

通过

使用 Microsoft Graph 获取团队和频道的更改通知

订阅租户级别上任何团队中的更改

权限

示例

订阅特定团队中的更改

权限

示例

订阅租户级别上任何频道中的更改

权限

示例

订阅特定团队的任何频道中的更改

权限

示例

包含资源数据的通知

不含资源数据的通知

相关内容

反馈

反馈

其他资源