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 das geänderte 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.
- Webhooks. Weitere Informationen finden Sie unter Empfangen von Änderungsbenachrichtigungen über Webhooks.
- Azure Event Hubs. Weitere Informationen finden Sie unter Empfangen von Änderungsbenachrichtigungen über Azure Event Hubs.
- Azure Event Grid (Vorschau) Weitere Informationen finden Sie unter Empfangen von Änderungsbenachrichtigungen über Azure Event Grid.
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 auf OneDrive für Geschäfts-, Schul- oder Unikonten | Ä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: Wird für Azure AD B2C-Mandanten nicht unterstützt. ANMERKUNG: Das Erstellen und vorläufige Löschen von Gruppen löst auch den updated changeType 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-Genehmigungen | Änderungen an allen Genehmigungen in einem Mandanten: /solutions/approval/approvalItems |
Maximale Abonnementkontingente: |
Teams callRecord | Änderungen an allen Anrufeinträgen: /communications/callRecords Änderungen an gefilterten Anrufdatensätzen: /communications/callRecords?$filter={parameters} |
Weitere Informationen finden Sie unter Änderungsbenachrichtigungen für Anrufdatensätze. Maximale Abonnementkontingente: ANMERKUNG: Die Erstellung von Aufrufdatensätzen löst auch den updated changeType aus. |
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 Eine Anrufaufzeichnung, die in einer Besprechung verfügbar wird, in der eine bestimmte Teams-App installiert ist: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllRecordings * |
Maximale Abonnementkontingente: |
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 Ein Anruftranskript, das in einer Besprechung verfügbar wird, in der eine bestimmte Teams-App installiert ist: appCatalogs/teamsApps/{id}/installedToOnlineMeetings/getAllTrancripts * |
Maximale Abonnementkontingente: |
Teams Chat | Änderungen an chatten im Mandanten: /chats Änderungen an einem bestimmten Chat: /chats/{id} Änderungen an einem bestimmten Chat mit dem Abfrageparameter notifyOnUserSpecificProperties : /chats/{id}?notifyOnUserSpecificProperties={Boolean} Änderungen an allen Chats in einem organization, in dem eine bestimmte Teams-App installiert ist: /appCatalogs/teamsApps/{id}/installedToChats Änderungen an allen Chats, zu denen ein bestimmter Benutzer gehört: /users/{id}/chats Änderungen an allen Chats, an denen ein bestimmter Benutzer teil ist, mit dem Abfrageparameter notifyOnUserSpecificProperties : /users/{id}/chats?notifyOnUserSpecificProperties={Boolean} |
Maximale Abonnementkontingente: |
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: |
Teams channel | Änderungen an Kanälen in allen Teams: /teams/getAllChannels Änderungen am Kanal in einem bestimmten Team: /teams/{id}/channels |
Maximale Abonnementkontingente: |
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: |
Teams onlineMeeting* | Änderungen an einer Onlinebesprechung: /communications/onlineMeetings(joinWebUrl='{encodedJoinWebUrl}')/meetingCallEvents |
Unterstützt nicht die Verwendung von $select , um nur ausgewählte Eigenschaften zurückzugeben. Die rich-Benachrichtigung besteht aus allen Eigenschaften des geänderten instance. Pro Anwendung und Onlinebesprechung ist ein Abonnement zulässig. Weitere Informationen finden Sie unter Abrufen von Änderungsbenachrichtigungen für Aktualisierungen von Microsoft Teams-Besprechungsanrufereignissen. |
Teams-Anwesenheit | Änderungen an der Anwesenheit eines einzelnen Benutzers: /communications/presences/{id} Änderungen an der Anwesenheit mehrerer Benutzer: /communications/presences?$filter=id in ({id},{id}...) |
Das Abonnement für die Anwesenheit mehrerer Benutzer ist auf 650 verschiedene Benutzer beschränkt. Unterstützt nicht die Verwendung von $select , um nur ausgewählte Eigenschaften zurückzugeben. Die rich-Benachrichtigung besteht aus allen Eigenschaften des geänderten instance. Pro Anwendung und delegiertem Benutzer ist ein Abonnement zulässig. Weitere Informationen finden Sie unter Abrufen von Änderungsbenachrichtigungen für Anwesenheitsupdates in Microsoft Teams. |
Teams team | Änderungen an einem Team im Mandanten: /teams Änderungen an einem bestimmten Team: /teams/{id} |
Maximale Abonnementkontingente: |
Angebot "Teams-Schichten" ShiftRequest | Änderungen an einer Angebotsverschiebungsanforderung in einem Team: /teams/{id}/schedule/offerShiftRequests |
Maximale Abonnementkontingente: |
Teams Schichten openShiftChangeRequest | Änderungen an allen offenen Schichtanforderungen in einem Team: /teams/{id}/schedule/openShiftChangeRequests |
Maximale Abonnementkontingente: |
Schichten in Teams | Änderungen an einer Schicht in einem Team: /teams/{id}/schedule/shifts |
Maximale Abonnementkontingente: |
Teams Schichten swapShiftsChangeRequest | Änderungen an einer Verschiebungsanforderung in einem Team: /teams/{id}/schedule/swapShiftsChangeRequests |
Maximale Abonnementkontingente: |
Teams verschiebt timeOffRequest | Änderungen an einer Anforderung für eine ausserplanende Zeit in einem Team: /teams/{id}/schedule/timeOffRequests |
Maximale Abonnementkontingente: |
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: Wird für persönliche Microsoft-Konten wie outlook.com nicht unterstützt. Wird für Azure AD B2C-Mandanten nicht unterstützt. ANMERKUNG: Das Erstellen und vorläufige Löschen von Benutzern löst auch den updated changeType 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-Genehmigungen | 43.200 Minuten (unter 30 Tagen) |
Teams callRecord | 4.230 Minuten (unter drei Tagen) |
Teams-AnrufAufzeichnung | 4.320 Minuten (drei Tage) |
Teams callTranscript | 4.320 Minuten (drei Tage) |
Teams channel | 4.320 Minuten (drei Tage) |
Teams Chat | 4.320 Minuten (drei Tage) |
Teams chatMessage | 4.320 Minuten (drei Tage) |
Teams conversationMember | 4.320 Minuten (drei Tage) |
Teams onlineMeeting | 4.320 Minuten (drei Tage) |
Teams team | 4.320 Minuten (drei Tage) |
Teams TeamsAppInstallation | 4.320 Minuten (3 Tage) |
Angebot "Teams-Schichten" ShiftRequest | 360 Minuten (6 Stunden) |
Teams Schichten openShiftChangeRequest | 360 Minuten (6 Stunden) |
Schichten in Teams | 360 Minuten (6 Stunden) |
Teams Schichten swapShiftsChangeRequest | 360 Minuten (6 Stunden) |
Teams verschiebt timeOffRequest | 360 Minuten (6 Stunden) |
Gruppen Unterhaltung | 4.230 Minuten (unter drei Tagen) |
OneDrive driveItem | 42.300 Minuten (unter 30 Tagen) |
SharePoint-Liste | 42.300 Minuten (unter 30 Tagen) |
Outlook- Nachrichten-, -Ereignis, Kontakt | 10.080 Minuten (unter sieben Tagen) |
Benutzer, Gruppe, sonstige Verzeichnisressourcen | 41.760 Minuten (unter 29 Tagen) |
onlineMeeting | 4.230 Minuten (unter drei Tagen) |
presence | 60 Minuten (1 Stunde) |
Drucken Drucker | 4.230 Minuten (unter drei Tagen) |
Drucken von printTaskDefinition | 4.230 Minuten (unter drei Tagen) |
todoTask | 4.230 Minuten (unter drei 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 drei 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 |
Zustimmungen | Weniger als 10 Sekunden | 40 Sekunden |
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 | Unbekannt | Unbekannt |
list | Weniger als 1 Minute | 5 Minuten |
message | Weniger als 1 Minute | 3 Minuten |
offerShiftRequest | Weniger als 1 Minute | 60 Minuten |
onlineMeeting | Weniger als 10 Sekunden | 1 Minute |
openShiftChangeRequest | Weniger als 1 Minute | 60 Minuten |
presence | Weniger als 10 Sekunden | 1 Minute |
Drucker | Weniger als 1 Minute | 5 Minuten |
printTaskDefinition | Weniger als 1 Minute | 5 Minuten |
shift | Weniger als 1 Minute | 60 Minuten |
swapShiftsChangeRequest | Weniger als 1 Minute | 60 Minuten |
team | Weniger als 10 Sekunden | 60 Minuten |
teamsAppInstallation | Weniger als 10 Sekunden | 60 Minuten |
timeOffRequest | Weniger als 1 Minute | 60 Minuten |
todoTask | Weniger als 2 Minuten | 15 Minuten |
user | Unbekannt | Unbekannt |
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.
- Microsoft Graph Schulungsmodul – Verwenden von Änderungsbenachrichtigungen und Nachverfolgen von Änderungen mit Microsoft Graph
- Microsoft Graph Webhooks-Beispiel für Node.js
- Microsoft Graph Webhooks-Beispiel für ASP.NET Core
- Microsoft Graph Webhooks-Beispiel für Java Spring