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

Получение уведомлений об изменениях чатов с помощью Microsoft Graph

  • Статья

Уведомления об изменениях позволяют подписаться на изменения (создание и обновление) чатов. Вы можете получать уведомления при создании или обновлении чата . Кроме того, вы можете получать данные ресурсов в уведомлениях и, следовательно, избегать вызова API, чтобы получить полезные данные.

Перейдите к этой статье о сценариях для ресурса чата . Вы также можете узнать об уведомлениях об изменениях для других ресурсов Microsoft Teams.

Примечание.

Если вы запрашиваете срок действия подпискиDateTime , который в будущем превышает 1 час, необходимо подписаться на уведомления о жизненном цикле, включив свойство lifecycleNotificationUrl в запрос подписки. В противном случае запрос подписки завершится ошибкой со следующим сообщением об ошибке: lifecycleNotificationUrl является обязательным свойством для создания подписки на этом ресурсе, если значение expirationDateTime имеет значение больше 1 часа.

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

Чтобы получать уведомления обо всех изменениях (создание и обновление), связанных с любым чатом в клиенте, подпишитесь на /chats. Этот ресурс поддерживает включение данных ресурса в уведомление.

Разрешения

Тип разрешения Разрешения (в порядке повышения привилегий)
Делегированные (рабочая или учебная учетная запись) Не поддерживается.
Делегированные (личная учетная запись Майкрософт) Не поддерживается.
Сервер приложений Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All

Пример

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

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

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

Чтобы получать уведомления обо всех изменениях, связанных с определенным чатом, подпишитесь на /chats/{id}. Этот ресурс поддерживает включение данных ресурсов в уведомление и предоставление параметра строки запроса notifyOnUserSpecificProperties в контексте пользователя.

Разрешения

Тип разрешения Разрешения (в порядке повышения привилегий)
Делегированные (рабочая или учебная учетная запись) Chat.ReadBasic, Chat.Read, Chat.ReadWrite
Делегированные (личная учетная запись Майкрософт) Не поддерживается.
Приложение ChatSettings.Read.Chat*, ChatSettings.ReadWrite.Chat*, Chat.Manage.Chat*, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All

Примечание. Разрешения, помеченные звездочкой (*), используют согласие для конкретных ресурсов.

Пример 1. Подписка на изменения в определенном чате

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

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

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

Пример 2. Подписка на изменения в конкретном чате с помощью параметра запроса notifyOnUserSpecificProperties

В следующем примере показано, как подписаться на получение уведомлений об изменениях в конкретном чате, указав параметр запроса notifyOnUserSpecificProperties .

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

{
  "changeType": "updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{id}?notifyOnUserSpecificProperties=true",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2024-04-22T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Подписка на изменения в любом чате на уровне пользователя (предварительная версия)

Чтобы получать уведомления об изменениях во всех чатах, в которые входит конкретный пользователь, подпишитесь на /users/{user-id}/chats. Этот ресурс поддерживает включение данных ресурсов в уведомление и предоставление параметра строки запроса notifyOnUserSpecificProperties в контексте пользователя.

Разрешения

Тип разрешения Разрешения (в порядке повышения привилегий)
Делегированные (рабочая или учебная учетная запись) Chat.ReadBasic, Chat.Read, Chat.ReadWrite
Делегированные (личная учетная запись Майкрософт) Не поддерживается.
Сервер приложений Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All

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

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

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/users/456bbcdb-1e1c-4f3f-b7d0-ad7b9abcdefc/chats",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2024-04-22T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Пример 2. Подписка на изменения в чатах уровня пользователя с помощью me пути

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

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/me/chats",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2024-04-22T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Пример 3. Подписка на изменения в чатах уровня пользователя с помощью параметра запроса notifyOnUserSpecificProperties

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

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/users/456bbcdb-1e1c-4f3f-b7d0-ad7b9abcdefc/chats?notifyOnUserSpecificProperties=true",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2024-04-22T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Подписка на изменения в любом чате в клиенте, где установлено приложение Teams

Чтобы получать уведомления об изменениях, связанных с любым чатом в клиенте, где установлено определенное приложение Teams, подпишитесь на /appCatalogs/teamsApps/{teams-app-id}/installedToChats. Этот ресурс поддерживает включение данных ресурса в уведомление.

Примечание. К этому API применяются требования лицензирования и оплаты. Он поддерживает параметр запроса model=B. Если модель не указана, будет использоваться режим оценки.

Разрешения

Тип разрешения Разрешения (в порядке повышения привилегий)
Делегированные (рабочая или учебная учетная запись) Не поддерживается.
Делегированные (личная учетная запись Майкрософт) Не поддерживается.
Приложение Chat.ReadBasic.WhereInstalled, Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled

Пример

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/appCatalogs/teamsApps/386bbcdb-1e1c-4f3f-b7d0-ad7b9ea6cf7c/installedToChats",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Полезные данные уведомлений

Уведомления с данными ресурсов

Для уведомлений с данными ресурсов полезные данные выглядят следующим образом. Эти полезные данные относятся к изменению свойства в чате.

{
    "value": [{
        "subscriptionId": "352887e3-9be0-4b6f-a4e6-dec118d857db",
        "changeType": "Created",
        "clientState": "<<--SpecifiedClientState-->>",
        "subscriptionExpirationDateTime": "2021-06-03T09:50:37.719033+00:00",
        "resource": "chats('19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces')",
        "resourceData": {
            "id": "19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces",
            "@odata.type": "#microsoft.graph.chat",
            "@odata.id": "chats('19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces')"
        },
        "EncryptedContent": {
            "data": "<<--EncryptedContent-->>",
            "dataKey": "<<--EnryptedDataKeyUsedForEncryptingContent-->>",
            "encryptionCertificateId": "<<--IdOfTheCertificateUsedForEncryptingDataKey-->>",
            "encryptionCertificateThumbprint": "<<--ThumbprintOfTheCertificateUsedForEncryptingDataKey-->>"
        }
            "tenantId": "<<--TenantForWhichNotificationWasSent-->>"
        }],
    "validationTokens": ["<<--ValidationTokens-->>"]
}

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

Расшифрованные полезные данные уведомления выглядят следующим образом. Полезные данные соответствуют схеме chats. Полезные данные похожи на результаты, возвращаемые операциями GET.

{
  "id": "19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces",
  "topic": null,
  "createdDateTime": "2021-06-03T14:25:04+05:30",
  "lastUpdatedDateTime": "2021-06-03T14:25:04.387Z",
  "chatType": "oneOnOne",
  "webUrl": "https://teams.microsoft.com/l/chat/19%3A1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438%40unq.gbl.spaces/0?tenantId=27d53d29-3606-45dd-bc86-a532f3f38b8c",
  "tenantId": "2432b57b-0abd-43db-aa7b-16eadd115d34",
  "isHiddenForAllMembers": false,
  "lastMessagePreview": null,
  "onlineMeetingInfo": null,
  "members": [
    {
      "userId": "976f4b31-fd01-4e0b-9178-29cc40c14438",
      "email": null,
      "tenantId": "2432b57b-0abd-43db-aa7b-16eadd115d34",
      "id": "MCMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOToxMjczYTAxNi0yMDFkLTRmOTUtODA4My0xYjdmOTliM2VkZWJfOTc2ZjRiMzEtZmQwMS00ZTBiLTkxNzgtMjljYzQwYzE0NDM4QHVucS5nYmwuc3BhY2VzIyM5NzZmNGIzMS1mZDAxLTRlMGItOTE3OC0yOWNjNDBjMTQ0Mzg=",
      "roles": [],
      "displayName": null,
      "visibleHistoryStartDateTime": "1970-01-01T00:00:00Z",
      "user": null
    },
    {
      "userId": "ee723d3d-22d0-4394-9c32-5764d68f4672",
      "email": null,
      "tenantId": "2432b57b-0abd-43db-aa7b-16eadd115d34",
      "id": "MCMjMjQzMmI1N2ItMGFiZC00M2RiLWFhN2ItMTZlYWRkMTE1ZDM0IyMxOToxMjczYTAxNi0yMDFkLTRmOTUtODA4My0xYjdmOTliM2VkZWJfOTc2ZjRiMzEtZmQwMS00ZTBiLTkxNzgtMjljYzQwYzE0NDM4QHVucS5nYmwuc3BhY2VzIyNlZTcyM2QzZC0yMmQwLTQzOTQtOWMzMi01NzY0ZDY4ZjQ2NzI=",
      "roles": [],
      "displayName": null,
      "visibleHistoryStartDateTime": "1970-01-01T00:00:00Z",
      "user": null
    }
  ],
  "messages": [],
  "installedApps": [],
  "tabs": [],
  "permissionGrants": [],
  "operations": [],
  "assignedSensitivityLabel": null,
  "pinnedMessages": []
}

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

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

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

В следующей полезных данных описываются сведения, отправляемые в запросе на уведомления, содержащие свойства пользователя. Полезные данные содержат подмножество свойств из схемы чата , включая свойство точки просмотра со значением, не имеющим значения NULL, специфичным для подписывающего пользователя. Пропуск других свойств из схемы чата не означает никаких изменений в их значениях.

Примечание. Когда пользователь скрывает чат в клиенте Teams, он получает уведомление с isHidden: true в свойстве точки просмотра , однако уведомление с isHidden: false не отправляется, когда чат снова становится видимым после поступления нового сообщения. Чтобы определить, не скрыт ли чат, подписчик должен сравнить lastMessageReadDateTime в свойстве viewpoint с createdDateTime нового сообщения. Если параметр createdDateTime является более поздним, чем lastMessageReadDateTime, чат отображается. Подписчик должен иметь активную подписку для получения уведомлений об изменениях сообщений в чате, чтобы получать уведомления о новых сообщениях в скрытом чате. Когда пользователь открывает чат и читает новое сообщение, отправляется уведомление с isHidden: false и обновленным lastMessageReadDateTime в свойстве точки просмотра .

{
  "id": "19:a1d516d162d441f38cd474916913c806@thread.v2",
  "topic": "Feature Crew",
  "createdDateTime": "2024-04-22T15:14:04.624Z",
  "lastUpdatedDateTime": "2024-04-23T14:37:53.87Z",
  "chatType": "group",
  "tenantId": "27d53d29-3606-45dd-bc86-a532f3f38b8c",
  "viewpoint": {
    "isHidden": false,
    "lastMessageReadDateTime": "2024-04-22T15:18:59.228Z"
  }
}

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

{
  "id": "19:2a81219665e6448da23022ddb949f693@thread.v2",
  "topic": "Group chat",
  "createdDateTime": "2024-04-22T15:02:57Z",
  "lastUpdatedDateTime": "2024-04-23T14:55:20.545Z",
  "chatType": "group",
  "webUrl": "https://teams.microsoft.com/l/chat/19%3A2a81219665e6448da23022ddb949f693%40thread.v2/0?tenantId=27d53d29-3606-45dd-bc86-a532f3f38b8c",
  "tenantId": "27d53d29-3606-45dd-bc86-a532f3f38b8c",
  "isHiddenForAllMembers": false,
  "lastMessagePreview": null,
  "onlineMeetingInfo": null,
  "members": [
    {
      "@odata.type": "#microsoft.graph.aadUserConversationMember",
      "userId": "4595d2f2-7b31-446c-84fd-9b795e63114b",
      "email": null,
      "tenantId": "27d53d29-3606-45dd-bc86-a532f3f38b8c",
      "id": "id",
      "roles": [
        "owner"
      ],
      "displayName": null,
      "visibleHistoryStartDateTime": "0001-01-01T00:00:00Z",
      "user": null
    },
    {
      "@odata.type": "#microsoft.graph.aadUserConversationMember",
      "userId": "7d898072-792c-4006-bb10-5ca9f2590649",
      "email": null,
      "tenantId": "27d53d29-3606-45dd-bc86-a532f3f38b8c",
      "id": "id",
      "roles": [
        "owner"
      ],
      "displayName": null,
      "visibleHistoryStartDateTime": "0001-01-01T00:00:00Z",
      "user": null
    },
    {
      "@odata.type": "#microsoft.graph.aadUserConversationMember",
      "userId": "c27c1b19-3904-4822-9813-4f6bdaab2eae",
      "email": null,
      "tenantId": "27d53d29-3606-45dd-bc86-a532f3f38b8c",
      "id": "id",
      "roles": [
        "owner"
      ],
      "displayName": null,
      "visibleHistoryStartDateTime": "0001-01-01T00:00:00Z",
      "user": null
    }
  ],
  "messages": [],
  "installedApps": [],
  "tabs": [],
  "permissionGrants": [],
  "operations": [],
  "assignedSensitivityLabel": null,
  "pinnedMessages": []
}

Уведомления без данных ресурса

В следующей расшифрованной полезных данных описываются сведения, отправляемые в запросе на уведомления без данных ресурса. Эти конкретные полезные данные означают, что создан новый чат.

{
  "subscriptionId": "8d85051d-779d-45bc-be92-e433f0a5d8ac",
  "changeType": "Created",
  "tenantId": "<<--TenantForWhichNotificationWasSent-->>",
  "clientState": "<<--SpecifiedClientState-->>",
  "subscriptionExpirationDateTime": "2021-06-03T10:26:09.8959595+00:00",
  "resource": "chats('19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces')",
  "resourceData": {
    "id": "19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces",
    "@odata.type": "#microsoft.graph.chat",
    "@odata.id": "chats('19:1273a016-201d-4f95-8083-1b7f99b3edeb_976f4b31-fd01-4e0b-9178-29cc40c14438@unq.gbl.spaces')"
  }
}

Свойства resource и @odata.id можно использовать для вызовов в Microsoft Graph, чтобы получить полезные данные сведений о чате. Вызовы GET всегда возвращают текущее состояние сведений о чате. Если сведения о чате были обновлены между отправкой уведомления и получением сведений о чате, операция возвращает обновленные сведения о чате.

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