Freigeben über

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. Wenn Sie diese Ereignisse über Das Azure Event Grid abonnieren, erstellen Sie ereignisgesteuerte Anwendungen, die auf Ressourcenänderungen in Echtzeit 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.
  • Leiten Sie Ereignisse mithilfe der Filter- und Routingfunktionen von Event Grid an mehrere Ziele weiter.

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

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 ihre Erstellung, Aktualisierung und Löschung ankündigen, unterstützt. Ausführliche Informationen zu den Ressourcen, für die Ereignisse von Ereignisquellen ausgelöst werden, finden Sie in den durch Änderungsbenachrichtigungen der Microsoft Graph-API unterstützten 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. Das Partnerthema wird automatisch als Teil der Graph-API-Abonnementerstellung erstellt. 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 sollte ich Ereignisse aus Microsoft Graph-API-Quellen über das Ereignisraster abonnieren?

Neben dem Abonnieren von Microsoft Graph-API-Ereignissen über Das Ereignisraster haben Sie weitere Optionen zum Empfangen ähnlicher Benachrichtigungen (nicht von Ereignissen). 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.
  • 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 basierend auf einigen Eigenschaften im Ereignis an verschiedene downstream-Anwendungen, Webhooks oder Azure-Dienste weiterleiten. Beispielsweise möchten Sie Ereignistypen wie Microsoft.Graph.UserCreated 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. 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 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 ereignisgesteuerte Ansätze, die von der Branche übernommen werden.

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

Erfüllen Sie diese allgemeinen Voraussetzungen, bevor Sie Ihre Anwendung zum Erstellen und Verlängern von Microsoft Graph-API-Abonnements implementieren:

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 in den Beispielen mit detaillierten Anweisungen im Abschnitt mit detaillierten Anweisungen , sie sollten jedoch alle Abschnitte in diesem Artikel lesen, da sie mehr, 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

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,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 sind Updated, Deleted und Created. 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 stattdessen westcentralus. 
      az account list-locations
  • lifecycleNotificationUrl: ein URI, der verwendet wird, um das Partnerthema zu definieren, an das microsoft.graph.subscriptionReauthorizationRequiredEreignisse 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

Verlängern Sie das Graph-API-Abonnement, bevor es abläuft, um das Beenden des Ereignisflusses zu vermeiden. Um den Erneuerungsprozess zu automatisieren, unterstützt die Microsoft Graph-API Lebenszyklusbenachrichtigungsereignisse , für die Anwendungen abonniert werden können. 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 das Graph-API-Abonnement nach Ablauf nicht verlängert wird, erstellen Sie ein neues Graph-API-Abonnement. Verweisen Sie auf das Partnerthema, das im abgelaufenen Abonnement verwendet wurde, sofern das Abonnement seit weniger als 30 Tagen 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:

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

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

  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": "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, stellen Sie sicher, dass sie mindestens drei Stunden von der aktuellen Uhrzeit entfernt ist. 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
  • 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

Führen Sie die folgenden beiden Schritte aus, um den Empfang von Microsoft Graph-API-Ereignissen mithilfe des Ereignisrasters einzurichten:

  • Last updated on