Manage topics and publish events using event domains

This article shows how to:

  • Create an Event Grid domain
  • Subscribe to event grid topics
  • List keys
  • Publish events to a domain

To learn about event domains, see Understand event domains for managing Event Grid topics.

Important

Using this Azure feature from PowerShell requires the AzureRM module installed. This is an older module only available for Windows PowerShell 5.1 that no longer receives new features. The Az and AzureRM modules are not compatible when installed for the same versions of PowerShell. If you need both versions:

  1. Uninstall the Az module from a PowerShell 5.1 session.
  2. Install the AzureRM module from a PowerShell 5.1 session.
  3. Download and install PowerShell Core 6.x or later.
  4. Install the Az module in a PowerShell Core session.

Install preview feature

This feature is in preview. To use it, you must install a preview extension or module.

Install extension for Azure CLI

For Azure CLI, you need the Event Grid extension.

In CloudShell:

  • If you've installed the extension previously, update it az extension update -n eventgrid
  • If you haven't installed the extension previously, install it az extension add -n eventgrid

For a local installation:

  1. Install the Azure CLI. Make sure that you have the latest version, by checking with az --version.
  2. Uninstall previous versions of the extension az extension remove -n eventgrid
  3. Install the eventgrid extension with az extension add -n eventgrid

Install module for PowerShell

For PowerShell, you need the AzureRM.EventGrid module.

In CloudShell:

  • Install the module Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGallery

For a local installation:

  1. Open PowerShell console as administrator
  2. Install the module Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGallery

If the -AllowPrerelease parameter isn't available, use the following steps:

  1. Run Install-Module PowerShellGet -Force
  2. Run Update-Module PowerShellGet
  3. Close the PowerShell console
  4. Restart PowerShell as administrator
  5. Install the module Install-Module -Name AzureRM.EventGrid -AllowPrerelease -Force -Repository PSGallery

Create an Event Domain

To manage large sets of topics, create an event domain.

# If you haven't already installed the extension, do it now.
# This extension is required for preview features.
az extension add --name eventgrid

az eventgrid domain create \
  -g <my-resource-group> \
  --name <my-domain-name> \
  -l <location>

Successful creation returns the following values:

{
  "endpoint": "https://<my-domain-name>.westus2-1.eventgrid.azure.net/api/events",
  "id": "/subscriptions/<sub-id>/resourceGroups/<my-resource-group>/providers/Microsoft.EventGrid/domains/<my-domain-name>",
  "inputSchema": "EventGridSchema",
  "inputSchemaMapping": null,
  "location": "westus2",
  "name": "<my-domain-name>",
  "provisioningState": "Succeeded",
  "resourceGroup": "<my-resource-group>",
  "tags": null,
  "type": "Microsoft.EventGrid/domains"
}

Note the endpoint and id as they're required to manage the domain and publish events.

Manage access to topics

Managing access to topics is done via role assignment. Role assignment uses role-based access control to limit operations on Azure resources to authorized users at a certain scope.

Event Grid has two built-in roles, which you can use to assign particular users access on various topics within a domain. These roles are EventGrid EventSubscription Contributor (Preview), which allows for creation and deletion of subscriptions, and EventGrid EventSubscription Reader (Preview), which only allows for listing of event subscriptions.

The following Azure CLI command limits alice@contoso.com to creating and deleting event subscriptions only on topic demotopic1:

az role assignment create \
  --assignee alice@contoso.com \
  --role "EventGrid EventSubscription Contributor (Preview)" \
  --scope /subscriptions/<sub-id>/resourceGroups/<my-resource-group>/providers/Microsoft.EventGrid/domains/<my-domain-name>/topics/demotopic1

For more information about managing access for Event Grid operations, see Event Grid security and authentication.

Create topics and subscriptions

The Event Grid service automatically creates and manages the corresponding topic in a domain based on the call to create an event subscription for a domain topic. There's no separate step to create a topic in a domain. Similarly, when the last event subscription for a topic is deleted, the topic is deleted as well.

Subscribing to a topic in a domain is the same as subscribing to any other Azure resource. For the source resource ID, specify the event domain ID returned when creating the domain earlier. To specify the topic you want to subscribe to, add /topics/<my-topic> to the end of the source resource ID. To create a domain scope event subscription that receives all events in the domain, specify the event domain ID without specifying any topics.

Typically, the user you granted access to in the preceding section would create the subscription. To simplify this article, you create the subscription.

az eventgrid event-subscription create \
  --name <event-subscription> \
  --source-resource-id "/subscriptions/<sub-id>/resourceGroups/<my-resource-group>/providers/Microsoft.EventGrid/domains/<my-domain-name>/topics/demotopic1" \
  --endpoint https://contoso.azurewebsites.net/api/updates

If you need a test endpoint to subscribe your events to, you can always deploy a pre-built web app that displays the incoming events. You can send your events to your test website at https://<your-site-name>.azurewebsites.net/api/updates.

Permissions that are set for a topic are stored in Azure Active Directory and must be deleted explicitly. Deleting an event subscription won't revoke a users access to create event subscriptions if they have write access on a topic.

Publish events to an Event Grid Domain

Publishing events to a domain is the same as publishing to a custom topic. However, instead of publishing to the custom topic, you publish all events to the domain endpoint. In the JSON event data, you specify the topic you wish the events to go to. The following array of events would result in event with "id": "1111" to topic demotopic1 while event with "id": "2222" would be sent to topic demotopic2:

[{
  "topic": "demotopic1",
  "id": "1111",
  "eventType": "maintenanceRequested",
  "subject": "myapp/vehicles/diggers",
  "eventTime": "2018-10-30T21:03:07+00:00",
  "data": {
    "make": "Contoso",
    "model": "Small Digger"
  },
  "dataVersion": "1.0"
},
{
  "topic": "demotopic2",
  "id": "2222",
  "eventType": "maintenanceCompleted",
  "subject": "myapp/vehicles/tractors",
  "eventTime": "2018-10-30T21:04:12+00:00",
  "data": {
    "make": "Contoso",
    "model": "Big Tractor"
  },
  "dataVersion": "1.0"
}]

To get the domain endpoint with Azure CLI, use

az eventgrid domain show \
  -g <my-resource-group> \
  -n <my-domain>

To get the keys for a domain, use:

az eventgrid domain key list \
  -g <my-resource-group> \
  -n <my-domain>

And then use your favorite method of making an HTTP POST to publish your events to your Event Grid domain.

Next steps