Empfangen von Microsoft Graph-API-Änderungsereignissen über Azure Event Grid
In diesem Artikel wird erläutert, wie Sie Ereignisse abonnieren können, die von der Microsoft Graph-API veröffentlicht werden. In der folgenden Tabelle sind die Ereignisquellen aufgeführt, für die Ereignisse durch die Graph-API verfügbar sind. Für die meisten Ressourcen werden Ereignisse, die die Erstellung, Aktualisierung und Löschung angekündigt, unterstützt. Ausführliche Informationen zu den Ressourcen, für die Ereignisse für Ereignisquellen ausgelöst werden, finden Sie unter Unterstützte Ressourcen von Microsoft Graph-API-Änderungsbenachrichtigungen.
Microsoft-Ereignisquelle | Ressourcen | Verfügbare Ereignistypen |
---|---|---|
Microsoft Entra ID | Benutzer, Gruppe | Microsoft Entra-Ereignistypen |
Microsoft Outlook | Ereignis (Kalenderbesprechung), Nachricht (E-Mail), Kontakt | Microsoft Outlook-Ereignistypen |
Microsoft Teams | ChatMessage, CallRecord (Besprechung) | Microsoft Teams-Ereignistypen |
OneDrive | DriveItem | Microsoft OneDrive-Ereignisse |
Microsoft SharePoint | Liste | Microsoft SharePoint-Ereignisse |
Aufgabenplanung | To Do-Aufgaben | Microsoft ToDo-Ereignisse |
Sicherheitswarnungen | Warnung | Microsoft Security Alert-Ereignisse |
Cloud-Druck | Drucker, Druckaufgabendefinition | Microsoft Cloud Printing-Ereignisse |
Microsoft Conversations | Unterhaltung | Microsoft 365-Gruppenchatereignisse |
Sie erstellen ein Microsoft Graph-API-Abonnement, um Graph-API Ereignisse zu aktivieren, die in ein Partnerthema fließen. Das Partnerthema wird automatisch als Teil der Graph-API-Abonnementerstellung für Sie erstellt. Sie verwenden dieses Partnerthema, um Ereignisabonnements zu erstellen, um Ihre Ereignisse an einen der unterstützten Ereignishandler zu senden, der Ihre Anforderungen am besten erfüllt, um die Ereignisse zu verarbeiten.
Wichtig
Wenn Sie das Feature Partnerereignisse nicht kennen, sehen Sie sich die Übersicht zu Partnerereignissen an.
Warum sollte ich Ereignisse aus Microsoft Graph-API-Quellen über das Ereignisraster abonnieren?
Neben der Möglichkeit, Ereignisse der Microsoft Graph-API über Event Grid zu abonnieren, können Sie ähnliche Benachrichtigungen (keine Ereignisse) auf anderen Wegen erhalten. Sie können die Microsoft Graph-API zum Übermitteln von Ereignissen an Event Grid verwenden, wenn Sie mindestens eine der folgenden Voraussetzungen erfüllen:
- Sie entwickeln eine ereignisgesteuerte Lösung, die Ereignisse aus Microsoft Entra ID, Teams usw. benötigt, um auf Ressourcenänderungen zu reagieren. Sie benötigen die robusten Ereignismodell- und Veröffentlichen-Abonnieren-Funktionen von Event Grid. Eine Übersicht über Event Grid finden Sie unter Event Grid-Konzepte.
- Sie möchten Event Grid nutzen, um Ereignisse mithilfe eines einzelnen Graph-API-Abonnements an mehrere Ziele weiterzuleiten. Außerdem möchten Sie es vermeiden, mehrere Graph-API-Abonnements zu verwalten.
- Sie müssen Ereignisse je nach den Eigenschaften des Ereignisses an verschiedene nachgelagerte Anwendungen, Webhooks oder Azure-Dienste weiterleiten. Beispielsweise möchten Sie Ereignistypen wie
Microsoft.Graph.UserCreated
undMicrosoft.Graph.UserDeleted
an eine spezielle Anwendung weiterleiten, die das Onboarding und Offboarding von Benutzern verarbeitet. Außerdem möchten SieMicrosoft.Graph.UserUpdated
-Ereignisse beispielsweise an eine andere Anwendung senden, die Kontaktinformationen synchronisiert. Sie können dies tun, indem Sie ein einzelnes Graph-API-Abonnement verwenden, wenn Sie Event Grid als Benachrichtigungsziel nutzen. Weitere Informationen finden Sie unter Ereignisfilter und Ereignishandler. - Die Interoperabilität ist Ihnen wichtig. Sie möchten Ereignisse standardmäßig mit Cloud Native Computing Foundation (CNCF) CloudEvents-Spezifikationsstandard weiterleiten und verarbeiten.
- Sie möchten die Erweiterbarkeitsunterstützung von CloudEvents verwenden. Wenn Sie beispielsweise Ereignisse in kompatiblen Systemen nachverfolgen möchten, verwenden Sie die CloudEvents-Erweiterung Verteilte Ablaufverfolgung. Hier erfahren Sie mehr über CloudEvents-Erweiterungen.
- Sie möchten bewährte ereignisgesteuerte Ansätze verwenden, die in der Branche üblich sind.
Aktivieren des Ereignisflusses der Microsoft Graph-API zu Ihrem Partnerthema
Sie fordern die Microsoft Graph-API an, Ereignisse an ein Ereignisraster-Partnerthema weiterzuleiten, indem Sie ein Graph-API-Abonnement mithilfe der Microsoft Graph API Software Development Kits (SDKs) erstellen und die Schritte in den Links zu Beispielen in diesem Abschnitt ausführen. Weitere Informationen finden Sie unter Unterstützte Sprachen für das Microsoft Graph-API-SDK für die verfügbare SDK-Unterstützung.
Allgemeine Voraussetzungen
Sie sollten diese allgemeinen Voraussetzungen erfüllen, bevor Sie Ihre Anwendung zum Erstellen und Verlängern von Microsoft Graph-API-Abonnements implementieren:
Machen Sie sich mit den allgemeinen Schritten vertraut, um Partnerereignisse zu abonnieren. Wie in diesem Artikel beschrieben, sollten Sie vor dem Erstellen eines Graph-API-Abonnements die Anweisungen in folgenden Artikeln befolgen:
Registrieren Sie den Ereignisrasterressourcenanbieter bei Ihrem Azure-Abonnement.
Microsoft Graph-API (Partner) autorisieren, ein Partnerthema in Ihrer Ressourcengruppe zu erstellen.
Verfügen Sie über ein funktionierendes Wissen über Microsoft Graph-API-Benachrichtigungen. Im Rahmen Ihres Lernens können Sie den Graph-API-Explorer verwenden, um Graph-API-Abonnements zu erstellen.
Verstehen von Konzepten für Partnerereignisse.
Identifizieren Sie die Microsoft Graph-API-Ressource, aus der Sie Systemstatusänderungsereignisse empfangen möchten. Weitere Informationen finden Sie unter Änderungsbenachrichtigungen der Microsoft Graph-API. Zum Nachverfolgen von Änderungen an Benutzern in der Microsoft Entra-ID sollten Sie beispielsweise die Benutzerressource verwenden. Verwenden Sie die Gruppe zum Nachverfolgen von Änderungen an Benutzergruppen.
Verfügen Sie über ein Mandantenadministratorkonto auf einem Microsoft 365-Mandanten. Sie können einen Entwicklungsmandanten kostenlos erhalten, indem Sie dem Microsoft 365-Entwicklerprogramm beitreten.
Weitere Voraussetzungen für die gewünschte Programmiersprache und die Entwicklungsumgebung, die Sie in den Microsoft Graph-API-Beispiellinks verwenden, finden Sie in einem nächsten Abschnitt.
Wichtig
Ausführliche Anweisungen zum Implementieren Ihrer Anwendung finden Sie im Abschnitt Beispiele mit detaillierten Anweisungen abschnitt, Sie sollten jedoch alle Abschnitte in diesem Artikel lesen, da sie zusätzliche, wichtige Informationen zum Weiterleiten von Microsoft Graph-API-Ereignissen mithilfe von Event Grid enthalten.
So erstellen Sie ein Microsoft Graph-API-Abonnement
Wenn Sie ein Graph-API-Abonnement erstellen, wird ein Partnerthema für Sie erstellt. Sie übergeben die folgenden Informationen in Parameter notificationUrl, um anzugeben, welches Partnerthema erstellt und dem neuen Graph-API-Abonnement zugeordnet werden soll:
- Name des Partnerthemas
- Ressourcengruppenname, in dem das Partnerthema erstellt wird
- Region (Standort)
- Azure-Abonnement
In diesen Codebeispielen wird gezeigt, wie Sie ein Graph-API-Abonnement erstellen. Sie zeigen Beispiele zum Erstellen eines Abonnements zum Empfangen von Ereignissen von allen Benutzern in einem Microsoft Entra ID-Mandanten, wenn sie erstellt, aktualisiert oder gelöscht werden.
POST https://graph.microsoft.com/v1.0/subscriptions
Content-type: application/json
{
"changeType": "Updated,Deleted,Created",
"notificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
"lifecycleNotificationUrl": "EventGrid:?azuresubscriptionid=8A8A8A8A-4B4B-4C4C-4D4D-12E12E12E12E&resourcegroup=yourResourceGroup&partnertopic=yourPartnerTopic&location=theNameOfAzureRegionFortheTopic",
"resource": "users",
"expirationDateTime": "2024-03-31T00:00:00Z",
"clientState": "secretClientValue"
}
changeType
: Hierbei handelt es sich um die Art der Ressourcenänderungen, für die Sie Ereignisse empfangen möchten. Gültige Werte sindUpdated
,Deleted
undCreated
. Sie können einen oder mehrere dieser Werte durch Kommas getrennt angeben.notificationUrl
: ein URI, der verwendet wird, um das Partnerthema zu definieren, an das Ereignisse gesendet werden. Es muss dem folgenden Muster entsprechen:EventGrid:?azuresubscriptionid=<you-azure-subscription-id>&resourcegroup=<your-resource-group-name>&partnertopic=<the-name-for-your-partner-topic>&location=<the-Azure-region-name-where-you-want-the-topic-created>
. Der Ort (auch als Azure-Region bezeichnet)name
kann abgerufen werden, indem der Befehl az account list-locations ausgeführt wird. Verwenden Sie keinen Anzeigenamen für den Ort. Beispielsweise sollten Sie nicht „USA, Westen-Mitte“ verwenden. Verwenden Sie stattdessenwestcentralus
.az account list-locations
lifecycleNotificationUrl
: ein URI, der verwendet wird, um das Partnerthema zu definieren, an dasmicrosoft.graph.subscriptionReauthorizationRequired
Ereignisse gesendet werden. Dieses Ereignis signalisiert Ihre Anwendung, dass das Graph-API-Abonnement bald abläuft. Der URI folgt dem zuvor beschriebenen Muster notificationUrl, wenn Ereignisraster als Ziel für Lebenszyklusereignisse verwendet wird. In diesem Fall sollte das Partnerthema mit dem in notificationUrl angegebenen identisch sein.- resource: die Ressource, die Ereignisse generiert, die Zustandsänderungen ankündigen.
- expirationDateTime: dies ist der Zeitpunkt, zu dem das Abonnement abläuft und somit der Flow von Ereignissen beendet wird. Es muss dem Format entsprechen, das unter Änderungsanforderung 3339 angegeben ist. Sie müssen den Ablaufzeitpunkt angeben, die in der maximal zulässigen Abonnementlänge pro Ressourcentyp vorhanden ist.
- client state: Diese Eigenschaft ist optional. Dieser wird zur Überprüfung von Aufrufen ihrer Ereignishandleranwendung während der Ereignisübermittlung verwendet. Weitere Informationen finden Sie unter Eigenschaften von Graph-API-Abonnements.
Wichtig
Namen von Partnerthemen müssen innerhalb derselben Azure-Region eindeutig sein. Mit jeder Kombination aus Mandanten- und Anwendungs-ID können bis zu zehn eindeutige Partnerthemen erstellt werden.
Achten Sie bei der Entwicklung Ihrer Lösung auf bestimmte Graph-API-Dienstgrenzwerte für Ressourcen.
Vorhandene Graph-API-Abonnements ohne
lifecycleNotificationUrl
Eigenschaft empfangen keine Lebenszyklusereignisse. Um die Eigenschaft lifecycleNotificationUrl hinzuzufügen, sollten Sie das vorhandene Abonnement löschen und ein neues Abonnement erstellen, das die Eigenschaft während der Erstellung des Abonnements angibt.
Nach dem Erstellen eines Graph-API-Abonnements haben Sie ein Partnerthema, das in Azure erstellt wurde.
Verlängern eines Microsoft Graph-API-Abonnements
Ihre Anwendung muss das Graph-API-Abonnement verlängern, bevor es abläuft, um das Beenden des Ereignisflusses zu vermeiden. Um den Erneuerungsprozess zu automatisieren, unterstützt Microsoft Graph-API Lebenszyklusbenachrichtigungsereignisse, die Ihre Anwendung abonnieren kann. Derzeit unterstützen alle Microsoft Graph-API-Ressourcen den microsoft.graph.subscriptionReauthorizationRequired
, der gesendet wird, wenn eine der folgenden Bedingungen eintritt:
- Das Zugriffstoken läuft bald ab.
- Das Graph-API-Abonnement läuft bald ab.
- Ein Mandantenadministrator hat die Berechtigungen Ihrer App zum Lesen einer Ressource widerrufen.
Wenn Sie Ihr Graph-API-Abonnement nach Ablauf nicht verlängert haben, müssen Sie ein neues Graph-API-Abonnement erstellen. Sie können sich auf das gleiche Partnerthema beziehen, das Sie in Ihrem abgelaufenen Abonnement verwendet haben, solange es für weniger als 30 Tage abgelaufen ist. Wenn das Graph-API-Abonnement länger als 30 Tage abgelaufen ist, können Sie Ihr vorhandenes Partnerthema nicht wiederverwenden. In diesem Fall müssen Sie entweder einen anderen Partnerthemennamen angeben. Alternativ können Sie das vorhandene Partnerthema löschen, um während der Erstellung des Graph-API-Abonnements ein neues Partnerthema mit demselben Namen zu erstellen.
Verlängern eines Microsoft Graph-API-Abonnements
Beim Empfang eines microsoft.graph.subscriptionReauthorizationRequired
Ereignisses sollte Ihre Anwendung das Graph-API-Abonnement verlängern, indem Sie die folgenden Aktionen ausführen:
Wenn Sie beim Erstellen des Graph-API-Abonnements einen geheimen Clientschlüssel in der Eigenschaft clientState angegeben haben, ist dieser geheime Clientschlüssel im Lieferumfang des Ereignisses enthalten. Überprüfen Sie, ob der clientState des Ereignisses mit dem Wert übereinstimmt, der beim Erstellen des Graph-API-Abonnements verwendet wird.
Stellen Sie sicher, dass die App über ein gültiges Zugriffstoken verfügt, um den nächsten Schritt auszuführen. Weitere Informationen finden Sie im nachfolgenden Abschnitt Beispiele mit detaillierten Anweisungen.
Rufen Sie eine der folgenden beiden APIs auf. Wenn der API-Aufruf erfolgreich ist, wird der Änderungsbenachrichtigungsfluss fortgesetzt.
Rufen Sie die
/reauthorize
Aktion auf, um das Abonnement erneut zu autorisieren, ohne das Ablaufdatum zu verlängern.POST https://graph.microsoft.com/beta/subscriptions/{id}/reauthorize
Führen Sie eine regelmäßige "Verlängerungs"-Aktion aus, um das Abonnement gleichzeitig erneut zu autorisieren und zu verlängern.
PATCH https://graph.microsoft.com/beta/subscriptions/{id} Content-Type: application/json { "expirationDateTime": "2024-04-30T11:00:00.0000000Z" }
Die Verlängerung schlägt möglicherweise fehl, wenn die App nicht mehr für den Zugriff auf die Ressource autorisiert ist. Es kann dann erforderlich sein, dass die App ein neues Zugriffstoken abruft, um ein Abonnement erfolgreich erneut zu autorisieren.
Autorisierungsprobleme ersetzen nicht die Notwendigkeit, ein Abonnement zu verlängern, bevor es abläuft. Die Lebenszyklus von Zugriffstoken und Abonnementablauf sind nicht identisch. Ihr Zugriffstoken läuft möglicherweise vor Ihrem Abonnement ab. Es ist wichtig, darauf vorbereitet zu sein, Ihren Endpunkt regelmäßig erneut zu autorisieren, um Ihr Zugriffstoken zu aktualisieren. Durch die erneute Autorisierung Ihres Endpunkts wird Ihr Abonnement nicht verlängert. Durch die Verlängerung Ihres Abonnements wird Ihr Endpunkt jedoch erneut autorisiert.
Beim Verlängern und/oder erneuten Autorisieren Ihres Graph-API-Abonnements wird dasselbe Partnerthema angegeben, das beim Erstellen des Abonnements angegeben wurde.
Wenn Sie ein neues expirationDateTime-Element angeben, muss es mindestens drei Stunden ab der aktuellen Uhrzeit liegen. Andernfalls empfängt Ihre Anwendung microsoft.graph.subscriptionReauthorizationRequired
Ereignisse möglicherweise bald nach der Verlängerung.
Beispiele zum erneuten Autorisieren Ihres Graph-API-Abonnements mithilfe einer der unterstützten Sprachen finden Sie unter Anforderung zur erneuten Autorisierung des Abonnements.
Beispiele zum Verlängern und Erneuten Autorisieren Ihres Graph-API-Abonnements mithilfe einer der unterstützten Sprachen finden Sie unter Anforderung zur Aktualisierung des Abonnements.
Beispiele mit detaillierten Anweisungen
Die Microsoft Graph-API-Dokumentation enthält Codebeispiele mit Anweisungen zur:
- Einrichtung Ihrer Entwicklungsumgebung mit bestimmten Anweisungen entsprechend der verwendeten Sprache. Anweisungen umfassen auch das Abrufen eines Microsoft 365-Mandanten für Entwicklungszwecke.
- Erstellen Sie Graph-API-Abonnements. Um ein Abonnement zu verlängern, können Sie die Graph-API mithilfe der Codeschnipsel in Verlängern eines Graph-API-Abonnements aufrufen.
- Rufen Sie Authentifizierungstoken ab, um sie beim Aufrufen der Microsoft Graph-API zu verwenden.
Hinweis
Es ist möglich, Ihr Graph-API-Abonnement mit dem Microsoft Graph-API-Explorer zu erstellen. Sie sollten die Beispiele weiterhin für andere wichtige Aspekte Ihrer Lösung verwenden, z. B. Authentifizierungs- und Empfangsereignisse.
Webanwendungsbeispiele sind für die folgenden Sprachen verfügbar:
- C#-Beispiel. Es ist ein aktuelles Beispiel, das das Erstellen und Verlängern von Graph-API-Abonnements umfasst und Sie durch einige der Schritte zum Aktivieren des Ereignisflusses führt.
- Java-Beispiel
- NodeJS-Beispiel.
Wichtig
Sie müssen Ihr Partnerthema aktivieren, das als Teil ihrer Graph-API-Abonnementerstellung erstellt wird. Sie müssen auch ein Event Grid-Ereignisabonnement für Ihre Webanwendung erstellen, um Ereignisse zu empfangen. Zu diesem Zweck verwenden Sie die in Ihrer Webanwendung konfigurierte URL, um Ereignisse als Webhook-Endpunkt in Ihrem Ereignisabonnement zu empfangen. Nächste Schritte für weitere Informationen.
Wichtig
Benötigen Sie Beispielcode für eine andere Sprache oder haben Sie Fragen? Senden Sie eine E-Mail an ask-graph-and-grid@microsoft.com.
Nächste Schritte
Führen Sie die Anweisungen in den folgenden beiden Schritten aus, um die Einrichtung für den Empfang von Microsoft Graph-API-Ereignissen mithilfe von Event Grid abzuschließen:
- Aktivieren Sie das Partnerthema, das als Teil der Erstellung der Microsoft Graph-API erstellt wurde.
- Abonnieren Sie Ereignisse, indem Sie ein Ereignisabonnement für Ihr Partnerthema erstellen.
Weitere nützliche Links:
- Azure Event Grid – Übersicht über Partnerereignisse
- Informationen zur Microsoft Graph-API.
- Microsoft Graph-API-Webhooks
- Bewährte Methoden für das Arbeiten mit der Microsoft Graph-API
- SDKs für die Microsoft Graph-API
- Microsoft Graph-API-Tutorials, die zeigen, wie Graph-API verwendet wird. Dieser Artikel enthält nicht unbedingt Beispiele für das Senden von Ereignissen an Event Grid.