Abrufen von Änderungsbenachrichtigungen für Nachrichten in Teams-Kanälen und -Chats mithilfe von Microsoft Graph

  • Artikel

Änderungsbenachrichtigungen ermöglichen es Ihnen, Änderungen (Erstellen, Aktualisieren und Löschen) an Nachrichten in einem Kanal oder Chat zu abonnieren. Änderungsbenachrichtigungen bieten ein Modell mit geringer Wartezeit, da Sie ein Abonnement verwalten können. Sie können auch die Ressourcendaten mithilfe der Benachrichtigungen erhalten und müssen so nicht die API aufrufen, um die Nutzlast abzurufen.

Fahren Sie mit diesem Artikel zu Szenarien für die chatMessage-Ressource im Kanal - oder Chatkontext 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 auf der Mandantenebene

Um alle Änderungen im Zusammenhang mit Nachrichten in einem Mandanten nachzuverfolgen, können Sie Abonnements auf Mandantenebene für Kanal- und Chatnachrichten verwenden und zwei Abonnements erstellen: eines zum Nachverfolgen aller Nachrichten über Kanäle hinweg und eines zum Nachverfolgen aller Nachrichten über Chats hinweg.

Abonnieren von Nachrichten in allen Kanälen

Um Änderungsbenachrichtigungen für alle Nachrichten und Antworten in den Kanälen eines Mandanten zu erhalten, abonnieren Sie /teams/getAllMessages. Diese Ressource unterstützt das Einbeziehen von Ressourcendaten in die Benachrichtigung.

Hinweis: Diese API hat Lizenzierungs- und Zahlungsanforderungen. Sie unterstützt sowohl model=A- als auch model=B Abfrageparameter. 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 ChannelMessage.Read.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": "/teams/getAllMessages",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Abonnieren von Nachrichten in allen Chats

Wenn Sie Änderungsbenachrichtigungen für alle Nachrichten in allen Chats in einem Mandanten erhalten möchten, abonnieren Sie /chats/getAllMessages. Diese Ressource unterstützt das Einbeziehen von Ressourcendaten in die Benachrichtigung.

Hinweis: Diese API hat Lizenzierungs- und Zahlungsanforderungen. Sie unterstützt sowohl model=A- als auch model=B Abfrageparameter. 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.Read.All

Beispiel

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

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

Abonnieren von Nachrichten in einem Kanal

Um Nachrichten und Antworten in einem Kanal nachzuverfolgen /teams/{team-id}/channels/{channel-id}/messages, können Sie ein Änderungsbenachrichtigungsabonnement auf Kanalebene erstellen, indem Sie abonnieren. Diese Ressource unterstützt das Einschließen von Ressourcendaten in die Benachrichtigung sowohl im delegierten als auch im anwendungsbasierten Modus.

Abonnements auf Kanalebene unterstützen auch die schlüsselwortbasierte Suche über den $search-Abfrageparameter.

Berechtigungen

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

Hinweis: Mit * markierte Berechtigungen werden als Teil der ressourcenspezifischen Zustimmung unterstützt.

Beispiel 1: Abonnieren aller Nachrichten (und Antworten) in einem Kanal

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

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

Beispiel 2: Abonnieren von Nachrichten (und Antworten) in einem Kanal, die bestimmten Text enthalten

Die folgende Anforderung sendet Nachrichten, die enthalten, Hello an den Abonnenten.

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{team-id}/channels/{channel-id}/messages?$search=Hello",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Beispiel 3: Abonnieren von Nachrichten (und Antworten) in einem Kanal ohne Ressourcendaten

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{team-id}/channels/{channel-id}/messages",
  "includeResourceData": false,
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Beispiel 4: Abonnieren von Nachrichten (und Antworten) in einem Kanal, die einen bestimmten Benutzer enthalten

Wenn Sie Benachrichtigungen nur für Nachrichten erhalten möchten, in denen ein bestimmter Benutzer erwähnt wurde, können Sie die ID des Benutzers (9a6eb4d1-826b-48b1-9627-b50836c8fee9 in diesem Beispiel) in der Abfrage angeben.

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/teams/{team-id}/channels/{channel-id}/messages?$filter=mentions/any(u: u/mentioned/user/id eq '9a6eb4d1-826b-48b1-9627-b50836c8fee9')",
  "includeResourceData": false,
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Abonnieren von Nachrichten in einem Chat

Um Nachrichten in einem Chat nachzuverfolgen, können Sie ein Änderungsbenachrichtigungsabonnement auf Chatebene erstellen, indem Sie abonnieren /chats/{chat-id}/messages. Diese Ressource unterstützt das Einschließen von Ressourcendaten in die Benachrichtigung sowohl im delegierten als auch im anwendungsbasierten Modus.

Abonnements auf Chatebene unterstützen auch die schlüsselwortbasierte Suche über den $search-Abfrageparameter.

Berechtigungen

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

Hinweis: Mit * markierte Berechtigungen werden als Teil der ressourcenspezifischen Zustimmung aktuell nur für die Betaversion unterstützt.

Beispiel 1: Abonnieren von Nachrichten in einem Chat

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

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

Beispiel 2: Abonnieren von Nachrichten in einem Chat, die bestimmten Text enthalten

Die folgende Anforderung sendet Nachrichten, die enthalten, Hello an den Abonnenten.

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

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

Beispiel 3: Abonnieren von Nachrichten (und Antworten) in einem Chat ohne Ressourcendaten

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json
{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{chat-id}/messages",
  "includeResourceData": false,
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Beispiel 4: Abonnieren einer Nachricht in einem Chat, in der ein bestimmter Benutzer erwähnt wird

Wenn Sie Benachrichtigungen nur für Nachrichten erhalten möchten, in denen ein bestimmter Benutzer erwähnt wurde, können Sie die ID des Benutzers (9a6eb4d1-826b-48b1-9627-b50836c8fee9 in diesem Beispiel) in der Abfrage angeben.

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

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/api/resourceNotifications",
  "resource": "/chats/{chat-id}/messages?$filter=mentions/any(u: u/mentioned/user/id eq '9a6eb4d1-826b-48b1-9627-b50836c8fee9')",
  "includeResourceData": false,
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Änderungen auf Benutzerebene abonnieren

Um Nachrichten in allen Chats nachzuverfolgen, zu der ein bestimmter Benutzer gehört, können Sie ein Änderungsbenachrichtigungsabonnement auf Benutzerebene erstellen, indem Sie abonnieren /users/{user-id}/chats/getAllMessages. Diese Ressource unterstützt das Einschließen von Ressourcendaten in die Benachrichtigung sowohl im delegierten als auch im anwendungsbasierten Modus.

Chatnachrichtenabonnements auf Benutzerebene unterstützen auch die schlüsselwortbasierte Suche über den $search Abfrageparameter.

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) Chat.Read, Chat.ReadWrite
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt
Anwendung Chat.Read.All, Chat.ReadWrite.All

Beispiel: Nachrichten in allen Chats abonnieren, an denen ein bestimmter Benutzer teilnimmt.

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

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

Abonnieren von Nachrichten eines beliebigen Chats in einem Mandanten, in dem eine bestimmte Teams-App installiert ist

Um Änderungsbenachrichtigungen für alle Chatnachrichten in einem Mandanten zu erhalten, in dem eine bestimmte Teams-App installiert ist, abonnieren Sie /appCatalogs/teamsApps/{teams-app-id}/installedToChats/getAllMessages. 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.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/getAllMessages",
  "includeResourceData": true,
  "encryptionCertificate": "{base64encodedCertificate}",
  "encryptionCertificateId": "{customId}",
  "expirationDateTime": "2019-09-19T11:00:00.0000000Z",
  "clientState": "{secretClientState}"
}

Nutzdaten der Benachrichtigung

Je nach Abonnement können Sie die Benachrichtigung entweder mit Ressourcendaten erhalten oder ohne. Wenn Sie mit Ressourcendaten abonnieren, können Sie die Nutzdaten der Nachricht zusammen mit der Benachrichtigung erhalten, d. h. Sie müssen nicht mehr zurückrufen, um den Inhalt zu erhalten.

Benachrichtigungen mit Ressourcendaten

Bei Benachrichtigungen mit Ressourcendaten sieht die Nutzlast wie folgt aus. Diese Nutzlast gilt für eine Nachricht, die in einem Chat gesendet wurde.

{
    "value": [{
        "subscriptionId": "10493aa0-4d29-4df5-bc0c-ef742cc6cd7f",
        "changeType": "created",
        "clientState": "<<--SpecifiedClientState-->>",
        "subscriptionExpirationDateTime": "2021-02-02T10:30:34.9097561-08:00",
        "resource": "chats('19:8ea0e38b-efb3-4757-924a-5f94061cf8c2_97f62344-57dc-409c-88ad-c4af14158ff5@unq.gbl.spaces')/messages('1612289765949')",
        "resourceData": {
            "id": "1612289765949",
            "@odata.type": "#Microsoft.Graph.chatMessage",
            "@odata.id": "chats('19:8ea0e38b-efb3-4757-924a-5f94061cf8c2_97f62344-57dc-409c-88ad-c4af14158ff5@unq.gbl.spaces')/messages('1612289765949')"
        },
        "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 Schema chatMessage. Die Nutzlast ist der von GET-Vorgängen zurückgegebenen Nutzlast ähnlich.

{
  "id": "1612289992105",
  "replyToId": null,
  "etag": "1612289992105",
  "messageType": "message",
  "createdDateTime": "2021-02-02T18:19:52Z",
  "lastModifiedDateTime": "2021-02-02T18:19:52.105Z",
  "lastEditedDateTime": null,
  "deletedDateTime": null,
  "subject": null,
  "summary": null,
  "chatId": "19:8ea0e38b-efb3-4757-924a-5f94061cf8c2_97f62344-57dc-409c-88ad-c4af14158ff5@unq.gbl.spaces",
  "importance": "normal",
  "locale": "en-us",
  "webUrl": null,
  "from": {
    "application": null,
    "device": null,
    "user": {
      "id": "8ea0e38b-efb3-4757-924a-5f94061cf8c2",
      "displayName": "Ramjot Singh",
      "userIdentityType": "aadUser"
    },
    "conversation": null
  },
  "body": {
    "contentType": "text",
    "content": "test"
  },
  "channelIdentity": null,
  "attachments": [],
  "mentions": [],
  "policyViolation": null,
  "reactions": [],
  "replies": [],
  "hostedContents": []
}

Benachrichtigungen ohne Ressourcendaten

Benachrichtigungen ohne Ressourcendaten enthalten genügend Informationen, um GET-Aufrufe zu tätigen, um Nachrichteninhalte zu erhalten. Abonnements für Benachrichtigungen ohne Ressourcendaten erfordern kein Verschlüsselungszertifikat (da die tatsächlichen Ressourcendaten nicht gesendet werden).

Das Nutzlast sieht wie folgt aus. Diese Nutzlast gilt für eine Nachricht, die in einem Kanal gesendet wurde.

 {
  "subscriptionId": "9f9d1ed0-c9cc-42e7-8d80-a7fc4b0cda3c",
  "changeType": "created",
  "tenantId": "<<--TenantForWhichNotificationWasSent-->>",
  "clientState": "<<--SpecifiedClientState-->>",
  "subscriptionExpirationDateTime": "2021-02-02T11:26:41.0537895-08:00",
  "resource": "teams('fbe2bf47-16c8-47cf-b4a5-4b9b187c508b')/channels('19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2')/messages('1612293113399')",
  "resourceData": {
    "id": "1612293113399",
    "@odata.type": "#Microsoft.Graph.chatMessage",
    "@odata.id": "teams('fbe2bf47-16c8-47cf-b4a5-4b9b187c508b')/channels('19:4a95f7d8db4c4e7fae857bcebe0623e6@thread.tacv2')/messages('1612293113399')"
  }
}

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

Verwandte Inhalte