Feedback Bearbeiten

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

  • Artikel
  • 6 Minuten Lesedauer

Ä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.

Abonnieren von Änderungen auf der Mandantenebene

Um alle Änderungen nachzuverfolgen, die mit Nachrichten in einem Mandanten verbunden sind, können Sie Abonnements auf Mandantenebene für Kanal- und Chatnachrichten verwenden. Dazu müssen Sie zwei Abonnements erstellen: eines zum Nachverfolgen aller Nachrichten in allen Kanälen und eines zum Nachverfolgen aller Nachrichten in allen Chats.

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

Wenn Sie Nachrichten und Antworten in einem Kanal nachverfolgen möchten, können Sie ein Änderungsbenachrichtigungsabonnement auf Kanalebene erstellen. Abonnieren Sie dazu /teams/{team-id}/channels/{channel-id}/messages. 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 mit dem Inhalt 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

Wenn Sie Nachrichten in einem Chat nachverfolgen möchten, können Sie ein Änderungsbenachrichtigungsabonnement auf Chatebene erstellen. Abonnieren Sie dazu /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 mit dem Inhalt 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 zu verfolgen, an denen ein bestimmter Benutzer teilnimmt, können Sie ein Abonnement für Änderungsbenachrichtigungen auf Benutzerebene erstellen. Um dies zu tun, abonnieren Sie /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}"
}

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 übermittelt 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 der aktuelle 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.

Siehe auch