Empfangen von Änderungsbenachrichtigungen über Azure Event Hubs

Artikel
10/14/2024

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.

Wichtig

Die Authentifizierung von Event Hubs mithilfe von Shared Access Signatures (SAS) ist in Zukunft veraltet. Es wird empfohlen, Event Hubs stattdessen mithilfe Microsoft Entra ID rollenbasierten Zugriffssteuerung (Role-Based Access Control, RBAC) zu authentifizieren.

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

Azure Event Hubs unterstützt die Authentifizierung entweder über Shared Access Signatures (SAS) oder Microsoft Entra ID rollenbasierte Zugriffssteuerung (Role-Based Access Control, RBAC). Weitere Informationen finden Sie unter Autorisieren des Zugriffs auf Azure Event Hubs.

In diesem Abschnitt wird veranschaulicht, wie Sie Azure Event Hubs-Authentifizierung mithilfe Microsoft Entra ID rollenbasierten Zugriffssteuerung (Role-Based Access Control, RBAC) auf dem Azure-Portal einrichten.

Konfigurieren des Event Hubs

Melden Sie sich beim Azure-Portal mit Berechtigungen zum Erstellen von Ressourcen in Ihrem Azure-Abonnement an.
Wählen Sie Ressource erstellen aus, geben Sie Event Hubs in die Suchleiste ein, und wählen Sie dann den Event Hubs-Vorschlag aus.
Wählen Sie auf der Seite Event Hubs-Erstellung die Option Erstellen aus.
Geben Sie die Details zur Erstellung des Event Hubs-Namespaces ein, und wählen Sie dann Erstellen aus.
Wenn der Event Hubs-Namespace bereitgestellt wird, wechseln Sie zur Seite für den Namespace.
Wählen Sie Event Hubs und dann + Event Hub aus.
Geben Sie dem neuen Event Hub einen Namen, und wählen Sie Erstellen aus.
Nachdem der Event Hub erstellt wurde, wechseln Sie zum Event Hubs-Namespace, und wählen Sie dann auf der Randleiste Access Control (IAM) aus.
Wählen Sie Rollenzuweisungen aus.
Wählen Sie + Hinzufügen und dann Rollenzuweisung hinzufügen aus.
Wechseln Sie unter Rolle zu Auftragsfunktionsrollen, wählen Sie Azure Event Hubs Datensender und dann Weiter aus.
Wählen Sie auf der Registerkarte Mitglieder die Option Zugriff auf Benutzer, Gruppe oder Dienstprinzipal zuweisen aus.
Wählen Sie + Mitglieder auswählen aus, suchen Sie nach Microsoft Graph Änderungsnachverfolgung, und wählen Sie sie aus.
Wählen Sie Überprüfen + zuweisen aus, um den Vorgang abzuschließen.

In diesem Abschnitt wird veranschaulicht, wie Sie Azure Event Hubs-Authentifizierung mithilfe von Shared Access Signatures (SAS) über die Azure CLI einrichten.

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.

Wichtig

Die Authentifizierung von Event Hubs mithilfe von Shared Access Signatures (SAS) ist in Zukunft veraltet. Es wird empfohlen, stattdessen Microsoft Entra ID rollenbasierte Zugriffssteuerung (Role-Based Access Control, RBAC) zu verwenden. Befolgen Sie die Anleitung zum Migrieren zu RBAC.

# --------------
# 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}"

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

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

Verwenden von RBAC
Verwenden von Key Vault

Wenn Sie die rollenbasierte Zugriffssteuerung verwenden, sieht die notificationUrl-Eigenschaft wie folgt aus:

EventHub:https://<eventhubnamespace>.servicebus.windows.net/eventhubname/<eventhubname>?tenantId=<domainname>

<eventhubnamespace> ist der Name, den Sie dem Event Hubs-Namespace geben. Sie finden sie auf der Übersichtsseite für Event Hubs unter Hostname.
<eventhubname> ist der Name, den Sie dem Event Hub geben. Sie finden sie unter Event Hubs –> Übersicht –> Event Hubs.
<domainname> ist der Name Ihres Mandanten; Beispiel: contoso.com. Da diese Domäne für den Zugriff auf die Azure Event Hubs verwendet wird, ist es wichtig, dass sie mit der Domäne übereinstimmt, die vom Azure-Abonnement verwendet wird, das die Azure Event Hubs enthält. Um diese Informationen zu erhalten, wählen Sie im Azure-Portal das Menü Microsoft Entra ID aus, und überprüfen Sie die Seite Übersicht. Der Domänenname wird unter der primären Domäne angezeigt.

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 dem Schlüsseltresor während der Erstellung gegeben haben. Er befindet sich im DNS-Namen.
<secretname> – Der Name, den Sie dem Geheimnis während der Erstellung gegeben haben. Sie finden sie auf der Seite Azure Key Vault Geheimnisse.
<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. Um diese Informationen zu erhalten, können Sie zur Übersichtsseite der Azure-Key Vault navigieren, die Sie erstellt haben, und das Abonnement auswählen. 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.

Migrieren einer Event Hub-Authentifizierung zu Microsoft Entra ID RBAC

In diesem Abschnitt erfahren Sie, wie Sie Ihre vorhandenen Event Hubs mit SAS-Authentifizierung zu Microsoft Entra ID RBAC-Authentifizierung migrieren. Verwenden Sie denselben Event Hub-Namespace, den Sie für die SAS-Authentifizierung verwendet haben, entweder über die Azure CLI oder die Azure-Portal.

Erstellen Sie unter demselben Event Hub-Namespace, den Sie für Ihr vorhandenes Abonnement verwenden, einen neuen Event Hub.
Erstellen Sie ein neues Abonnement mit den gleichen Details wie das vorhandene Abonnement, außer mit dem Namen des neuen Event Hubs aus dem vorherigen Schritt in der URL. Weitere Informationen finden Sie unter Erstellen des Abonnements: Verwenden von RBAC.

Sie erhalten Benachrichtigungen auf dem neuen Event Hub. Sie können überprüfen, ob der Datenverkehr dem alten Abonnement ähnelt, indem Sie das Diagramm Nachrichten für den Event Hub überprüfen. Überprüfen Sie außerdem, ob fehler oder fehler beim Empfangen von Benachrichtigungen vorliegen.

Nachdem Sie überprüft haben, dass Sie Benachrichtigungen erhalten und der neue Event Hub ordnungsgemäß funktioniert, können Sie das alte Abonnement, den alten Event Hub und die SAS-basierte Authentifizierung löschen und mit der Verwendung des neuen Abonnements beginnen.

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

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

Erstellen Sie ein Speicherkonto.
Erstellen Sie einen Container im Speicherkonto. Der Containername muss auf microsoft-graph-change-notificationsfestgelegt werden.
Rufen Sie die Zugriffsschlüssel des Speicherkontos oder Verbindungszeichenfolge ab.
Fügen Sie die Verbindungszeichenfolge dem Schlüsseltresor hinzu, und geben Sie ihm einen Namen. Dieser Wert ist der Geheimnisname.
Erstellen Sie Ihr Abonnement, oder erstellen Sie es neu, und fügen Sie nun die Eigenschaft blobStoreUrl in die folgende Syntax ein: 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')


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipalsWithAppId("{appId}").GetAsync();



mgc service-principals-with-app-id get --app-id {app-id}



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  //other-imports
)


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
appId := "{appId}"
servicePrincipals, err := graphClient.ServicePrincipalsWithAppId(&appId).Get(context.Background(), nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

ServicePrincipal result = graphClient.servicePrincipalsWithAppId("{appId}").get();

Snippet not available


<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->servicePrincipalsWithAppId('{appId}', )->get()->wait();


Import-Module Microsoft.Graph.Applications

Get-MgServicePrincipalByAppId


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.service_principals_with_app_id("{appId}").get()

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


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new ServicePrincipal
{
	AppId = "0bf30f3b-4a52-48df-9a82-234910c4a086",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipals.PostAsync(requestBody);



mgc service-principals create --body '{\
    "appId": "0bf30f3b-4a52-48df-9a82-234910c4a086"\
}\
'



// Code snippets are only available for the latest major version. Current major version is $v1.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

requestBody := graphmodels.NewServicePrincipal()
appId := "0bf30f3b-4a52-48df-9a82-234910c4a086"
requestBody.SetAppId(&appId) 

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
servicePrincipals, err := graphClient.ServicePrincipals().Post(context.Background(), requestBody, nil)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

ServicePrincipal servicePrincipal = new ServicePrincipal();
servicePrincipal.setAppId("0bf30f3b-4a52-48df-9a82-234910c4a086");
ServicePrincipal result = graphClient.servicePrincipals().post(servicePrincipal);


const options = {
	authProvider,
};

const client = Client.init(options);

const servicePrincipal = {
    appId: '0bf30f3b-4a52-48df-9a82-234910c4a086'
};

await client.api('/servicePrincipals')
	.post(servicePrincipal);


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\ServicePrincipal;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new ServicePrincipal();
$requestBody->setAppId('0bf30f3b-4a52-48df-9a82-234910c4a086');

$result = $graphServiceClient->servicePrincipals()->post($requestBody)->wait();


Import-Module Microsoft.Graph.Applications

$params = @{
	appId = "0bf30f3b-4a52-48df-9a82-234910c4a086"
}

New-MgServicePrincipal -BodyParameter $params


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.service_principal import ServicePrincipal
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = ServicePrincipal(
	app_id = "0bf30f3b-4a52-48df-9a82-234910c4a086",
)

result = await graph_client.service_principals.post(request_body)

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

Übersicht über Änderungsbenachrichtigungen
Sehen Sie sich die folgenden Azure Event Hubs-Schnellstarts an:
- .NET Core
- Java
- Python
- JavaScript

Freigeben über

Empfangen von Änderungsbenachrichtigungen über Azure Event Hubs

Verwenden von Azure Event Hubs zum Empfangen von Änderungsbenachrichtigungen

Einrichten der Azure Event Hubs-Authentifizierung

Konfigurieren des Event Hubs

Konfigurieren des Event Hubs

Konfigurieren der Azure-Key Vault

Erstellen des Abonnements und Empfangen von Benachrichtigungen

Erstellen des Abonnements

Migrieren einer Event Hub-Authentifizierung zu Microsoft Entra ID RBAC

Empfangen von Benachrichtigungen

Behandeln von Validierungsbenachrichtigungen

Abonnements für umfangreiche Benachrichtigungen mit großen Nutzlasten

Einrichten von Speicher und Erstellen eines Abonnements

Empfangen umfangreicher Benachrichtigungen

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

Feedback

Zusätzliche Ressourcen

Freigeben über

Empfangen von Änderungsbenachrichtigungen über Azure Event Hubs

Verwenden von Azure Event Hubs zum Empfangen von Änderungsbenachrichtigungen

Einrichten der Azure Event Hubs-Authentifizierung

Konfigurieren des Event Hubs

Erstellen des Abonnements und Empfangen von Benachrichtigungen

Erstellen des Abonnements

Migrieren einer Event Hub-Authentifizierung zu Microsoft Entra ID RBAC

Empfangen von Benachrichtigungen

Behandeln von Validierungsbenachrichtigungen

Abonnements für umfangreiche Benachrichtigungen mit großen Nutzlasten

Einrichten von Speicher und Erstellen eines Abonnements

Empfangen umfangreicher Benachrichtigungen

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

Verwandte Inhalte

Feedback

Zusätzliche Ressourcen