title | description | ms.date | ms.topic | ms.custom |
---|---|---|---|---|
Quickstart: Send custom events to web endpoint - Event Grid, PowerShell |
Quickstart: Use Azure Event Grid and PowerShell to publish a custom topic, and subscribe to events for that topic. The events are handled by a web application. |
07/01/2021 |
quickstart |
devx-track-azurepowershell, mode-api |
Azure Event Grid is an eventing service for the cloud. In this article, you use the Azure PowerShell to create a custom topic, subscribe to the topic, and trigger the event to view the result. Typically, you send events to an endpoint that processes the event data and takes actions. However, to simplify this article, you send the events to a web app that collects and displays the messages.
When you're finished, you see that the event data has been sent to the web app.
[!INCLUDE updated-for-az]
[!INCLUDE quickstarts-free-trial-note.md]
This article requires that you are running the latest version of Azure PowerShell. If you need to install or upgrade, see Install and configure Azure PowerShell.
Event Grid topics are Azure resources, and must be placed in an Azure resource group. The resource group is a logical collection into which Azure resources are deployed and managed.
Create a resource group with the New-AzResourceGroup command.
The following example creates a resource group named gridResourceGroup in the westus2 location.
New-AzResourceGroup -Name gridResourceGroup -Location westus2
[!INCLUDE event-grid-register-provider-powershell.md]
An event grid topic provides a user-defined endpoint that you post your events to. The following example creates the custom topic in your resource group. Replace <your-topic-name>
with a unique name for your topic. The topic name must be unique because it's part of the DNS entry. Additionally, it must be between 3-50 characters and contain only values a-z, A-Z, 0-9, and "-"
$topicname="<your-topic-name>"
New-AzEventGridTopic -ResourceGroupName gridResourceGroup -Location westus2 -Name $topicname
Before subscribing to the topic, let's create the endpoint for the event message. Typically, the endpoint takes actions based on the event data. To simplify this quickstart, you deploy a pre-built web app that displays the event messages. The deployed solution includes an App Service plan, an App Service web app, and source code from GitHub.
Replace <your-site-name>
with a unique name for your web app. The web app name must be unique because it's part of the DNS entry.
$sitename="<your-site-name>"
New-AzResourceGroupDeployment `
-ResourceGroupName gridResourceGroup `
-TemplateUri "https://raw.githubusercontent.com/Azure-Samples/azure-event-grid-viewer/master/azuredeploy.json" `
-siteName $sitename `
-hostingPlanName viewerhost
The deployment may take a few minutes to complete. After the deployment has succeeded, view your web app to make sure it's running. In a web browser, navigate to: https://<your-site-name>.azurewebsites.net
You should see the site with no messages currently displayed.
You subscribe to a topic to tell Event Grid which events you want to track and where to send those events. The following example subscribes to the topic you created, and passes the URL from your web app as the endpoint for event notification.
The endpoint for your web app must include the suffix /api/updates/
.
$endpoint="https://$sitename.azurewebsites.net/api/updates"
New-AzEventGridSubscription `
-EventSubscriptionName demoViewerSub `
-Endpoint $endpoint `
-ResourceGroupName gridResourceGroup `
-TopicName $topicname
View your web app again, and notice that a subscription validation event has been sent to it. Select the eye icon to expand the event data. Event Grid sends the validation event so the endpoint can verify that it wants to receive event data. The web app includes code to validate the subscription.
Let's trigger an event to see how Event Grid distributes the message to your endpoint. First, let's get the URL and key for the topic.
$endpoint = (Get-AzEventGridTopic -ResourceGroupName gridResourceGroup -Name $topicname).Endpoint
$keys = Get-AzEventGridTopicKey -ResourceGroupName gridResourceGroup -Name $topicname
To simplify this article, let's set up sample event data to send to the custom topic. Typically, an application or Azure service would send the event data. The following example uses Hashtable to construct the event's data htbody
and then coverts it to well-formed JSON payload object $body
:
$eventID = Get-Random 99999
#Date format should be SortableDateTimePattern (ISO 8601)
$eventDate = Get-Date -Format s
#Construct body using Hashtable
$htbody = @{
id= $eventID
eventType="recordInserted"
subject="myapp/vehicles/motorcycles"
eventTime= $eventDate
data= @{
make="Ducati"
model="Monster"
}
dataVersion="1.0"
}
#Use ConvertTo-Json to convert event body from Hashtable to JSON Object
#Append square brackets to the converted JSON payload since they are expected in the event's JSON payload syntax
$body = "["+(ConvertTo-Json $htbody)+"]"
If you view $body
, you see the full event. The data
element of the JSON is the payload of your event. Any well-formed JSON can go in this field. You can also use the subject field for advanced routing and filtering.
Now, send the event to your topic.
Invoke-WebRequest -Uri $endpoint -Method POST -Body $body -Headers @{"aeg-sas-key" = $keys.Key1}
You've triggered the event, and Event Grid sent the message to the endpoint you configured when subscribing. View your web app to see the event you just sent.
[{
"id": "1807",
"eventType": "recordInserted",
"subject": "myapp/vehicles/motorcycles",
"eventTime": "2018-01-25T15:58:13",
"data": {
"make": "Ducati",
"model": "Monster"
},
"dataVersion": "1.0",
"metadataVersion": "1",
"topic": "/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.EventGrid/topics/{topic}"
}]
If you plan to continue working with this event or the event viewer app, don't clean up the resources created in this article. Otherwise, use the following command to delete the resources you created in this article.
Remove-AzResourceGroup -Name gridResourceGroup
Now that you know how to create topics and event subscriptions, learn more about what Event Grid can help you do:
- About Event Grid
- Route Blob storage events to a custom web endpoint
- Monitor virtual machine changes with Azure Event Grid and Logic Apps
- Stream big data into a data warehouse
See the following samples to learn about publishing events to and consuming events from Event Grid using different programming languages.