In Namespace-Themen veröffentlichen und Ereignisse im Azure Event Grid konsumieren

  • Artikel

Dieser Artikel bietet eine kurze Einführung in die Pull-Delivery unter Verwendung des curl Bash-Shell-Befehls zum Veröffentlichen, Empfangen und Bestätigen von Ereignissen. Event Grid-Ressourcen werden mit CLI-Befehlen erstellt. Dieser Artikel eignet sich für einen schnellen Test der Pull-Delivery-Funktionalität. Beispielcode für die Verwendung der SDKs für die Datenebene finden Sie in den .NET- oder Java-Beispielen. Für Java stellen wir den Beispielcode in zwei Artikeln zur Verfügung: Veröffentlichung von Ereignissen und Empfang von Ereignissen Schnellstarts. Weitere Informationen über das Pull-Delivery-Modell finden Sie in den Artikeln Konzepte und Überblick über Pull-Delivery.

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.

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

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

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

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 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 eastus

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 Ereignisabonnements

Erstellen Sie ein Ereignisabonnement, indem Sie seinen Übermittlungsmodus auf Warteschlange festlegen, was Pullübermittlung unterstützt. Weitere Informationen zu allen Konfigurationsoptionen finden Sie in der neuesten Event Grid Steuerungsebenen-REST-API.

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

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

  2. Erstellen Sie ein Ereignisabonnement für das Namespacethema:

    az eventgrid namespace topic event-subscription create -g $resource_group --topic-name $topic -n $event_subscription --namespace-name $namespace --delivery-configuration "{deliveryMode:Queue,queue:{receiveLockDurationInSeconds:300,maxDeliveryCount:4,eventTimeToLive:P1D}}"

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

Empfangen des Ereignisses

Sie empfangen Ereignisse von Event Grid mithilfe eines Endpunkts, der sich auf ein Ereignisabonnement bezieht.

  1. Erstellen Sie diesen Endpunkt, indem Sie den folgenden Befehl ausführen:

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

  2. Senden Sie eine Anforderung, um das Ereignis zu nutzen:

    curl -X POST -H "Content-Type: application/json" -H "Authorization:SharedAccessKey $key" $receive_operation_uri

Bestätigen eines Ereignisses

Nachdem Sie ein Ereignis empfangen haben, übergeben Sie dieses Ereignis zur Verarbeitung an Ihre Anwendung. Nachdem Sie Ihr Ereignis erfolgreich verarbeitet haben, müssen Sie dieses Ereignis nicht mehr in Ihrem Ereignisabonnement enthalten sein. Um Event Grid anzuweisen, das Ereignis zu löschen, bestätigen Sie es mithilfe seines Sperrtokens, das Sie in der Antwort des Empfangsvorgangs erhalten haben.

  1. Im vorherigen Schritt sollten Sie eine Antwort erhalten haben, die ein brokerProperties-Objekt mit einer lockToken-Eigenschaft enthält. Kopieren Sie den Wert des Sperrtokens, und legen Sie eine Umgebungsvariable darauf fest:

    lockToken="<paste-the-lock-token-here>"

  2. Erstellen Sie nun die Nutzlast des Bestätigungsvorgangs, die das Sperrtoken für das Ereignis angibt, das bestätigt werden soll.

    acknowledge_request_payload=' { "lockTokens": ["'$lockToken'"]} '

  3. Fahren Sie mit dem Erstellen der Zeichenfolge mit dem Bestätigungsvorgangs-URI fort:

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

  4. Senden Sie abschließend eine Anforderung zur Bestätigung des empfangenen Ereignisses:

    curl -X POST -H "Content-Type: application/json" -H "Authorization:SharedAccessKey $key" -d "$acknowledge_request_payload" $acknowledge_operation_uri

    Wenn der Bestätigungsvorgang ausgeführt wird, bevor das Sperrtoken abläuft (300 Sekunden, wie beim Erstellen des Ereignisabonnements festgelegt), sollte eine Antwort wie die folgende angezeigt werden:

    {"succeededLockTokens":["CiYKJDQ4NjY5MDEyLTk1OTAtNDdENS1BODdCLUYyMDczNTYxNjcyMxISChDZae43pMpE8J8ovYMSQBZS"],"failedLockTokens":[]}

Nächste Schritte

Weitere Informationen zum Pullübermittlungsmodell finden Sie unter Überblick über Pullübermittlung.