Einrichten von Benachrichtigungen für Änderungen an Ressourcendaten

Änderungsbenachrichtigungen ermöglichen Es Anwendungen, Warnungen zu erhalten, wenn eine Microsoft Graph-Ressource an Änderungen interessiert ist. d. h. erstellt, aktualisiert oder gelöscht wird. Microsoft Graph sendet Benachrichtigungen an den angegebenen Clientendpunkt, und der Clientdienst verarbeitet die Benachrichtigungen gemäß den Geschäftsanforderungen. Der Dienst kann z. B. weitere Daten abrufen, seinen Cache und seine Ansichten aktualisieren usw.

Warum sollte ich Änderungsbenachrichtigungen erhalten?

Änderungsbenachrichtigungen folgen einem ereignisgesteuerten Modell, bei dem Kunden Warnungen erhalten, wenn Änderungen auftreten, anstatt Microsoft Graph abzurufen. Abhängig von Ihrer Geschäftslogik sind Änderungsbenachrichtigungen in folgenden Fällen geeignet:

  • Sie abonnieren eine Ressource, die häufig geändert wird.
  • Sie müssen nahezu in Echtzeit auf Änderungen reagieren.
  • Sie möchten vermeiden, dass häufig Microsoft Graph abgerufen wird, was dazu führen kann, dass Sie die Drosselungsgrenzwerte erreichen.

Arten von Änderungsbenachrichtigungen

Microsoft Graph unterstützt drei Arten von Änderungsbenachrichtigungen:

  • Grundlegende Benachrichtigungen: Änderungsbenachrichtigungen, die keine Ressourcendaten mit Ausnahme der ID der geänderten Ressource enthalten. Wenn eine App eine grundlegende Benachrichtigung empfängt, kann der Dienst die ID verwenden, um ein geändertes Objekt abzufragen.
  • Umfangreiche Benachrichtigungen: Änderungsbenachrichtigungen, die die Ressourcendaten des geänderten Objekts enthalten. Weitere Informationen zu umfangreichen Benachrichtigungen finden Sie unter Umfangreiche Benachrichtigungen.
  • Lebenszyklusbenachrichtigungen: Benachrichtigungen, die den Kunden benachrichtigen, wenn aufgrund des Lebenszyklus seines Abonnements das Risiko besteht, dass Änderungsbenachrichtigungen fehlen. Weitere Informationen zu Lebenszyklusbenachrichtigungen finden Sie unter Lebenszyklusbenachrichtigungen.

Empfangen von Änderungsbenachrichtigungen

Microsoft Graph kann Über die folgenden Kanäle Änderungsbenachrichtigungen an Clients senden.

Verwalten von Abonnements

Clients können Abonnements erstellen, verlängern und löschen. Während das Abonnement aktiv ist und Änderungen an der abonnierten Ressource auftreten, sendet Microsoft Graph Änderungsbenachrichtigungen an den angegebenen Benachrichtigungsendpunkt.

Sie verwalten das Abonnement mithilfe des Abonnementressourcentyps und der zugehörigen Methoden. Microsoft Graph sendet Änderungsbenachrichtigungen in einer Struktur, die im Ressourcentyp changeNotificationCollection definiert ist.

Unterstützte Ressourcen

Eine App kann Änderungen an den in der Tabelle aufgeführten Microsoft Graph-Ressourcen abonnieren.

Hinweis: Abonnements für Ressourcen, die mit einem Sternchen (*) gekennzeichnet sind, sind nur auf dem /beta Endpunkt verfügbar.

Ressource Unterstützte Ressourcenpfade Begrenzungen
Drucken in der Cloud Drucker Änderungen, wenn ein Druckauftrag heruntergeladen werden kann (jobFetchable-Ereignis): /print/printers/{id}/jobs -
Cloud-drucken printTaskDefinition Änderungen, wenn sich ein gültiger Auftrag in der Warteschlange befindet (jobStarted-Ereignis): /print/printtaskdefinition/{id}/tasks -
driveItem in OneDrive (persönlich) Änderungen am Inhalt innerhalb der Hierarchie eines beliebigen Ordners: /users/{id}/drive/root -
driveItem in OneDrive for Business Änderungen am Inhalt innerhalb der Hierarchie des Stammordners: /drives/{id}/root , /users/{id}/drive/root -
Gruppe Änderungen an allen Gruppen: /groups

Änderungen an einer bestimmten Gruppe: /groups/{id}

Änderungen an Besitzern einer bestimmten Gruppe: /groups/{id}/owners

Änderungen an Mitgliedern einer bestimmten Gruppe: /groups/{id}/members
Maximale Abonnementkontingente:
  • Pro App (für alle Mandanten kombiniert): insgesamt 50.000 Abonnements.
  • Pro Mandant (für alle Anwendungen kombiniert): 1.000 Abonnements insgesamt für alle Apps.
  • Kombination aus App und Mandant: insgesamt 100 Abonnements.

    Wird für Azure AD B2C-Mandanten nicht unterstützt.

    HINWEIS: Das Erstellen und vorläufige Löschen von Gruppen löst auch den updatedchangeType aus.
  • Liste auf einer SharePoint-Website Änderungen am Inhalt innerhalb der Liste: /sites/{site-id}/lists/{list-id} -
    Microsoft 365-Gruppenunterhaltung Änderungen an den Unterhaltungen einer Gruppe: groups/{id}/conversations -
    Outlook-Nachricht Änderungen an allen Nachrichten im Postfach eines Benutzers: /users/{id}/messages , /me/messages

    Änderungen an Nachrichten im Posteingang eines Benutzers: /users/{id}/mailFolders('inbox')/messages , /me/mailFolders('inbox')/messages
    Pro Postfach sind maximal 1.000 aktive Abonnements für alle Anwendungen zulässig.
    Outlook-Ereignis Änderungen an allen Ereignissen im Postfach eines Benutzers: /users/{id}/events , /me/events Pro Postfach sind maximal 1.000 aktive Abonnements für alle Anwendungen zulässig.
    Persönlicher Outlook-Kontakt Änderungen an allen persönlichen Kontakten im Postfach eines Benutzers: /users/{id}/contacts , /me/contacts Pro Postfach sind maximal 1.000 aktive Abonnements für alle Anwendungen zulässig.
    Sicherheitswarnung Änderungen an einer bestimmten Warnung: /security/alerts/{id}

    Änderungen an gefilterten Warnungen: /security/alerts/?$filter={parameters}
    Weitere Informationen finden Sie unter Sicherheits-API Warnungen.
    Teams callRecord Änderungen an allen Anrufeinträgen: /communications/callRecords Maximale Abonnementkontingente:
  • Pro organization: insgesamt 100 Abonnements.
  • Teams-AnrufAufzeichnung Alle Aufzeichnungen in einem organization:communications/onlineMeetings/getAllRecordings

    Alle Aufzeichnungen für eine bestimmte Besprechung: communications/onlineMeetings/{onlineMeetingId}/recordings

    Eine Anrufaufzeichnung, die in einer Besprechung verfügbar wird, die von einem bestimmten Benutzer organisiert wird: users/{id}/onlineMeetings/getAllRecordings
    Maximale Abonnementkontingente:
  • Kombination pro App und Onlinebesprechung: 1
  • Kombination pro App und Benutzer: 1
  • Pro Benutzer (für Abonnements, die Aufzeichnungen in allen onlineMeetings nachverfolgen, die vom Benutzer organisiert werden): 10 Abonnements.
  • Pro organization: insgesamt 10.000 Abonnements.
  • Teams callTranscript Alle Transkripte in einem organization:communications/onlineMeetings/getAllTranscripts

    Alle Transkripte für eine bestimmte Besprechung: communications/onlineMeetings/{onlineMeetingId}/transcripts

    Ein Anruftranskript, das in einer Besprechung verfügbar wird, die von einem bestimmten Benutzer organisiert wird: users/{id}/onlineMeetings/getAllTranscripts
    Maximale Abonnementkontingente:
  • Kombination pro App und Onlinebesprechung: 1
  • Kombination pro App und Benutzer: 1
  • Pro Benutzer (für Abonnements, die Transkripte in allen vom Benutzer organisierten onlineMeetings nachverfolgen): 10 Abonnements.
  • Pro organization: insgesamt 10.000 Abonnements.
  • Teams Chat Änderungen an chatten im Mandanten: /chats

    Änderungen an einem bestimmten Chat: /chats/{id}

    Änderungen an allen Chats in einem organization, in dem eine bestimmte Teams-App installiert ist:/appCatalogs/teamsApps/{id}/installedToChats
    Maximale Abonnementkontingente:
  • Kombination pro App und Chat: 1 Abonnement.
  • Pro organization: insgesamt 10.000 Abonnements.
  • Teams chatMessage Änderungen an Chatnachrichten in allen Kanälen in allen Teams: /teams/getAllMessages

    Änderungen an Chatnachrichten in einem bestimmten Kanal: /teams/{id}/channels/{id}/messages

    Änderungen an Chatnachrichten in allen Chats: /chats/getAllMessages

    Änderungen an Chatnachrichten in einem bestimmten Chat: /chats/{id}/messages

    Änderungen an Chatnachrichten in allen Chats, zu der ein bestimmter Benutzer gehört: /users/{id}/chats/getAllMessages

    Änderungen an Chatnachrichten für alle Chats in einem organization, in dem eine bestimmte Teams-App installiert ist:/appCatalogs/teamsApps/{id}/installedToChats/getAllMessages
    Maximale Abonnementkontingente:
  • Kombination aus App und Kanal oder Chat: 1 Abonnement.
  • Pro Benutzer (für Abonnements, die Chatnachrichten in allen Chats nachverfolgen): 10 Abonnements.
  • Pro organization: insgesamt 10.000 Abonnements.
  • Teams channel Änderungen an Kanälen in allen Teams: /teams/getAllChannels

    Änderungen am Kanal in einem bestimmten Team: /teams/{id}/channels
    Maximale Abonnementkontingente:
  • Kombination pro App und Team: 1 Abonnement.
  • Pro organization: insgesamt 10.000 Abonnements.
  • Teams conversationMember Änderungen an der Mitgliedschaft in einem bestimmten Team: /teams/{id}/members

    Änderungen an der Mitgliedschaft in allen Kanälen unter einem bestimmten Team: teams/{id}/channels/getAllMembers

    Änderungen an der Mitgliedschaft in einem bestimmten Chat: /chats/{id}/members

    Änderungen an der Mitgliedschaft für alle Chats in einem organization, in dem eine bestimmte Teams-App installiert ist:/appCatalogs/teamsApps/{id}/installedToChats/getAllMembers

    Änderungen an der Mitgliedschaft in allen Chats: /chats/getAllMembers
    Maximale Abonnementkontingente:
  • Kombination pro App und Team: 1 Abonnement.
  • Pro organization: insgesamt 10.000 Abonnements.
  • Teams onlineMeeting* Änderungen an einer Onlinebesprechung: /communications/onlineMeetings/?$filter=JoinWebUrl eq {joinWebUrl}
    Teams-Anwesenheit Änderungen an der Anwesenheit eines einzelnen Benutzers: /communications/presences/{id}

    Änderungen an mehreren Benutzerpräsenzen: /communications/presences?$filter=id in ({id},{id}...)
    Teams team Änderungen an einem Team im Mandanten: /teams

    Änderungen an einem bestimmten Team: /teams/{id}
    Maximale Abonnementkontingente:
  • Kombination pro App und Team: 1 Abonnement.
  • Pro organization: insgesamt 10.000 Abonnements.
  • todoTask Änderungen an allen Vorgängen in einer bestimmten Aufgabenliste: /me/todo/lists/{todoTaskListId}/tasks -
    user Änderungen an allen Benutzern: /users

    Änderungen an einem bestimmten Benutzer: /users/{id}
    Maximale Abonnementkontingente:
  • Pro App (für alle Mandanten kombiniert): insgesamt 50.000 Abonnements.
  • Pro Mandant (für alle Anwendungen kombiniert): 1000 Abonnements insgesamt über alle Apps hinweg
  • Kombination aus App und Mandant: insgesamt 100 Abonnements.

    Wird für persönliche Microsoft-Konten wie outlook.com nicht unterstützt.

    Wird für Azure AD B2C-Mandanten nicht unterstützt.

    HINWEIS: Das Erstellen und vorläufige Löschen von Benutzern löst auch den updatedchangeType aus.
  • Hinweis: Für viele Ressourcen gelten Grenzwerte oder Kontingente für die Anzahl der Abonnements, die für diese Ressource erstellt werden können. Wenn dieser Grenzwert überschritten wird, führen Versuche, ein Abonnement zu erstellen, zu einer 403 Forbidden Fehlerantwort. Die Meldungseigenschaft der Fehlerantwort erklärt den Grenzwert, der überschritten wurde.

    Einige dieser Ressourcen unterstützen umfangreiche Benachrichtigungen (Benachrichtigungen mit Ressourcendaten). Weitere Informationen zu Ressourcen, die umfangreiche Benachrichtigungen unterstützen, finden Sie unter Einrichten von Änderungsbenachrichtigungen, die Ressourcendaten enthalten.

    Gültigkeitsdauer von Abonnements

    Abonnements haben eine eingeschränkte Gültigkeit. Apps müssen ihre Abonnements vor der Ablaufzeit verlängern. Andernfalls muss ein neues Abonnement erstellt werden. Apps können auch jederzeit gekündigt werden, um keine weiteren Änderungsbenachrichtigungen zu erhalten.

    In der folgenden Tabelle sind die maximalen Ablaufzeiten für Abonnements pro Ressource in Microsoft Graph aufgeführt.

    Ressource Maximal zulässige Ablaufzeit
    Sicherheitswarnung 43.200 Minuten (unter 30 Tagen)
    Teams callRecord 4.230 Minuten (unter 3 Tagen)
    Teams-AnrufAufzeichnung 4.320 Minuten (3 Tage)
    Teams callTranscript 4.320 Minuten (3 Tage)
    Teams channel 4.320 Minuten (3 Tage)
    Teams Chat 4.320 Minuten (3 Tage)
    Teams chatMessage 4.320 Minuten (3 Tage)
    Teams conversationMember 4.320 Minuten (3 Tage)
    Teams onlineMeeting 4.320 Minuten (3 Tage)
    Teams team 4.320 Minuten (3 Tage)
    Gruppen Unterhaltung 4.230 Minuten (unter 3 Tagen)
    OneDrive driveItem 42.300 Minuten (unter 30 Tagen)
    SharePoint-Liste 42.300 Minuten (unter 30 Tagen)
    Outlook- Nachrichten-, -Ereignis, Kontakt 4.230 Minuten (unter 3 Tagen)
    Benutzer, Gruppe, sonstige Verzeichnisressourcen 41.760 Minuten (unter 29 Tagen)
    onlineMeeting 4.230 Minuten (unter 3 Tagen)
    presence 60 Minuten (1 Stunde)
    Drucken Drucker 4.230 Minuten (unter 3 Tagen)
    Drucken von printTaskDefinition 4.230 Minuten (unter 3 Tagen)
    todoTask 4.230 Minuten (unter 3 Tagen)

    Webhooks für diese Ressource sind nur im globalen Endpunkt und nicht in den nationalen Clouds verfügbar.
    baseTask (veraltet) 4.230 Minuten (unter 3 Tagen)

    Hinweis: Vorhandene Anwendungen und neue Anwendungen sollten den unterstützten Wert nicht überschreiten. In Zukunft schlagen alle Anforderungen zur Erstellung oder Verlängerung eines Abonnements, die über den Maximalwert hinausgehen, fehl.

    Wartezeit

    Die folgende Tabelle enthält eine Liste der voraussichtlichen Wartezeiten zwischen dem Eintreten eines Ereignisses im Dienst und der Übermittlung der Änderungsbenachrichtigung.

    Ressource Durchschnittliche Wartezeit Maximale Wartezeit
    Warnung1 Weniger als 3 Minuten 5 Minuten
    Kalender Weniger als 1 Minute 3 Minuten
    callRecord Weniger als 15 Minuten 60 Minuten
    callRecording Weniger als 10 Sekunden 60 Minuten
    callTranscript Weniger als 10 Sekunden 60 Minuten
    channel Weniger als 10 Sekunden 60 Minuten
    chat Weniger als 10 Sekunden 60 Minuten
    chatMessage Weniger als 10 Sekunden 1 Minute
    contact Weniger als 1 Minute 3 Minuten
    conversation Unbekannt Unbekannt
    conversationMember Weniger als 10 Sekunden 60 Minuten
    driveItem Weniger als 1 Minute 5 Minuten
    event Unbekannt Unbekannt
    group Weniger als 2 Minuten 15 Minuten
    list Weniger als 1 Minute 5 Minuten
    message Weniger als 1 Minute 3 Minuten
    onlineMeeting Weniger als 10 Sekunden 1 Minute
    presence Weniger als 10 Sekunden 1 Minute
    Drucker Weniger als 1 Minute 5 Minuten
    printTaskDefinition Weniger als 1 Minute 5 Minuten
    team Weniger als 10 Sekunden 60 Minuten
    todoTask Weniger als 2 Minuten 15 Minuten
    user Weniger als 2 Minuten 15 Minuten

    1 Die für die Warnungsressource bereitgestellte Latenz gilt erst, nachdem die Warnung erstellt wurde. Sie enthält nicht die Zeit, die eine Regel benötigt, um eine Warnung aus den Daten zu erstellen.

    Codebeispiele

    Es folgen einige Codebeispiele in GitHub.