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

  • 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 über 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 den unterstützten Ressourcen von Microsoft Graph-API-Änderungsbenachrichtigungen .

Wichtig

Die Möglichkeit der Microsoft Graph-API, Ereignisse an Azure Event Grid zu senden, befindet sich derzeit in der öffentlichen Vorschau. Sollten Sie Fragen haben oder Support benötigen, senden Sie uns eine E-Mail an ask-graph-and-grid@microsoft.com.

Microsoft-Ereignisquelle Verfügbare Ereignistypen
Microsoft Entra ID Microsoft Entra-Ereignistypen
Microsoft Outlook Microsoft Outlook-Ereignistypen
Microsoft 365-Gruppenunterhaltungen
Microsoft Teams Microsoft Teams-Ereignistypen
Microsoft SharePoint und OneDrive
Microsoft SharePoint
Sicherheitswarnungen
Microsoft Conversations
Microsoft Universal Print

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 abhängig von einigen der Eigenschaften im Ereignis an verschiedene downstream-Anwendungen, Webhooks oder Azure-Dienste weiterleiten. Sie können z. B. Ereignistypen wie Microsoft.Graph.UserCreated und Microsoft.Graph.UserDeleted an eine spezielle Anwendung weiterleiten, die das Onboarding und das Offboarding der Benutzer verarbeitet. Sie können auch Ereignisse an eine andere Anwendung senden Microsoft.Graph.UserUpdated , die z. B. 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 mithilfe des CloudEvents-Spezifikationsstandards von CNCF weiterleiten und verarbeiten.
  • Sie möchten die Erweiterbarkeitsunterstützung von CloudEvents verwenden. Wenn Sie z. B. Ereignisse über kompatible Systeme hinweg nachverfolgen möchten, verwenden Sie die Verteilte Ablaufverfolgung der CloudEvents-Erweiterung. 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-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 in den Beispielen 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 speicherorte. 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 oben beschriebenen Muster "notificationUrl ", wenn "Event Grid" als Ziel für Lebenszyklusereignisse verwendet wird. In diesem Fall sollte das Partnerthema mit dem in notificationUrl angegebenen identisch sein.
  • ressource: die Ressource, die Ereignisse generiert, die Zustandsänderungen ankündigen.
  • expirationDateTime: Die Ablaufzeit, zu der das Abonnement abläuft, und der Ablauf von Ereignissen wird beendet. Er muss dem in RFC 3339 angegebenen Format entsprechen. Sie müssen eine Ablaufzeit angeben, die innerhalb der maximal zulässigen Abonnementlänge pro Ressourcentyp liegt.
  • client state: Diese Eigenschaft ist optional. Sie 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

  • Der Name des Partnerthemas muss 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.

Hinweis

Wenn Ihre Anwendung den Header x-ms-enable-features mit Ihrer Anforderung zum Erstellen eines Graph-API-Abonnements während der privaten Vorschau verwendet, sollten Sie ihn entfernen, da es nicht mehr erforderlich ist.

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

Verlängern eines Microsoft Graph-API-Abonnements

Ein Graph-API-Abonnement muss von Ihrer Anwendung verlängert werden, 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 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 ablaufen 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 Partnerthemanamen 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 in den kommenden Beispielen 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ängerung"-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 microsoft.graph.subscriptionReauthorizationRequired Ihre Anwendung 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 Updateabonnementanforderung.For examples about how to renew and reauthorize your Graph API subscription subscription request..

Beispiele mit detaillierten Anweisungen

Die Microsoft Graph-API-Dokumentation enthält Codebeispiele mit Anweisungen zu:

  • Richten Sie Ihre Entwicklungsumgebung mit bestimmten Anweisungen entsprechend der verwendeten Sprache ein. Anweisungen umfassen auch das Abrufen eines Microsoft 365-Mandanten für Entwicklungszwecke.
  • Erstellen Sie eine Graph-API-Abonnements. Um ein Abonnement zu verlängern, können Sie die Graph-API mithilfe der Codeausschnitte in "Verlängern eines Graph-API-Abonnements oben" 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. Dies 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
    • GraphAPIController enthält Beispielcode zum Erstellen, Löschen und Verlängern eines Graph-API-Abonnements. Sie muss zusammen mit der obigen Java-Beispielanwendung verwendet werden.
  • 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 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: