Manage topics and publish events using event domains

  • Article

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.

Create an Event Domain

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

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>.chinanorth2-1.eventgrid.azure.cn/api/events",
  "id": "/subscriptions/<sub-id>/resourceGroups/<my-resource-group>/providers/Microsoft.EventGrid/domains/<my-domain-name>",
  "inputSchema": "EventGridSchema",
  "inputSchemaMapping": null,
  "location": "chinanorth2",
  "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 Azure 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.chinacloudsites.cn/api/updates

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

Button to deploy the Resource Manager template to Azure.

Permissions that are set for a topic are stored in Microsoft Entra ID and must be deleted explicitly. Deleting an event subscription doesn't revoke a users access to create event subscriptions if they've 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.

Note

For samples that use programming language SDKs to publish events to an Event Grid domain, use the following links:

Search lists of topics or subscriptions

To search and manage large number of topics or subscriptions, the Event Grid APIs support listing and pagination.

Using CLI

For example, the following command lists all the topics with name containing mytopic.

az eventgrid topic list --odata-query "contains(name, 'mytopic')"

For more information about this command, see az eventgrid topic list.

Next steps