Поделиться через

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

  • Статья

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

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

Примечание.

Начиная с 30 июня 2024 г. для получения изменений, произошедших в активном вызове собрания, рекомендуется подписаться на расширенные уведомления.

Разрешения

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

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

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

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

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

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

Чтобы подписаться на изменения присутствия, можно задать ресурсу в полезных данных communications/presences/{id} подписки, где поле {id} должно быть заменено идентификатором GUID присутствия пользователя. Эта подписка отправляет уведомления об изменениях при изменении присутствия пользователя.

Задайте значение includeResourceDatatrue и укажите соответствующие значения для encryptionCertificateIdencryptionCertificate и для подписки на расширенные уведомления.

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

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

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

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

Основные уведомления о присутствии

Базовые уведомления уведомляют подписчиков об идентификаторе ресурса, который изменился. При получении этих сведений необходимо выполнить отдельный вызов GET, чтобы получить сведения о данных. Для базовых уведомлений о присутствии вы получаете сведения о том, какое присутствие пользователя изменилось, но нет данных о присутствии пользователя. Api присутствия 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}",
  }]
}

Расширенные уведомления о присутствии

Расширенные уведомления уведомляют подписчиков об изменениях, произошедших с ресурсом. Для расширенных уведомлений о присутствии подписчики получают уведомления о том, что пользователь Availability и Activity меняется в encryptedContent.data. Сведения о подписке на расширенные уведомления и расшифровке данных см. в статье Настройка уведомлений об изменениях, включающих данные ресурсов.

Примечание.

Доступность и действие могут иметь одно и то же значение.

Дополнительные сведения о возможных сочетаниях доступности и действий см. в разделе Свойства присутствия.

Пример полезных данных

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

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