Quickstart: Liefere Ereignisse an Azure Event Hubs mithilfe von Namespace-Themen (Azure CLI)

In diesem Quickstart verwendet man die Azure CLI, um Ereignisse in einem Event Grid Namespace-Thema im CloudEvents JSON-Format zu veröffentlichen und diese Ereignisse dann an einen Azure Event Hubs-Handler zu übertragen. Du erstellst die Event-Grid- und Event Hubs-Ressourcen, konfigurierst eine verwaltete Identität für eine sichere Übertragung und sendest ein Beispielereignis über cURL.

Durch die Verwendung von Azure Event Grid-Namespace-Themen können Sie Events veröffentlichen und sie an Handler wie Azure Event Hubs liefern. Die Lieferung von Ereignissen an Event Hubs ist nützlich, wenn Sie hochvolumige Ereignisströme oder Telemetrie für Downstream-Analysen, Speicher oder weitere Verarbeitung sammeln müssen.

Wenn Sie nicht über ein Azure-Konto verfügen, erstellen Sie ein kostenloses Konto , bevor Sie beginnen.

Voraussetzungen

  • Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter Schnellstart für Bash in Azure Cloud Shell.

  • Wenn Sie CLI-Referenzbefehle lieber lokal ausführen möchten, installieren Sie die Azure CLI. Wenn Sie mit Windows oder macOS arbeiten, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.

    • Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an. Um den Authentifizierungsprozess abzuschließen, führen Sie die schritte aus, die in Ihrem Terminal angezeigt werden. Informationen zu anderen Anmeldeoptionen finden Sie unter Anmelden mit der Azure CLI.

    • Wenn Sie dazu aufgefordert werden, installieren Sie die Azure CLI-Erweiterung bei der ersten Verwendung. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden von Erweiterungen mit der Azure CLI.

    • Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um auf die neueste Version zu aktualisieren.

  • Dieser Quickstart erfordert Version 2.53.0 oder höher der Azure CLI. Die Befehle az eventgrid namespace stammen aus der eventgrid Erweiterung, Version 2.51.0 oder neuer, die sich beim ersten Ausführen eines dieser Befehle automatisch installiert. Wenn Sie Azure Cloud Shell verwenden, ist die neueste Version bereits installiert.

Aktivieren des Event Grid-Ressourcenanbieters

  1. Wenn Sie "Event Grid" zum ersten Mal in Ihrem Azure-Abonnement verwenden, müssen Sie möglicherweise den Event Grid-Ressourcenanbieter registrieren. Führen Sie den folgenden Befehl aus, um den Anbieter zu registrieren:

    az provider register --namespace Microsoft.EventGrid

  2. Es kann einen Moment dauern, bis die Registrierung abgeschlossen ist. Führen Sie den folgenden Befehl aus, um den Status zu überprüfen:

    az provider show --namespace Microsoft.EventGrid --query "registrationState"

    Wenn registrationStateRegistered ist, können Sie den Vorgang fortsetzen.

Erstellen einer Ressourcengruppe

Erstellen Sie mit dem Befehl az group create eine Azure-Ressourcengruppe. Nutze diese Ressourcengruppe, um alle Ressourcen zu speichern, die du in diesem Quickstart erstellst.

  1. Deklarieren Sie eine Variable, die den Namen einer Azure-Ressourcengruppe enthalten soll. Geben Sie einen Namen für die Ressourcengruppe an, indem Sie <your-resource-group-name> durch einen von Ihnen gewünschten Wert ersetzen.

    resource_group="<your-resource-group-name>"

    location="<your-resource-group-location>"

  2. Erstellen Sie eine Ressourcengruppe. Ändern Sie den Ort, wie Sie es für richtig halten.

    az group create --name $resource_group --location $location

Erstellen eines Event Grid-Namespace

Ein Event Grid-Namespace stellt einen benutzerdefinierten Endpunkt bereit, für den Sie Ihre Ereignisse bereitstellen. Das folgende Beispiel erstellt einen Namespace in Ihrer Ressourcengruppe, indem Bash in Azure Cloud Shell verwendet wird. Der Namespacename muss eindeutig sein, da er Teil eines DNS-Eintrags (Domain Name System) ist. Ein Namespacename sollte die folgenden Regeln erfüllen:

  • Es sollte zwischen 3 und 50 Zeichen sein.
  • Es sollte regional einzigartig sein.
  • Erlaubte Zeichen sind a-z, A-Z, 0-9 und -.
  • Er sollte nicht mit reservierten Schlüsselwortpräfixen wie Microsoft, System oder EventGrid beginnen.

  1. Deklarieren Sie eine Variable, die den Namen für den Event Grid-Namespace enthalten soll. Geben Sie einen Namen für den Namespace an, indem Sie <your-namespace-name> durch einen gewünschten Wert ersetzen.

    namespace="<your-namespace-name>"

  2. Erstellen Sie einen Namespace. Möglicherweise möchten Sie den Speicherort ändern, an dem er bereitgestellt wird.

    az eventgrid namespace create -g $resource_group -n $namespace -l $location

Erstellen Sie ein Event Grid Namespace-Thema

Erstellen Sie ein Thema, um alle Ereignisse zu speichern, die im Namensraum-Endpunkt veröffentlicht werden.

  1. Deklarieren Sie eine Variable, die den Namen für Ihr Namespacethema enthält. Geben Sie einen Namen für das Namensraumthema an, indem Sie <your-topic-name> durch einen gewünschten Wert ersetzen.

    topic="<your-topic-name>"

  2. Erstellen Sie Ihr Namespacethema:

    az eventgrid namespace topic create -g $resource_group -n $topic --namespace-name $namespace

Erstellen einer neuen Event Hubs-Ressource

Erstellen Sie eine Event Hubs-Ressource, die Sie als Handler-Ziel für das Namespace-Themen-Push-Delivery-Abonnement verwenden.

  1. Deklarieren Sie eine Variable für den Namen des Event Hubs-Namespace.

    eventHubsNamespace="<your-event-hubs-namespace-name>"

  2. Erstellen Sie den Event Hubs-Namespace.

    az eventhubs namespace create --resource-group $resource_group --name $eventHubsNamespace --location $location

  3. Deklarieren Sie eine Variable für den Event Hub-Namen.

    eventHubsEventHub="<your-event-hub-name>"

  4. Führen Sie den folgenden Befehl aus, um einen Event Hub im Namespace zu erstellen.

    az eventhubs eventhub create --resource-group $resource_group --namespace-name $eventHubsNamespace --name $eventHubsEventHub

Übertragung von Ereignissen an Event Hubs mithilfe einer verwalteten Identität

Um Events in Event-Hubs in Ihrem Event Hubs-Namensraum mithilfe einer verwalteten Identität zu liefern, folgen Sie diesen Schritten:

  1. Aktivieren Sie vom System zugewiesene oder vom Benutzer zugewiesene verwaltete Identität: Namespaces. Lesen Sie weiter zum nächsten Abschnitt, um herauszufinden, wie Sie eine verwaltete Identität mit Azure CLI aktivieren können.
  2. Fügen Sie die Identität der Rolle Azure Event Hubs-Datensender im Event Hubs-Namespace hinzu. Um zu erfahren, wie man die Rollenzuweisung addiert, siehe den nächsten Abschnitt.
  3. Aktivieren Sie in Ihrem Event Hubs-Namespace die Einstellung Vertrauenswürdigen Microsoft-Diensten die Umgehung dieser Firewall erlauben?.
  4. Konfigurieren Sie das Ereignisabonnement, das einen Event Hub als Endpunkt verwendet, um die vom System zugewiesene oder vom Benutzer zugewiesene verwaltete Identität zu verwenden.

Aktivieren der verwalteten Identität im Event Grid-Namespace

Aktivieren Sie die systemzugewiesene verwaltete Identität im Event Grid Namensraum.

az eventgrid namespace update --resource-group $resource_group --name $namespace --identity "{type:SystemAssigned}"

Hinzufügen von Rollenzuweisungen in Event Hubs für die verwaltete Identität für Event Grid

  1. Abrufen der vom Event Grid-Namespacesystem verwalteten Identitätsprinzipal-ID.

    principalId=$(az eventgrid namespace show --resource-group $resource_group --name $namespace --query identity.principalId -o tsv)

  2. Abrufen der Event Hubs Event Hub-Ressourcen-ID.

    eventHubResourceId=$(az eventhubs eventhub show --resource-group $resource_group --namespace-name $eventHubsNamespace --name $eventHubsEventHub --query id -o tsv)

  3. Fügen Sie in Event Hubs eine Rollenzuweisung für die systemseitig verwaltete Identität für Event Grid hinzu.

    az role assignment create --role "Azure Event Hubs Data Sender" --assignee $principalId --scope $eventHubResourceId

Erstellen eines Ereignisabonnements

Erstellen Sie ein Push-Delivery-Event-Abonnement, das die verwaltete Identität des Event Grid-Namensraums verwendet, um Ereignisse an Ihr Event Hub zu liefern.

event_subscription="<your-event-subscription-name>"

az eventgrid namespace topic event-subscription create --resource-group $resource_group --namespace-name $namespace --topic-name $topic --name $event_subscription --delivery-configuration "{deliveryMode:Push,push:{maxDeliveryCount:10,deliveryWithResourceIdentity:{identity:{type:SystemAssigned},destination:{endpointType:EventHub,properties:{resourceId:$eventHubResourceId}}}}}"

Senden Sie ein Testereignis an das Namespace-Thema

Senden Sie nun ein Beispielereignis an das Namespacethema, indem Sie die schritte in diesem Abschnitt ausführen.

Namespace-Zugriffsschlüssel auflisten

  1. Rufen Sie die Zugriffsschlüssel ab, die dem von Ihnen erstellten Namespace zugeordnet sind. Nutze eines davon, um dich beim Veröffentlichen von Veranstaltungen zu authentifizieren. Um Ihre Schlüssel auflisten zu können, benötigen Sie zuerst die vollständige Namespaceressourcen-ID. Führen Sie den folgenden Befehl aus, um es zu erhalten.

    namespace_resource_id=$(az eventgrid namespace show -g $resource_group -n $namespace --query "id" --output tsv)

  2. Rufen Sie den ersten Schlüssel aus dem Namespace ab:

    key=$(az eventgrid namespace list-key -g $resource_group --namespace-name $namespace --query "key1" --output tsv)

Veröffentlichen eines Ereignisses

  1. Rufen Sie den Namespace-Hostnamen ab. Nutze es, um den HTTP-Endpunkt des Namensraums zu komponieren, an den du Ereignisse sendest.

    publish_operation_uri="https://"$(az eventgrid namespace show -g $resource_group -n $namespace --query "topicsConfiguration.hostname" --output tsv)"/topics/"$topic:publish?api-version=2023-06-01-preview

  2. Erstellen sie ein Beispiel für ein CloudEvents-kompatibles Ereignis:

    event=' { "specversion": "1.0", "id": "'"$RANDOM"'", "type": "com.yourcompany.order.ordercreatedV2", "source" : "/mycontext", "subject": "orders/O-234595", "time": "'`date +%Y-%m-%dT%H:%M:%SZ`'", "datacontenttype" : "application/json", "data":{ "orderId": "O-234595", "url": "https://yourcompany.com/orders/o-234595"}} '

    Das data Element ist die Nutzlast Ihres Ereignisses. Für dieses Feld kann ein beliebiger wohlgeformter JSON-Code verwendet werden. Für weitere Informationen zu Eigenschaften (auch bekannt als Kontextattribute), die in ein Ereignis aufgenommen werden können, siehe die CloudEvents-Spezifikationen .

  3. Verwenden Sie cURL, um das Ereignis an das Thema zu senden. cURL ist ein Dienstprogramm, das HTTP-Anfragen sendet.

    curl -X POST -H "Content-Type: application/cloudevents+json" -H "Authorization:SharedAccessKey $key" -d "$event" $publish_operation_uri

    Im Azure-Portal gehen Sie auf Ihre Event Hubs-Namensraumseite, aktualisieren Sie die Seite und überprüfen Sie, ob der Zähler für eingehende Nachrichten im Diagramm zeigt, dass ein Ereignis empfangen wurde.

    Screenshot der Seite

Bereinigen von Ressourcen

Wenn du die von dir erstellten Ressourcen nicht mehr brauchst, lösche sie, um zusätzliche Kosten zu vermeiden. Löschen Sie die Ressourcengruppe und alle darin enthaltenen Ressourcen:

az group delete --name $resource_group

Nächste Schritte

In diesem Quickstart haben Sie den Event Grid Namespace und Event Hubs Ressourcen erstellt und konfiguriert und Events an einen Event Hub verschoben. Um zu erfahren, wie man Events von einem Event Hub empfängt, siehe diese Tutorials:

  • Last updated on