Share via

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

  • 项目

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

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

权限

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

支持的状态资源

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

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

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

订阅状态更改

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

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

{
    "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}"
}

接收状态事件通知

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

示例：基本状态通知

注意

由于基本通知仅包含已更改的资源的 ID，因此需要对 Microsoft Graph 进行单独的 GET 状态调用才能访问用户状态数据。 有关详细信息，请参阅 GET 状态。

{
  "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}",
  }]
}

示例：包含资源数据的状态通知

包含资源数据的状态通知在有效负载中加密了以下附加属性：

  • 可用性或基本状态信息 (可用、离开、忙碌)
  • 在会议、通话) 中对可用性 (补充的活动或信息

[注意]：可用性和活动可以是相同的值。

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

{
  "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}"
}

相关内容