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.

Create an Event Domain

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

For Azure CLI, use:

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

For PowerShell, use:

New-AzureRmEventGridDomain `
  -ResourceGroupName <my-resource-group> `
  -Name <my-domain-name> `
  -Location <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

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

New-AzureRmRoleAssignment `
  -SignInName alice@contoso.com `
  -RoleDefinitionName "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.

For Azure CLI, use:

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

For PowerShell, use:

New-AzureRmEventGridSubscription `
  -ResourceId "/subscriptions/<sub-id>/resourceGroups/<my-resource-group>/providers/Microsoft.EventGrid/domains/<my-domain-name>/topics/demotopic1" `
  -EventSubscriptionName <event-subscription> `
  -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>

To get the domain endpoint with PowerShell, use

Get-AzureRmEventGridDomain `
  -ResourceGroupName <my-resource-group> `
  -Name <my-domain>

To get the keys for a domain, use:

Get-AzureRmEventGridDomainKey `
  -ResourceGroupName <my-resource-group> `
  -Name <my-domain>

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

Search lists of topics or subscriptions

In order to make searching and managing of large numbers of topics or subscriptions, Event Grid's APIs support listing and pagination.

Using CLI

To use it make sure you’re using the Azure CLI Event Grid extension version 0.4.1 or newer.

# 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 topic list \
    --odata-query "contains(name, 'my-test-filter')"

Next steps