Freigeben über

Abrufen von Änderungsbenachrichtigungen für Chats mithilfe von Microsoft Graph

  • Artikel

Mit Änderungsbenachrichtigungen können Sie Änderungen (erstellen und aktualisieren) an Chats abonnieren. Sie können benachrichtigt werden, wenn ein Chat erstellt oder aktualisiert wird. Sie können auch die Ressourcendaten in den Benachrichtigungen erhalten und müssen so nicht die API aufrufen, um die Nutzlast abzurufen.

Fahren Sie mit diesem Artikel zu Szenarien für die Chatressource fort. Oder informieren Sie sich über Änderungsbenachrichtigungen für andere Microsoft Teams-Ressourcen.

Hinweis

Wenn Sie ein abonnement expirationDateTime anfordern, das mehr als eine Stunde in der Zukunft liegt, müssen Sie Lebenszyklusbenachrichtigungen abonnieren, indem Sie eine lifecycleNotificationUrl-Eigenschaft in Ihre Abonnementanforderung einschließen. Andernfalls schlägt Ihre Abonnementanforderung mit der folgenden Fehlermeldung fehl: lifecycleNotificationUrl ist eine erforderliche Eigenschaft für die Abonnementerstellung für diese Ressource, wenn der wert expirationDateTime auf größer als 1 Stunde festgelegt ist.

Abonnieren von Änderungen für jeden Chat auf Mandantenebene

Um Änderungsbenachrichtigungen für alle Änderungen (erstellen und aktualisieren) in Bezug auf einen beliebigen Chat auf einem Mandanten zu erhalten, abonnieren Sie /chats. Diese Ressource unterstützt das Einbeziehen von Ressourcendaten in die Benachrichtigung.

Berechtigungen

Berechtigungstyp Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)
Delegiert (Geschäfts-, Schul- oder Unikonto) Nicht unterstützt
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt
Anwendung Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All

Beispiel

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

Abonnieren von Änderungen in einem bestimmten Chat

Um Änderungsbenachrichtigungen für alle Änderungen in Bezug auf einen bestimmten Chat zu erhalten, abonnieren Sie /chats/{id}. Diese Ressource unterstützt das Einschließen von Ressourcendaten in die Benachrichtigung und das Bereitstellen des Abfragezeichenfolgenparameters notifyOnUserSpecificProperties im Benutzerkontext.

Berechtigungen

Berechtigungstyp Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)
Delegiert (Geschäfts-, Schul- oder Unikonto) Chat.ReadBasic, Chat.Read, Chat.ReadWrite
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt
Anwendung ChatSettings.Read.Chat*, ChatSettings.ReadWrite.Chat*, Chat.Manage.Chat*, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All

Hinweis: Mit * markierte Berechtigungen verwenden ressourcenspezifische Zustimmung.

Beispiel 1: Abonnieren von Änderungen in einem bestimmten Chat

Das folgende Beispiel zeigt, wie Sie abonnieren, um Benachrichtigungen über Änderungen in einem bestimmten Chat zu erhalten.

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

Beispiel 2: Abonnieren von Änderungen in einem bestimmten Chat mithilfe des Abfrageparameters notifyOnUserSpecificProperties

Das folgende Beispiel zeigt, wie Sie abonnieren, um Benachrichtigungen über Änderungen in einem bestimmten Chat zu erhalten, indem Sie den abfrageparameter notifyOnUserSpecificProperties angeben.

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

Abonnieren von Änderungen in einem beliebigen Chat auf Benutzerebene (Vorschau)

Um Änderungsbenachrichtigungen für alle Änderungen in allen Chats zu erhalten, zu der ein bestimmter Benutzer gehört, abonnieren Sie /users/{user-id}/chats. Diese Ressource unterstützt das Einschließen von Ressourcendaten in die Benachrichtigung und das Bereitstellen des Abfragezeichenfolgenparameters notifyOnUserSpecificProperties im Benutzerkontext.

Berechtigungen

Berechtigungstyp Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)
Delegiert (Geschäfts-, Schul- oder Unikonto) Chat.ReadBasic, Chat.Read, Chat.ReadWrite
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt
Anwendung Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All

Beispiel 1: Abonnieren von Änderungen in Chats auf Benutzerebene

Das folgende Beispiel zeigt, wie Sie abonnieren, um Benachrichtigungen über Änderungen in allen Chats zu erhalten, zu der ein bestimmter Benutzer gehört.

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

Beispiel 2: Abonnieren von Änderungen in Chats auf Benutzerebene mithilfe des me Pfads

Das folgende Beispiel zeigt, wie Sie abonnieren, um Benachrichtigungen über Änderungen in allen Chats zu erhalten, zu der der angemeldete Benutzer gehört.

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

Beispiel 3: Abonnieren von Änderungen in Chats auf Benutzerebene mithilfe des Abfrageparameters notifyOnUserSpecificProperties

Das folgende Beispiel zeigt, wie Sie abonnieren, um Benachrichtigungen über Änderungen in allen Chats zu erhalten, zu der ein bestimmter Benutzer gehört, indem Sie den abfrageparameter notifyOnUserSpecificProperties angeben.

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

Abonnieren von Änderungen in einem Beliebigen Chat in einem Mandanten, in dem eine Teams-App installiert ist

Um Änderungsbenachrichtigungen für alle Änderungen im Zusammenhang mit einem Chat in einem Mandanten zu erhalten, in dem eine bestimmte Teams-App installiert ist, abonnieren /appCatalogs/teamsApps/{teams-app-id}/installedToChatsSie . Diese Ressource unterstützt das Einbeziehen von Ressourcendaten in die Benachrichtigung.

Hinweis: Diese API hat Lizenzierungs- und Zahlungsanforderungen. Sie unterstützt den Abfrageparameter model=B. Wenn kein Modell angegeben ist, wird der Auswertungsmodus verwendet.

Berechtigungen

Berechtigungstyp Berechtigungen (von der Berechtigung mit den wenigsten Rechten zu der mit den meisten Rechten)
Delegiert (Geschäfts-, Schul- oder Unikonto) Nicht unterstützt
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt
Anwendung Chat.ReadBasic.WhereInstalled, Chat.Read.WhereInstalled, Chat.ReadWrite.WhereInstalled

Beispiel

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

Nutzlast der Benachrichtigung

Benachrichtigungen mit Ressourcendaten

Bei Benachrichtigungen mit Ressourcendaten sieht die Nutzlast wie folgt aus. Dies Nutzlast bezieht sich auf eine Eigenschaftsänderung in einem Chat.

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

Einzelheiten zum Validieren von Tokens und Entschlüsseln der Nutzlast finden Sie unter Änderungsbenachrichtigungen einrichten, die Ressourcendaten enthalten.

Die entschlüsselte Benachrichtigungsnutzlast sieht wie folgt aus. Die Nutzlast entspricht dem Chats-Schema. Die Nutzlast ist der von GET-Vorgängen zurückgegebenen Nutzlast ähnlich.

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

Benachrichtigungsnutzlasten für benutzerspezifische Eigenschaften

Wenn Sie den Abfragezeichenfolgenparameter notifyOnUserSpecificProperties während der Abonnementerstellung mit einem Wert true angeben, werden zwei Arten von Nutzlasten mit unterschiedlichen Informationssätzen an den Abonnenten gesendet. Ein Typ enthält benutzerspezifische Eigenschaften. die andere enthält keine benutzerspezifischen Eigenschaften.

Hinweis: Der Abfragezeichenfolgenparameter notifyOnUserSpecificProperties wird nur für Chatabonnements im Benutzerkontext unterstützt, insbesondere für Abonnements für einen bestimmten Chat oder auf Benutzerebene.

Die folgende Nutzlast beschreibt die Informationen, die in einer Anforderung für Benachrichtigungen gesendet werden, die benutzerspezifische Eigenschaften enthalten. Die Nutzlast enthält eine Teilmenge der Eigenschaften aus dem Chatschema , einschließlich der Viewpoint-Eigenschaft mit einem Wert ungleich NULL, der für den abonnierenden Benutzer spezifisch ist. Das Auslassen anderer Eigenschaften aus dem Chatschema impliziert keine Änderung ihrer Werte.

Hinweis: Wenn ein Benutzer einen Chat im Teams-Client ausblendet, erhält er eine Benachrichtigung mit isHidden: true in der Eigenschaft "Viewpoint ". Es wird jedoch keine Benachrichtigung mit isHidden: false gesendet, wenn der Chat wieder sichtbar wird, nachdem eine neue Nachricht eingetroffen ist. Um festzustellen, ob der Chat nicht mehr ausgeblendet ist, muss der Abonnent lastMessageReadDateTime in der Eigenschaft "viewpoint " mit dem createdDateTime der neuen Nachricht vergleichen. Wenn createdDateTime später als lastMessageReadDateTime ist, ist der Chat sichtbar. Der Abonnent muss über ein aktives Abonnement verfügen, um Änderungsbenachrichtigungen zu Nachrichten im Chat zu erhalten, um über neue Nachrichten in einem ausgeblendeten Chat benachrichtigt zu werden. Wenn der Benutzer dann den Chat öffnet und die neue Nachricht liest, wird eine Benachrichtigung mit isHidden: false und einer aktualisierten lastMessageReadDateTime in der eigenschaft viewpoint gesendet.

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

Die folgende Nutzlast beschreibt die Informationen, die in einer Anforderung für Benachrichtigungen gesendet werden, die keine benutzerspezifischen Eigenschaften enthalten. Die Nutzlast enthält nicht die Eigenschaft "viewpoint ". Diese Situation impliziert jedoch keine Änderung des Werts für den Benutzer.

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

Benachrichtigungen ohne Ressourcendaten

Die folgende entschlüsselte Nutzlast beschreibt die Informationen, die in einer Anforderung für Benachrichtigungen ohne Ressourcendaten gesendet werden. Diese spezielle Nutzlast bedeutet, dass ein neuer Chat erstellt wurde.

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

Die Eigenschaften ressource und @odata.id können verwendet werden, um Aufrufe an Microsoft Graph zu tätigen, um die Nutzlast für die Chatdetails zu erhalten. GET-Anrufe geben immer den aktuellen Status der Chatdetails zurück. Wenn die Chatdetails zwischen dem Senden der Benachrichtigung und dem Abrufen der Chatdetails aktualisiert wurden, gibt der Vorgang die aktualisierten Chatdetails zurück.

Verwandte Inhalte