Freigeben über

Tutorial: Weiterleiten von Ereignissen vom Typ „Richtlinienzustandsänderung“ an Event Grid mithilfe der Azure CLI

  • Artikel

In diesem Artikel erfahren Sie, wie Sie Azure Policy-Ereignisabonnements einrichten, um Ereignisse vom Typ „Richtlinienzustandsänderung“ an einen Webendpunkt zu senden. Azure Policy-Benutzer können Ereignisse abonnieren, die ausgegeben werden, wenn sich der Richtlinienzustand für Ressourcen ändert. Diese Ereignisse können Webhooks, Azure Functions, Azure Storage-Warteschlangen oder andere Ereignishandler auslösen, die von Azure Event Grid unterstützt werden. Üblicherweise senden Sie Ereignisse an einen Endpunkt, der die Ereignisdaten verarbeitet und entsprechende Aktionen ausführt. Der Einfachheit halber werden die Ereignisse in diesem Tutorial allerdings an eine Web-App gesendet, die die Nachrichten sammelt und anzeigt.

Voraussetzungen

  • Wenn Sie kein Azure-Abonnement besitzen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.

  • Für diesen Schnellstart muss mindestens Version 2.0.76 der Azure CLI ausgeführt werden. Führen Sie az --version aus, um die Version zu finden. Informationen zum Durchführen einer Installation oder eines Upgrades finden Sie bei Bedarf unter Installieren der Azure CLI.

Azure Cloud Shell

Azure hostet Azure Cloud Shell, eine interaktive Shell-Umgebung, die Sie über Ihren Browser nutzen können. Sie können entweder Bash oder PowerShell mit Cloud Shell verwenden, um mit Azure-Diensten zu arbeiten. Sie können die vorinstallierten Befehle von Cloud Shell verwenden, um den Code in diesem Artikel auszuführen, ohne etwas in Ihrer lokalen Umgebung installieren zu müssen.

Starten von Azure Cloud Shell:

Option Beispiel/Link
Wählen Sie rechts oben in einem Code- oder Befehlsblock die Option Ausprobieren aus. Durch die Auswahl von Ausprobieren wird der Code oder Befehl nicht automatisch in Cloud Shell kopiert. Screenshot that shows an example of Try It for Azure Cloud Shell.
Rufen Sie https://shell.azure.com auf, oder klicken Sie auf die Schaltfläche Cloud Shell starten, um Cloud Shell im Browser zu öffnen. Button to launch Azure Cloud Shell.
Wählen Sie im Azure-Portal rechts oben im Menü die Schaltfläche Cloud Shell aus. Screenshot that shows the Cloud Shell button in the Azure portal

So verwenden Sie Azure Cloud Shell:

  1. Starten Sie Cloud Shell.

  2. Wählen Sie die Schaltfläche Kopieren für einen Codeblock (oder Befehlsblock) aus, um den Code oder Befehl zu kopieren.

  3. Fügen Sie den Code oder Befehl mit STRG+UMSCHALT+V unter Windows und Linux oder CMD+UMSCHALT+V unter macOS in die Cloud Shell-Sitzung ein.

  4. Drücken Sie die EINGABETASTE, um den Code oder Befehl auszuführen.

Erstellen einer Ressourcengruppe

Event Grid-Themen sind Azure-Ressourcen und müssen in einer Azure-Ressourcengruppe platziert werden. Die Azure-Ressourcengruppe ist eine logische Sammlung, in der Azure-Ressourcen bereitgestellt und verwaltet werden.

Erstellen Sie mithilfe des Befehls az group create eine Ressourcengruppe.

Im folgenden Beispiel wird eine Ressourcengruppe mit dem Namen <resource_group_name> am Standort westus erstellt. Ersetzen Sie <resource_group_name> durch einen eindeutigen Namen für Ihre Ressourcengruppe.

# Log in first with az login if you're not using Cloud Shell

az group create --name <resource_group_name> --location westus

Erstellen eines Event Grid-Systemthemas

Nachdem wir nun über eine Ressourcengruppe verfügen, erstellen wir als Nächstes ein Systemthema. Ein Systemthema in Event Grid stellt mindestens ein Ereignis dar, das von Azure-Diensten wie Azure Policy und Azure Event Hubs veröffentlicht wurde. Von diesem Systemthema wird der Thementyp Microsoft.PolicyInsights.PolicyStates für Azure Policy-Zustandsänderungen verwendet.

Zunächst müssen Sie die Ressourcenanbieter (RP) PolicyInsights und EventGrid im entsprechenden Verwaltungsbereich registrieren. Während das Azure-Portal alle Ressourcenanbieter, die Sie zum ersten Mal aufrufen, automatisch registriert, ist dies bei der Azure CLI nicht der Fall.

# Log in first with az login if you're not using Cloud Shell

# Register the required RPs at the management group scope
az provider register --namespace Microsoft.PolicyInsights -m <managementGroupId>
az provider register --namespace Microsoft.EventGrid -m <managementGroupId>

# Alternatively, register the required RPs at the subscription scope (defaults to current subscription context)
az provider register --namespace Microsoft.PolicyInsights
az provider register --namespace Microsoft.EventGrid

Als nächstes ersetzen Sie <subscriptionId> im Parameter scope durch die ID Ihres Abonnements und <resource_group_name> im Parameter resource-group durch die zuvor erstellte Ressourcengruppe.

az eventgrid system-topic create --name PolicyStateChanges --location global --topic-type Microsoft.PolicyInsights.PolicyStates --source "/subscriptions/<subscriptionId>" --resource-group "<resource_group_name>"

Wenn Ihr Event Grid-Systemthema auf den Verwaltungsgruppenbereich angewendet wird, weicht die Syntax des Azure CLI-Parameters --source etwas ab. Hier sehen Sie ein Beispiel:

az eventgrid system-topic create --name PolicyStateChanges --location global --topic-type Microsoft.PolicyInsights.PolicyStates --source "/tenants/<tenantID>/providers/Microsoft.Management/managementGroups/<management_group_name>" --resource-group "<resource_group_name>"

Erstellen eines Nachrichtenendpunkts

Vor dem Abonnieren des Themas erstellen wir zunächst den Endpunkt für die Ereignisnachricht. Der Endpunkt führt in der Regel Aktionen auf der Grundlage der Ereignisdaten aus. Der Einfachheit halber stellen Sie in dieser Schnellstartanleitung eine vorgefertigte Web-App bereit, die die Ereignisnachrichten anzeigt. Die bereitgestellte Lösung umfasst einen App Service-Plan, eine App Service-Web-App und Quellcode von GitHub.

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.

# Log in first with az login if you're not using Cloud Shell

az deployment group create \
  --resource-group <resource_group_name> \
  --template-uri "https://raw.githubusercontent.com/Azure-Samples/azure-event-grid-viewer/master/azuredeploy.json" \
  --parameters siteName=<your-site-name> 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.

Abonnieren des Systemthemas

Sie abonnieren ein Thema, um Event Grid mitzuteilen, welche Ereignisse Sie nachverfolgen möchten und wohin sie gesendet werden sollen. Im folgenden Beispiel wird das von Ihnen erstellte Systemthema abonniert. Außerdem wird die URL Ihrer Web-App als Endpunkt für den Empfang von Ereignisbenachrichtigungen übergeben. Ersetzen Sie <event_subscription_name> durch einen Namen für Ihr Ereignisabonnement. Verwenden Sie für <resource_group_name> und <your-site-name> jeweils den zuvor erstellten Wert.

Der Endpunkt für Ihre Web-App muss das Suffix /api/updates/ enthalten.

# Log in first with az login if you're not using Cloud Shell

# Create the subscription
az eventgrid system-topic event-subscription create \
  --name <event_subscription_name> \
  --resource-group <resource_group_name> \
  --system-topic-name PolicyStateChanges \
  --endpoint https://<your-site-name>.azurewebsites.net/api/updates

Zeigen Sie wieder Ihre Web-App an. Wie Sie sehen, wurde ein Abonnementüberprüfungsereignis an sie gesendet. Klicken Sie auf das Augensymbol, um die Ereignisdaten zu erweitern. Event Grid sendet das Überprüfungsereignis, damit der Endpunkt bestätigen kann, dass er Ereignisdaten empfangen möchte. Die Web-App enthält Code zur Überprüfung des Abonnements.

Screenshot of the Event Grid subscription validation event in the pre-built web app.

Erstellen einer Richtlinienzuweisung

In dieser Schnellstartanleitung wird eine Richtlinienzuweisung erstellt und die Definition Tag für Ressourcengruppen erforderlich zugewiesen. Diese Richtliniendefinition dient dazu, Ressourcengruppen zu identifizieren, bei denen das im Rahmen der Richtlinienzuweisung konfigurierte Tag fehlt.

Führen Sie den folgenden Befehl aus, um eine Richtlinienzuweisung zu erstellen, die auf die Ressourcengruppe ausgerichtet ist, die Sie für das Event Grid-Thema erstellt haben:

# Log in first with az login if you're not using Cloud Shell

az policy assignment create --name 'requiredtags-events' --display-name 'Require tag on RG' --scope '<resourceGroupScope>' --policy '<policy definition ID>' --params '{ \"tagName\": { \"value\": \"EventTest\" } }'

In dem Befehl werden folgende Informationen verwendet:

  • Name: Der tatsächliche Name der Zuweisung. Für dieses Beispiel wurde requiredtags-events verwendet.
  • DisplayName: Der Anzeigename für die Richtlinienzuweisung. In diesem Fall wird Require tag on RG verwendet.
  • Bereich: Ein Bereich bestimmt, für welche Ressourcen oder Ressourcengruppe die Richtlinienzuweisung erzwungen wird. Er kann von einem Abonnement bis zu Ressourcengruppen reichen. Ersetzen Sie <scope> durch den Namen Ihrer Ressourcengruppe. Ein Ressourcengruppenbereich hat folgendes Format: /subscriptions/<subscriptionId>/resourceGroups/<resourceGroup>.
  • Richtlinie: Die Richtliniendefinitions-ID, auf deren Grundlage Sie die Zuweisung erstellen. In diesem Fall handelt es sich hierbei um die ID der Richtliniendefinition Tag für Ressourcengruppen erforderlich. Führen Sie den folgenden Befehl aus, um die Richtliniendefinitions-ID abzurufen: az policy definition list --query "[?displayName=='Require a tag on resource groups']"

Warten Sie nach dem Erstellen der Richtlinienzuweisung, bis in der Web-App eine Ereignisbenachrichtigung vom Typ Microsoft.PolicyInsights.PolicyStateCreated angezeigt wird. Der Wert data.complianceState der erstellten Ressourcengruppe lautet zunächst NonCompliant (Nicht konform).

Screenshot of the Event Grid subscription Policy State Created event for the resource group in the pre-built web app.

Hinweis

Wenn die Ressourcengruppe andere Richtlinienzuweisungen aus der Abonnement- oder Verwaltungsgruppenhierarchie erbt, werden entsprechende Ereignisse ebenfalls angezeigt. Vergewissern Sie sich, dass das Ereignis die Zuweisung in diesem Tutorial betrifft, indem Sie die Eigenschaft data.policyDefinitionId auswerten.

Auslösen einer Änderung für die Ressourcengruppe

Die Ressourcengruppe ist konform, wenn ein Tag mit dem Namen EventTest vorhanden ist. Fügen Sie das Tag mithilfe des folgenden Befehls der Ressourcengruppe hinzu, und ersetzen Sie dabei <subscriptionId> durch Ihre Abonnement-ID und <resourceGroup> durch den Namen der Ressourcengruppe:

# Log in first with az login if you're not using Cloud Shell

az tag create --resource-id '/subscriptions/<SubscriptionID>/resourceGroups/<resourceGroup>' --tags EventTest=true

Warten Sie, bis in der Web-App eine Ereignisbenachrichtigung vom Typ Microsoft.PolicyInsights.PolicyStateChanged angezeigt wird, Nachdem Sie der Ressourcengruppe das erforderliche Tag hinzugefügt haben. Erweitern Sie das Ereignis. Daraufhin sehen Sie, dass der Wert data.complianceState nun Compliant (Konform) lautet.

Problembehandlung

Wenn Sie eine der folgenden Fehlermeldungen erhalten, vergewissern Sie sich, dass Sie beide Ressourcenanbieter in dem Bereich, den Sie abonnieren (Verwaltungsgruppe oder Abonnement), registriert haben:

  • Deployment has failed with the following error: {"code":"Publisher Notification Error","message":"Failed to enable publisher notifications.","details":[{"code":"Publisher Provider Error","message":"GET request for <uri> failed with status code: Forbidden, code: AuthorizationFailed and message: The client '<identifier>' with object id '<identifier>' does not have authorization to perform action 'microsoft.policyinsights/eventGridFilters/read' over scope '<scope>/providers/microsoft.policyinsights/eventGridFilters/_default' or the scope is invalid. If access was recently granted, please refresh your credentials.."}]}
  • Deployment has failed with the following error: {'code':'Publisher Notification Error','message':'Failed to enable publisher notifications.','details':[{'code':'ApiVersionNotSupported','message':'Event Grid notifications are currently not supported by microsoft.policyinsights in global. Try re-registering Microsoft.EventGrid provider if this is your first event subscription in this region.'}]}

Bereinigen von Ressourcen

Wenn Sie diese Web-App und das Azure Policy-Ereignisabonnement weiterverwenden möchten, überspringen Sie die Bereinigung der in diesem Artikel erstellten Ressourcen. Führen Sie andernfalls den folgenden Befehl aus, um die in diesem Artikel erstellten Ressourcen zu löschen.

Ersetzen Sie <resource_group_name> durch die weiter oben erstellte Ressourcengruppe.

az group delete --name <resource_group_name>

Nächste Schritte

Sie haben gelernt, wie Sie Themen und Ereignisabonnements für Azure Policy erstellen. Nun können Sie sich eingehender über Ereignisse vom Typ „Richtlinienzustandsänderung“ sowie über die Möglichkeiten von Event Grid informieren: