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

  • Artikel

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 stabilen Funktionen für ereignisgesteuerte Modelle und Veröffentlichen/Abonnieren 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 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 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:

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

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:

  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, 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:

Weitere nützliche Links: