Teilen über

Übermitteln von Ereignissen an Webhooks mithilfe von Namespacethemen: Azure-Befehlszeilenschnittstelle (Vorschau)

  • Artikel

Dieser Artikel enthält eine Schritt-für-Schritt-Anleitung zur Veröffentlichung von Ereignissen in Azure Event Grid im CloudEvents-JSON-Format und zum Zustellen dieser Ereignisse unter Verwendung des Pushübermittlungsmodells. Um spezifisch zu sein, verwenden Sie die Azure-Befehlszeilenschnittstelle und Curl, um Ereignisse in einem Namespacethema in Event Grid zu veröffentlichen und diese Ereignisse von einem Ereignisabonnement an einen Webhookhandler zu pushen. Weitere Informationen zum Pushübermittlungsmodell finden Sie unter Übersicht über Pushübermittlung.

Hinweis

Die Event Grid-Erweiterung der Azure CLI unterstützt noch keine Namespaces und darin enthaltene Ressourcen. Wir verwenden die Azure CLI-Ressource, um Event Grid-Ressourcen zu erstellen.

Wenn Sie kein Azure-Abonnement haben, erstellen Sie ein kostenloses Azure-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, installieren Sie die Azure CLI. Wenn Sie Windows oder macOS ausführen, 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. Führen Sie die in Ihrem Terminal angezeigten Schritte aus, um den Authentifizierungsprozess abzuschließen. Informationen zu anderen Anmeldeoptionen finden Sie unter Anmelden mit der Azure CLI.

    • Installieren Sie die Azure CLI-Erweiterung beim ersten Einsatz, wenn Sie dazu aufgefordert werden. 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 das Upgrade auf die aktuelle Version durchzuführen.

  • Für diesen Artikel ist mindestens Version 2.0.70 der Azure CLI erforderlich. Bei Verwendung von Azure Cloud Shell ist die aktuelle Version bereits installiert.

Aktivieren des Event Grid-Ressourcenanbieters

  1. Wenn Sie zuvor in Ihrem Azure-Abonnement noch nicht Event Grid verwendet haben, sollten Sie 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. Sie verwenden diese Ressourcengruppe, um alle in diesem Artikel erstellten Ressourcen zu enthalten.

Die allgemeinen Schritte zur Verwendung von Cloud Shell zum Ausführen von Befehlen sind:

  • Klicken Sie auf Cloud Shell öffnen, damit ein Azure Cloud Shell-Fenster im rechten Bereich angezeigt wird.
  • Kopieren Sie den Befehl, und fügen Sie ihn in das Azure Cloud Shell-Fenster ein.
  • Drücken Sie die EINGABETASTE, um den Befehl auszuführen.

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

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

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

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

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

Erstellen eines Namespace

Ein Event Grid-Namespace stellt einen benutzerdefinierten Endpunkt bereit, an dem Sie Ihre Ereignisse bereitstellen. Im folgenden Beispiel wird ein Namespace in Ihrer Ressourcengruppe mithilfe von Bash in der Azure Cloud Shell erstellt. Der Namespace-Name muss eindeutig sein, da er Teil eines DNS-Eintrags (Domain Name System) ist. Ein Namespacename sollte die folgenden Regeln einhalten:

  • Er sollte zwischen 3 und 50 Zeichen lang sein.
  • Es sollte regional eindeutig sein.
  • Zulässige Zeichen sind nur: a bis z, A bis Z, 0 bis 9 und „-“.
  • Es sollte nicht mit reservierten Schlüsselwortpräfixen wie Microsoft, System oder EventGrid beginnen.

  1. Deklarieren Sie eine Variable, die den Namen für Ihren Event Grid-Namespace enthält. 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 eines Namespaces Möglicherweise möchten Sie den Ort ändern, an dem es bereitgestellt wird.

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

Erstellen eines Namespacethemas

Erstellten Sie ein Thema, um alle Ereignisse zu speichern, die am Namespaceendpunkt veröffentlicht werden.

  1. Deklarieren Sie eine Variable, die den Namen für Ihr Namespacethema enthält. Geben Sie einen Namen für das Namespacethema 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 eines Nachrichtenendpunkts

Vor dem Abonnieren des Namespacethemas erstellen Sie zunächst den Endpunkt für die Ereignisnachricht. Der Endpunkt führt in der Regel Aktionen auf der Grundlage der Ereignisdaten aus. Um diesen Schnellstart zu vereinfachen stellen Sie eine vorab erstellte Web-App bereit, welche die Ereignisnachrichten anzeigt. Die bereitgestellte Lösung umfasst einen App Service-Plan, eine App Service-Web-App und Quellcode von GitHub.

  1. Kopieren Sie den folgenden Befehl, geben Sie einen Namen für die Web-App an (Event Grid Viewer-Beispiel), und drücken Sie die EINGABETASTE, um den Befehl auszuführen. Ersetzen Sie <your-site-name> durch einen eindeutigen Namen für Ihre Web-App. Der Name der Web-App muss eindeutig sein, da er Teil des DNS-Eintrags ist.

    sitename="<your-site-name>"

  2. Führen Sie az deployment group create aus, um die Web-App mithilfe einer Azure Resource Manager-Vorlage bereitzustellen.

    az deployment group create \
  --resource-group $resource_group \
  --template-uri "https://raw.githubusercontent.com/Azure-Samples/azure-event-grid-viewer/master/azuredeploy.json" \
  --parameters siteName=$sitename hostingPlanName=viewerhost

Die Bereitstellung kann einige Minuten dauern. Nach erfolgreichem Abschluss der Bereitstellung können Sie Ihre Web-App anzeigen und sich vergewissern, dass sie ausgeführt wird. Navigieren Sie hierzu in einem Webbrowser zu https://<your-site-name>.azurewebsites.net. Die Website sollte angezeigt werden, und es sollten momentan keine Nachrichten vorliegen.

Übermitteln von Ereignissen an den Azure Event Grid Viewer-Webhook

Erstellen Sie ein Ereignisabonnement zur Pushübermittlung für den Namespace, und verwenden Sie dazu den Webhook für Azure Event Grid Viewer.

  1. Definieren Sie eine Variable für den Namen des Ereignisabonnements.

    event_subscription="<your_event_subscription_name>"

  2. Ersetzen Sie EVENTGRIDWEBSITENAME durch den Namen der Event Grid Viewer-Website. Beispiel: contosoegridviewer

    az resource create --api-version 2024-06-01-preview --resource-group $resource_group --namespace Microsoft.EventGrid --resource-type eventsubscriptions --name $event_subscription --parent namespaces/$namespace/topics/$topic --location $location --properties "{\"eventDeliverySchema\": \"CloudEventSchemaV1_0\",\"deliveryConfiguration\":{\"deliveryMode\":\"Push\",\"push\":{\"destination\":{\"endpointType\":\"WebHook\",\"properties\":{\"endpointUrl\":\"https:\/\/$sitename.azurewebsites.net\/api/updates\"}}}}}"

Senden von Ereignissen an Ihr Thema

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

Auflisten von Namespacezugriffsschlüsseln

  1. Rufen Sie die Zugriffsschlüssel ab, die dem erstellten Namespace zugeordnet sind. Sie verwenden einen davon, um sich beim Veröffentlichen von Ereignissen zu authentifizieren. Um Ihre Schlüssel aufzulisten, benötigen Sie zunächst die vollständige Namespaceressourcen-ID. Rufen Sie sie ab, indem Sie den folgenden Befehl ausführen:

    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 Hostnamen des Namespaces ab. Sie erstellen damit den HTTP-Endpunkt des Namespaces, an den Ereignisse gesendet werden. Die folgenden Operationen waren erstmals mit der API-Version 2023-06-01-preview verfügbar.

    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 CloudEvents-kompatibles Beispielereignis:

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

    Bei dem data-Element handelt es sich um die Nutzlast Ihres Ereignisses. Für dieses Feld kann ein beliebiger wohlgeformter JSON-Code verwendet werden. Weitere Informationen zu Eigenschaften (auch als Kontextattribute bezeichnet), die in ein Ereignis einfließen können, finden Sie in den CloudEvents-Spezifikationen.

  3. Verwenden Sie CURL, um das Ereignis an das Thema zu senden. CURL ist ein Hilfsprogramm zum Senden von HTTP-Anforderungen.

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

Überprüfen des Ereignisempfangs durch Azure Event Grid Viewer

Überprüfen Sie, ob in der Azure Event Grid Viewer-Web-App die Ereignisse angezeigt werden, die von Event Grid empfangen wurden.

Screenshot von Azure Event Grid Viewer mit einem empfangenen Beispielereignis

Zugehöriger Inhalt

In diesem Schnellstart haben Sie einen Webhook als Ereignishandler verwendet. Einen Schnellstart mit Azure Event Hub als Ereignishandler finden Sie unter Übermitteln von Ereignissen an Azure Event Hubs mithilfe von Namespacethemen.