Empfangen von Microsoft Graph-API-Änderungsereignissen über Azure Event Grid

Die Microsoft Graph-API bietet Änderungsbenachrichtigungen für Ressourcen in Microsoft 365-Diensten, einschließlich Microsoft Entra-ID, Teams, Outlook und OneDrive. Indem Sie diese Ereignisse über Azure Event Grid abonnieren, können Sie ereignisgesteuerte Anwendungen erstellen, die in Echtzeit auf Ressourcenänderungen reagieren.

In diesem Artikel wird Folgendes erläutert:

  • Erstellen Sie Microsoft Graph-API-Abonnements, die Ereignisse zu Azure Event Grid-Partnerthemen bereitstellen.
  • Verwalten Sie die Abonnementlebenszyklen mit automatischer Verlängerung.
  • Routen Sie Ereignisse zu mehreren Zielen, indem Sie die Filter- und Routing-Funktionen von Event Grid nutzen.

Azure Event Grid bietet gegenüber herkömmlichen Webhook-basierten Microsoft Graph-API-Abonnements mehrere Vorteile:

  • Vereinfachtes Routing: Verwenden Sie ein einzelnes Graph-API-Abonnement, um Ereignisse an mehrere Ziele zu senden.
  • Erweiterte Filterung: Leiten Sie bestimmte Ereignistypen basierend auf Ereigniseigenschaften an verschiedene Anwendungen weiter.
  • Standardscompliance: Empfangen von Ereignissen im CloudEvents-Format für eine bessere Interoperabilität.
  • Zuverlässigkeit: Integrierte Wiederholungslogik und Dead-Letter-Warteschlangen sorgen für eine zuverlässige Ereignisübermittlung.

Unterstützte Ereignisquellen

Die folgende Tabelle listet die Ereignisquellen auf, für die Sie Ereignisse über die Graph-API erhalten können. Für die meisten Ressourcen unterstützt die Graph-API Ereignisse, die ihre Erstellung, Aktualisierung und Löschung ankündigen. Ausführliche Informationen zu den Ressourcen, die Ereignisse für Ereignisquellen auslösen, finden Sie unter von Microsoft Graph-API-Änderungsbenachrichtigungen unterstützte Ressourcen.

Microsoft-Ereignisquelle Ressourcen Verfügbare Ereignistypen
Microsoft Entra ID Benutzer, Gruppe Microsoft Entra ID-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-Unterhaltungen Unterhaltung Microsoft 365-Gruppenchatereignisse

Erstellen Sie ein Microsoft Graph-API-Abonnement, damit Graph-API-Ereignisse in ein Partnerthema fließen können. Die Graph-API erstellt automatisch das Partnerthema, wenn Sie das Abonnement erstellen. Verwenden Sie dieses Partnerthema, um Ereignisabonnements zu erstellen , um Ihre Ereignisse an einen der unterstützten Ereignishandler zu senden, die Ihre Anforderungen zum Verarbeiten der Ereignisse am besten erfüllen.

Wichtig

Wenn Sie mit dem Feature " Partnerereignisse " nicht vertraut sind, lesen Sie die Übersicht über Partnerereignisse.

Warum abonnieren Sie Ereignisse aus Microsoft Graph-API-Quellen über Event Grid?

Neben dem Abonnieren von Microsoft Graph-API-Events über Event Grid haben Sie auch andere Möglichkeiten, ähnliche Benachrichtigungen (keine Events) zu erhalten. Verwenden Sie die Microsoft Graph-API, um Ereignisse an das Ereignisraster zu übermitteln, wenn Sie mindestens eine der folgenden Anforderungen erfüllen:

  • Sie entwickeln eine ereignisgesteuerte Lösung, die Ereignisse von Microsoft Entra ID, Outlook oder Teams verwendet, um auf Ressourcenänderungen zu reagieren. Sie benötigen das robuste ereignisgesteuerte Modell und die Veröffentlichungsabonnent-Funktionen, die Event Grid bereitstellt. Eine Übersicht über Event Grid finden Sie unter Event Grid-Konzepte.
  • Du möchtest Event Grid nutzen, um Ereignisse über ein einziges Graph-API-Abonnement zu mehreren Zielen zu routen, und du möchtest die Verwaltung mehrerer Graph-API-Abonnements vermeiden.
  • Sie müssen Ereignisse basierend auf einigen Eigenschaften im Ereignis an verschiedene downstream-Anwendungen, Webhooks oder Azure-Dienste weiterleiten. Beispielsweise möchten Sie Ereignistypen wie Microsoft.Graph.UserUpdated und Microsoft.Graph.UserDeleted an eine spezielle Anwendung weiterleiten, die das Onboarding und Offboarding von Benutzern verarbeitet. Außerdem möchten Sie Microsoft.Graph.UserUpdated-Ereignisse beispielsweise an eine andere Anwendung senden, die Kontaktinformationen synchronisiert. Das können Sie erreichen, indem Sie ein einziges Graph-API-Abonnement verwenden, wenn Sie Event Grid als Benachrichtigungsziel verwenden. Weitere Informationen finden Sie unter Ereignisfilter und Ereignishandler.
  • Die Interoperabilität ist Ihnen wichtig. Sie möchten Ereignisse standardisiert weiterleiten und verarbeiten, indem Sie den Cloud Native Computing Foundation (CNCF) CloudEvents-Standard verwenden.
  • Sie schätzen die Erweiterbarkeitsunterstützung, die CloudEvents bereitstellt. Um z. B. Ereignisse über kompatible Systeme hinweg zu verfolgen, verwenden Sie die Verteilte Ablaufverfolgungserweiterung CloudEvents. Erfahren Sie mehr über CloudEvents-Erweiterungen.
  • Sie verwenden bewährte, ereignisgetriebene Ansätze, die die Branche anwendet.

Aktivieren des Ereignisflusses der Microsoft Graph-API zu Ihrem Partnerthema

Fordern Sie 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

Bevor Sie Ihre Anwendung zur Erstellung und Erneuerung von Microsoft Graph-API-Abonnements implementieren, stellen Sie sicher, dass Sie diese allgemeinen Voraussetzungen erfüllen:

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

Während detaillierte Anweisungen zur Implementierung Ihrer Anwendung im Abschnitt Beispiele mit detaillierten Anweisungen zu finden sind, lesen Sie alle Abschnitte dieses Artikels, da sie wichtigere Informationen zur Weiterleitung von Microsoft Graph-API-Ereignissen mit Event Grid enthalten.

So erstellen Sie ein Microsoft Graph-API-Abonnement

Wenn Sie ein Graph-API-Abonnement erstellen, erstellt das System ein Partnerthema für Sie. Sie geben folgende Informationen in den Parameter notificationUrl ein, um das Partnerthema zu spezifizieren, das mit dem neuen Graph-API-Abonnement erstellt und zugeordnet werden soll:

  • Name des Partnerthemas
  • Name der Ressourcengruppe für das Partnerthema
  • Region (Standort)
  • Azure-Abonnement

Diese Codebeispiele zeigen, wie Sie ein Graph-API-Abonnement erstellen. Sie enthalten 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",
    "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": "2026-08-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: Updated und Deleted (Created wird von der Graph-API nicht unterstützt; siehe die Graph-API-Dokumentation für weitere Details). 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>. Um den Standort (auch bekannt als Azure-Region) zu erhalten, nameführe den az account list-locations Befehl aus. Verwenden Sie keinen Anzeigenamen für den Ort. Beispielsweise sollten Sie nicht „USA, Westen-Mitte“ verwenden. Verwenden Sie stattdessen westcentralus.

    az account list-locations

  • lifecycleNotificationUrl: eine URI, die verwendet wird, um das Partnerthema zu definieren, an das microsoft.graph.subscriptionReauthorizationRequired Ereignisse gesendet werden. Dieses Ereignis signalisiert Ihre Anwendung, dass das Graph-API-Abonnement bald abläuft. Die URI folgt demselben Muster wie notificationUrl zuvor beschrieben, wenn Sie Event Grid als Ziel für Lebenszyklusereignisse verwenden. In diesem Fall sollte das Partnerthema mit dem in notificationUrl angegebenen identisch sein.

  • resource: die Ressource, die Ereignisse erzeugt, die Zustandsänderungen ankündigen.

  • expirationDateTime: die Ablaufzeit, zu der das Abonnement abläuft und der Ablauf der Ereignisse stoppt. Sie muss dem in der Request for Comments (RFC) 3339 angegebenen Format entsprechen. Sie müssen eine Ablaufzeit angeben, die innerhalb der maximal zulässigen Abonnementlänge pro Ressourcentyp liegt.

  • clientState: Verwenden Sie diese optionale Eigenschaft, um Aufrufe an Ihre Ereignishandler-Anwendung während der Ereignisauslieferung zu verifizieren. 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 lifecycleNotificationUrl Eigenschaft hinzuzufügen, löschen Sie das bestehende Abonnement und erstellen Sie ein neues Abonnement, das die Eigenschaft während der Abonnementerstellung angibt.

Nach dem Erstellen eines Graph-API-Abonnements haben Sie ein Partnerthema, das in Azure erstellt wurde.

Verlängern eines Microsoft Graph-API-Abonnements

Verlängern Sie das Graph-API-Abonnement, bevor es abläuft, um das Beenden des Ereignisflusses zu vermeiden. Um den Verlängerungsprozess zu automatisieren, unterstützt die Microsoft Graph-API Lebenszyklus-Benachrichtigungsereignisse, für die Anwendungen abonniert werden können. Derzeit unterstützen alle Arten von Microsoft Graph-API-Ressourcen das microsoft.graph.subscriptionReauthorizationRequired Ereignis, das gesendet wird, wenn eine der folgenden Bedingungen eintritt:

  • Der Zugangstoken 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 das Graph-API-Abonnement nach Ablauf nicht verlängert wird, erstellen Sie ein neues Graph-API-Abonnement. Du kannst auf dasselbe Partnerthema verweisen, das im abgelaufenen Abonnement verwendet wurde, solange es 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 musst du einen anderen Partner-Themennamen 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

Wenn Ihre Anwendung ein microsoft.graph.subscriptionReauthorizationRequired Ereignis erhält, sollte sie das Graph-API-Abonnement erneuern:

  1. Wenn Sie beim Erstellen des Graph-API-Abonnements ein Client-Geheimnis in der ClientState-Eigenschaft bereitgestellt haben, enthält das Ereignis dieses Client-Geheimnis. Überprüfen Sie, ob der clientState des Ereignisses mit dem Wert übereinstimmt, der beim Erstellen des Graph-API-Abonnements verwendet wird.

  2. Stellen Sie sicher, dass die App über ein gültiges Zugriffstoken verfügt, um den nächsten Schritt auszuführen. Der Abschnitt mit den folgenden Mustern mit detaillierten Anweisungen bietet weitere Informationen.

  3. 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": "2026-09-30T11:00:00.0000000Z"
}

      Die Verlängerung könnte scheitern, wenn die App nicht mehr berechtigt ist, auf die Ressource zuzugreifen. Die App muss dann möglicherweise ein neues Zugriffstoken erhalten, um ein Abonnement neu 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. Seien Sie darauf vorbereitet, Ihren Endpunkt regelmäßig neu 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.

Wenn Sie Ihr Graph-API-Abonnement verlängern oder neu autorisieren, verwendet es dasselbe Partnerthema, das Sie bei der Erstellung des Abonnements angegeben haben.

Wenn Sie einen neuen Ablaufdatum angeben, achten Sie darauf, dass es mindestens drei Stunden vom aktuellen Zeitpunkt entfernt ist. Andernfalls empfängt Ihre Anwendung microsoft.graph.subscriptionReauthorizationRequired Ereignisse möglicherweise bald nach der Verlängerung.

Beispiele dafür, wie Sie Ihr Graph-API-Abonnement mit einer der unterstützten Sprachen neu autorisieren können, finden Sie unter Subscription Reauthorize Request.

Beispiele dafür, wie Sie Ihr Graph-API-Abonnement verlängern und neu autorisieren können, indem Sie eine der unterstützten Sprachen verwenden, finden Sie unter Update-Abonnement-Anfrage.

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 ein Graph-API-Abonnement. Um ein Abonnement zu verlängern, rufen Sie die Graph-API auf, indem Sie die Codeschnipsel aus How to renew a Graph-API Subscription verwenden.
  • Rufen Sie Authentifizierungstoken ab, um sie beim Aufrufen der Microsoft Graph-API zu verwenden.

Hinweis

Sie können Ihr Graph-API-Abonnement mit dem Microsoft Graph-API Explorer 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
  • Node.js 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.

Wichtig

Benötigen Sie Beispielcode für eine andere Sprache oder Haben Sie Fragen? E-Mail ask-graph-and-grid@microsoft.com.

Verwandte Inhalte

Um Microsoft Graph-API-Ereignisse über Event Grid zu empfangen, führen Sie diese beiden Schritte aus:

  • Last updated on