通过

获取 Microsoft Teams 中状态更新的更改通知

  • 项目

Microsoft Graph 中的更改通知使你能够订阅 Microsoft Teams 中 用户状态 信息的更改。 更改通知提供了使用 GET 状态 和 POST getPresencesByUserId API 轮询状态的替代方法。

使用 Webhook 订阅用户的状态信息，并在发生更改时获取通知。 有关 Webhook 的一般信息，请参阅Microsoft图形 API更改通知。

注意

自 2024 年 6 月 30 日起，若要获取活动会议呼叫发生的更改，建议订阅 丰富通知。

权限

权限类型 权限（从最低特权到最高特权） 支持的版本
委派（工作或学校帐户） Presence.Read.All。 V1，beta 版。
委派（个人 Microsoft 帐户） 不支持。 不支持。
应用程序 不支持。 不支持。

支持的状态资源

单个用户可以为每个唯一应用程序创建一个状态订阅，最长过期时间为一小时。 订阅可以在过期前通过 更新订阅 API 进行续订，也可以在过期后为同一资源创建新订阅。 状态订阅支持包含资源数据的通知，允许传递更详细的信息以及更改通知。 有关详细信息，请参阅 使用资源数据设置更改通知。

下表列出了可订阅的状态更改类型。 有关详细信息，请参阅 创建订阅。

状态订阅类型 资源 URL 支持的更改类型
单用户状态更改 communications/presences/{id} 更新日期
批量用户状态更改 (最多 650 个用户 ID) communications/presences?$filter=id in ('{id}', '{id}', ...) 更新日期

订阅状态更改

若要订阅状态更改，可以将订阅有效负载 communications/presences/{id} 中的资源设置为 ，其中 {id} 字段必须替换为用户状态的用户 ID GUID。 当用户状态发生更改时，此订阅会发送更改通知。

true设置为 includeResourceData ，并为 encryptionCertificate 和 encryptionCertificateId 提供适当的值，以便订阅丰富通知。

示例：单用户状态订阅有效负载

{
    "changeType": "updated",
    "notificationUrl": "https://webhook.contoso.com/api",
    "lifecycleNotificationUrl": "https://webhook.contoso.com/api",
    "resource": "communications/presences/{id}",
    "expirationDateTime": "2023-09-14T10:00:00.0000000Z",
    "includeResourceData": true,
    "encryptionCertificate": "{encryption certificate}",
    "encryptionCertificateId": "{certificate id}",
    "clientState": "{secret client state}"
}

订阅多个用户的状态

可以通过将订阅资源值设置为 /communications/presences?$filter=id in ('{id}', '{id}',...)来创建用户状态的批量订阅，其中 {id} 表示用户的用户 ID GUID。 单个订阅中最多可以订阅 650 个用户。 用户 ID 的状态更改会生成通知。

示例：多个用户状态订阅有效负载

{
    "changeType": "updated",
    "notificationUrl": "https://webhook.contoso.com/api",
    "lifecycleNotificationUrl": "https://webhook.contoso.com/api",
    "resource": "/communications/presences?$filter=id in ('{id}', '{id}',...)",
    "expirationDateTime": "2023-09-14T10:00:00.0000000Z",
    "includeResourceData": true,
    "encryptionCertificate": "{encryption certificate}",
    "encryptionCertificateId": "{certificate id}",
    "clientState": "{secret client state}"
}

接收状态事件通知

更改用户的可用性和活动时，将触发状态事件的更改通知。

基本状态通知

基本通知通知订阅者有关已更改的资源的标识。 收到此信息时，应进行单独的 GET 调用以获取数据的详细信息。 对于基本状态通知，你会收到有关哪个用户的状态已更改的信息，但不会收到有关用户状态详细信息的数据。 可以使用 GET 状态 API 来发现用户的可用性和活动状态。

有效负载示例

{
  "value": [{
    "subscriptionId": "{Subscription id}",
    "clientState": "{secret client state}",
    "changeType": "updated",
    "tenantId": "{Organization/Tenant id}",
    "resource": "communications/presences/{id}",
    "subscriptionExpirationDateTime": "2023-09-14T10:00:00.0000000Z",
    "resourceData": {
      "@odata.id": "users/{User Id}/presence",
      "@odata.type": "#microsoft.graph.presence",
      "id": "{User Id}"
    },
    "organizationId": "{Organization/Tenant id}",
  }]
}

丰富状态通知

丰富通知通知订阅者有关资源发生更改的信息。 对于丰富状态通知，当用户和 中的 encryptedContent.data更改时AvailabilityActivity，订阅者会收到通知。 有关订阅富通知和解密数据的信息，请参阅 设置包含资源数据的更改通知。

注意

可用性和活动可以是相同的值。

有关可用性和活动可能组合的详细信息，请参阅 状态属性。

有效负载示例

{
  "value": [{
    "subscriptionId": "{Subscription id}",
    "clientState": "{secret client state}",
    "changeType": "updated",
    "tenantId": "{Organization/Tenant id}",
    "resource": "communications/presences/{id}",
    "subscriptionExpirationDateTime": "2023-09-14T10:00:00.0000000Z",
    "resourceData": {
      "@odata.id": "users/{User Id}/presence",
      "@odata.type": "#microsoft.graph.presence",
      "id": "{User Id}"
    },
    "organizationId": "{Organization/Tenant id}",
    "encryptedContent": {
      "data": "{Encrypted content}",
      "dataSignature": "{Encrypted data signature}",
      "dataKey": "{Encrypted data key for encrypting content}",
      "encryptionCertificateId": "{User specified id of encryption certificate}",
      "encryptionCertificateThumbprint": "{Encrpytion certification thumbprint}"
    }
  }],
  "validationTokens": ["{Validation Tokens}"]
}

示例：包含资源数据的解密通知

{
    "@odata.id": "users/{User Id}/presence",
    "@odata.type": "#microsoft.graph.presence",
    "id": "{User Id}",
    "availability": "{Availability}",
    "activity": "{Activity}"
}

相关内容