Empfangen von Änderungsbenachrichtigungen über Azure Event Hubs

  • Artikel

Webhooks eignen sich nicht für den Empfang von Änderungsbenachrichtigungen in Szenarien mit hohem Durchsatz oder wenn der Empfänger keine öffentlich verfügbare Benachrichtigungs-URL verfügbar machen kann. Alternativ können Sie Azure Event Hubs verwenden.

Beispiele für Szenarien mit hohem Durchsatz, in denen Sie Azure Event Hubs verwenden können, sind Anwendungen, die eine große Menge von Ressourcen abonnieren, Anwendungen, die Ressourcen abonnieren, die sich häufig ändern, und mehrinstanzenfähige Anwendungen, die Ressourcen in einer großen Gruppe von Organisationen abonnieren.

Der Artikel führt Sie durch den Prozess der Verwaltung Ihres Microsoft Graph-Abonnements und den Empfang von Änderungsbenachrichtigungen über Azure Event Hubs.

Verwenden von Azure Event Hubs zum Empfangen von Änderungsbenachrichtigungen

Azure Event Hubs ist ein beliebter Echtzeitereignis-Erfassungs- und Verteilungsdienst, der für große Maßstäbe entwickelt wurde. Die Verwendung von Azure Event Hubs für den Erhalt von Änderungsbenachrichtigungen unterscheidet sich in mehrfacher Hinsicht von Webhooks, darunter:

  • Sie sind nicht auf öffentlich verfügbare Benachrichtigungs-URLs angewiesen. Das Event Hubs SDK leitet die Benachrichtigungen an Ihre Anwendung weiter.
  • Sie müssen auf die Überprüfung der Benachrichtigungs-URL nicht antworten. Sie können die empfangene Überprüfungsnachricht ignorieren.
  • Sie müssen einen Event Hub bereitstellen.
  • Sie müssen eine Azure-Key Vault bereitstellen oder den Microsoft Graph Änderungsnachverfolgung-Dienst der Rolle "Datensender" auf Ihrem Event Hub hinzufügen.

Einrichten der Azure Event Hubs-Authentifizierung

Mit der Azure CLI können Sie Administrative Aufgaben in Azure erstellen und automatisieren. Die CLI kann auf Ihrem lokalen Computer installiert werden oder direkt über die Azure Cloud Shell ausgeführt werden.

# --------------
# TODO: update the following values
#sets the name of the resource group
resourcegroup=rg-graphevents-dev
#sets the location of the resources
location='uk south'
#sets the name of the Azure Event Hubs namespace
evhamespacename=evh-graphevents-dev
#sets the name of the hub under the namespace
evhhubname=graphevents
#sets the name of the access policy to the hub
evhpolicyname=grapheventspolicy
#sets the name of the Azure KeyVault
keyvaultname=kv-graphevents
#sets the name of the secret in Azure KeyVault that will contain the connection string to the hub
keyvaultsecretname=grapheventsconnectionstring
# --------------
az group create --location $location --name $resourcegroup
az eventhubs namespace create --name $evhamespacename --resource-group $resourcegroup --sku Basic --location $location
az eventhubs eventhub create --name $evhhubname --namespace-name $evhamespacename --resource-group $resourcegroup --partition-count 2 --message-retention 1
az eventhubs eventhub authorization-rule create --name $evhpolicyname --eventhub-name $evhhubname --namespace-name $evhamespacename --resource-group $resourcegroup --rights Send
evhprimaryconnectionstring=`az eventhubs eventhub authorization-rule keys list --name $evhpolicyname --eventhub-name $evhhubname --namespace-name $evhamespacename --resource-group $resourcegroup --query "primaryConnectionString" --output tsv`
az keyvault create --name $keyvaultname --resource-group $resourcegroup --location $location --enable-soft-delete true --sku standard --retention-days 90
az keyvault secret set --name $keyvaultsecretname --value $evhprimaryconnectionstring --vault-name $keyvaultname --output none
graphspn=`az ad sp list --display-name 'Microsoft Graph Change Tracking' --query "[].appId" --output tsv`
az keyvault set-policy --name $keyvaultname --resource-group $resourcegroup --secret-permissions get --spn $graphspn --output none
keyvaulturi=`az keyvault show --name $keyvaultname --resource-group $resourcegroup --query "properties.vaultUri" --output tsv`
domainname=`az ad signed-in-user show --query 'userPrincipalName' | cut -d '@' -f 2 | sed 's/\"//'`
notificationUrl="EventHub:${keyvaulturi}secrets/${keyvaultsecretname}?tenantId=${domainname}"
echo "Notification Url:\n${notificationUrl}"

Hinweis: Das hier bereitgestellte Skript ist mit Linux-basierten Shells, Windows WSL und Azure Cloud Shell kompatibel. Für die Ausführung in Windows-Shells sind einige Updates erforderlich.

Create des Abonnements und Empfangen von Benachrichtigungen

Nachdem Sie die erforderlichen Azure KeyVault- und Azure Event Hubs-Dienste erstellt haben, können Sie jetzt Ihr Abonnement für Änderungsbenachrichtigungen erstellen und mit dem Empfangen von Änderungsbenachrichtigungen über Azure Event Hubs beginnen.

Create des Abonnements

Das Erstellen eines Abonnements zum Empfangen von Änderungsbenachrichtigungen mit Event Hubs ist nahezu identisch mit der Erstellung eines Webhookabonnements, weist jedoch wichtige Änderungen in der notificationUrl-Eigenschaft auf. Überprüfen Sie zunächst die Schritte zur Erstellung eines Webhookabonnements , bevor Sie fortfahren.

Bei der Abonnementerstellung muss notificationUrl auf Ihren Event Hubs-Speicherort verweisen.

Wenn Sie Key Vault verwenden, sieht die notificationUrl-Eigenschaft wie folgt aus: EventHub:https://<azurekeyvaultname>.vault.azure.net/secrets/<secretname>?tenantId=<domainname>, mit den folgenden Werten:

  • azurekeyvaultname: der Name, den Sie beim Erstellen des Schlüsseltresors angegeben haben. Sie finden ihn im DNS-Namen.
  • secretname: der Name, den Sie beim Erstellen des geheimen Schlüssels angegeben haben. Sie finden ihn auf der Azure Key Vault-Seite Geheime Schlüssel.
  • domainname - Der Name Ihres Mandanten; beispiel: contoso.com. Da diese Domäne für den Zugriff auf die Azure-Key Vault verwendet wird, ist es wichtig, dass sie mit der Domäne übereinstimmt, die vom Azure-Abonnement verwendet wird, das die Azure-Key Vault enthält. Diese Informationen können Sie abrufen, indem Sie zur Seite "Übersicht" des von Ihnen erstellten Azure Key Vaults wechseln und auf das Abonnement klicken. Der Domänenname wird im Feld Verzeichnis angezeigt.

Hinweis

Doppelte Abonnements sind nicht zulässig. Wenn eine Abonnementanforderung die gleichen Werte für changeType und die Ressource enthält, die ein vorhandenes Abonnement enthält, schlägt die Anforderung mit einem HTTP-Fehlercode 409 Conflictund der Fehlermeldung Subscription Id <> already exists for the requested combinationfehl.

Empfangen von Benachrichtigungen

Änderungsbenachrichtigungen werden jetzt von Event Hubs an Ihre Anwendung übermittelt. Ausführliche Informationen finden Sie unter Empfangen von Ereignissen in der Dokumentation zu Event Hubs.

Bevor Sie die Benachrichtigungen in Ihrer Anwendung erhalten können, müssen Sie eine weitere SAS-Richtlinie mit der Berechtigung "Lauschen" erstellen und die Verbindungszeichenfolge abrufen, ähnlich den Schritten unter Konfigurieren des Event Hubs.

Tipp

Create eine separate Richtlinie für die Anwendung, die auf Event Hubs-Nachrichten lauscht, anstatt die gleichen Verbindungszeichenfolge wiederzuverwenden, die Sie in Azure KeyVault festgelegt haben. Diese Trennung folgt dem Prinzip der geringsten Rechte, indem sichergestellt wird, dass jede Komponente der Lösung nur über die erforderlichen Berechtigungen verfügt.

Behandeln von Validierungsbenachrichtigungen

Ihre Anwendung empfängt Validierungsbenachrichtigungen, wenn sie ein neues Abonnement erstellt. Sie sollten diese Benachrichtigungen ignorieren. Das folgende Beispiel stellt den Text einer Gültigkeitsprüfungsmeldung dar.

 {
    "value":[
        {
            "subscriptionId":"NA",
            "subscriptionExpirationDateTime":"NA",
            "clientState":"NA",
            "changeType":"Validation: Testing client application reachability for subscription Request-Id: 522a8e7e-096a-494c-aaf1-ac0dcfca45b7",
            "resource":"NA",
            "resourceData":{
                "@odata.type":"NA",
                "@odata.id":"NA",
                "id":"NA"
            }
        }
    ]
}

Abonnements für umfangreiche Benachrichtigungen mit großen Nutzlasten

Die maximale Nachrichtengröße für Event Hubs beträgt 1 MB. Wenn Sie umfangreiche Benachrichtigungen verwenden, erwarten Sie möglicherweise Benachrichtigungen, die diesen Grenzwert überschreiten. Zum Empfangen von Benachrichtigungen, die größer als 1 MB über Event Hubs sind, müssen Sie ihrer Abonnementanforderung auch ein Blob Storage-Konto hinzufügen.

Einrichten von Speicher und Erstellen eines Abonnements

  1. Create ein Speicherkonto.
  2. Create einen Container im Speicherkonto, und weisen Sie ihm einen Namen zu.
  3. Rufen Sie die Zugriffsschlüssel des Speicherkontos oder Verbindungszeichenfolge ab.
  4. Fügen Sie die Verbindungszeichenfolge dem Schlüsseltresor hinzu, und geben Sie ihm einen Namen. Dieser Wert ist der Geheimnisname.
  5. Create Oder erstellen Sie Ihr Abonnement neu, einschließlich der blobStoreUrl-Eigenschaft in der folgenden Syntax:blobStoreUrl: "https://<azurekeyvaultname>.vault.azure.net/secrets/<secretname>?tenantId=<domainname>"

Empfangen umfangreicher Benachrichtigungen

Wenn Event Hubs eine Benachrichtigungsnutzlast empfängt, die größer als 1 MB ist, enthält die Benachrichtigung nicht die Eigenschaften resource, resourceData und encryptedContent , die in umfangreichen Benachrichtigungen enthalten sind. Die Benachrichtigung enthält stattdessen eine additionalPayloadStorageId-Eigenschaft mit einer ID, die auf das Blob in Ihrem Speicherkonto verweist, in dem diese Eigenschaften gespeichert sind.

Was geschieht, wenn die Anwendung Microsoft Graph Änderungsnachverfolgung fehlt?

Der Microsoft Graph-Änderungsnachverfolgung-Dienstprinzipal fehlt möglicherweise in Ihrem Mandanten, je nachdem, wann der Mandant erstellt wurde und administrative Vorgänge ausgeführt wurden. Die global eindeutige appId des Dienstprinzipals lautet 0bf30f3b-4a52-48df-9a82-234910c4a086 , und Sie können die folgende Abfrage ausführen, um zu überprüfen, ob sie im Mandanten vorhanden ist.

GET https://graph.microsoft.com/v1.0/servicePrincipals(appId='0bf30f3b-4a52-48df-9a82-234910c4a086')

Wenn der Dienstprinzipal nicht vorhanden ist, erstellen Sie ihn wie folgt. Sie müssen der aufrufenden App die Berechtigung Application.ReadWrite.All erteilen, um diesen Vorgang auszuführen.

Methode 1

POST https://graph.microsoft.com/v1.0/servicePrincipals
Content-type: application/json

{
    "appId": "0bf30f3b-4a52-48df-9a82-234910c4a086"
}

Methode 2

POST https://graph.microsoft.com/v1.0/servicePrincipals(appId='0bf30f3b-4a52-48df-9a82-234910c4a086')
Content-type: application/json
Prefer: create-if-missing

{
    "displayName": "Microsoft Graph Change Tracking"
}

Verwandte Inhalte