Получение уведомлений об изменениях для обновлений присутствия в Microsoft Teams

  • Статья

Уведомления об изменениях в Microsoft Graph позволяют подписаться на изменения в сведениях о присутствии пользователей в Microsoft Teams. Уведомления об изменениях предоставляют альтернативу опросу о присутствии с помощью API get presence и POST getPresencesByUserId .

Используйте веб-перехватчики, чтобы подписаться на сведения о присутствии пользователей и получать уведомления об изменениях. Общие сведения о веб-перехватчиках см. в разделе Уведомления об изменениях microsoft API Graph.

Разрешения

Тип разрешения Разрешения (в порядке повышения привилегий) Поддерживаемые версии
Делегированные (рабочая или учебная учетная запись) Presence.Read.All. Версия 1, бета-версия.
Делегированные (личная учетная запись Майкрософт) Не поддерживается. Не поддерживается.
Для приложений Не поддерживается. Не поддерживается.

Поддерживаемые ресурсы для присутствия

Максимальный срок действия подписок составляет час. Подписку можно продлить с помощью API обновления подписки до истечения срока ее действия или создать новую подписку для того же ресурса после истечения срока действия. Подписки присутствия поддерживают уведомления с данными ресурсов, позволяя доставлять более подробные сведения вместе с уведомлениями об изменениях. Дополнительные сведения см. в разделе Настройка уведомлений об изменениях с использованием данных ресурсов.

В следующей таблице перечислены типы изменений присутствия, на которые можно подписаться. Дополнительные сведения см. в разделе Создание подписки.

Тип подписки присутствия URL-адрес ресурса Поддерживаемые типы изменений
Изменения присутствия одного пользователя communications/presences/{id} Обновлено
Массовое изменение присутствия пользователей (не более 650 идентификаторов пользователей) communications/presences?$filter=id in ('{id}', '{id}', ...) Обновлено

Подписка на изменения присутствия

Чтобы подписаться на изменения присутствия, можно задать ресурсу в полезных данных communications/presences/{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} представляет идентификатор guid пользователей. В одной подписке можно подписаться не более 650 пользователей. Изменения присутствия для идентификаторов пользователей создают уведомление.

Пример. Полезные данные подписки присутствия нескольких пользователей

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

Получение уведомлений о событиях присутствия

Уведомления об изменениях для событий присутствия активируются при внесении изменений в доступность и действия пользователя.

Пример. Базовые уведомления о присутствии

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

Связанные материалы