Azure Service Bus to Event Grid integration overview

  • Article

Service Bus can emit events to Event Grid when there are messages in a queue or a subscription when no receivers are present. You can create Event Grid subscriptions to your Service Bus namespaces, listen to these events, and then react to the events by starting a receiver. With this feature, you can use Service Bus in reactive programming models. The key scenario of this feature is that Service Bus queues or subscriptions with a low volume of messages do not need to have a receiver that polls for messages continuously.

To enable the feature, you need the following items:

  • A Service Bus Premium namespace with at least one Service Bus queue or a Service Bus topic with at least one subscription.
  • Contributor access to the Service Bus namespace. Navigate to your Service Bus namespace in the Azure portal, and then select Access control (IAM), and select Role assignments tab. Verify that you have the contributor access to the namespace.
  • Additionally, you need an Event Grid subscription for the Service Bus namespace. This subscription receives a notification from Event Grid that there are messages to be picked up. Typical subscribers could be the Logic Apps feature of Azure App Service, Azure Functions, or a webhook contacting a web app. The subscriber then processes the messages.

19

Available event types

Service Bus emits the following event types:

Event type Description
Microsoft.ServiceBus.ActiveMessagesAvailableWithNoListeners Raised when a new active message arrives in a queue or subscription and there are no receivers listening.
Microsoft.ServiceBus.DeadletterMessagesAvailableWithNoListeners Raised when a new active messages arrives in a dead letter queue and there are no active listeners.
Microsoft.ServiceBus.ActiveMessagesAvailablePeriodicNotifications Raised every 30 seconds if there are active messages in a queue or subscription, even if there are active listeners on that specific queue or subscription. It's also raised when the active message count transitions from 0 to a positive value for the queue or subscription.
Microsoft.ServiceBus.DeadletterMessagesAvailablePeriodicNotifications Raised every 30 seconds if there are messages in the dead-letter entity of a queue or subscription, even if there are active listeners on the dead-letter entity of that specific queue or subscription. It's also raised when the dead-letter message count transitions from 0 to a positive value for the dead-letter entity of the queue or subscription.

Example event

Active messages available with no listeners

This event is generated if you have active messages in a queue or a subscription and there are no receivers listening.

[{
  "topic": "/subscriptions/{subscription-id}/resourcegroups/{your-rg}/providers/Microsoft.ServiceBus/namespaces/{your-service-bus-namespace}",
  "subject": "topics/{your-service-bus-topic}/subscriptions/{your-service-bus-subscription}",
  "eventType": "Microsoft.ServiceBus.ActiveMessagesAvailableWithNoListeners",
  "eventTime": "2018-02-14T05:12:53.4133526Z",
  "id": "dede87b0-3656-419c-acaf-70c95ddc60f5",
  "data": {
    "namespaceName": "YOUR SERVICE BUS NAMESPACE WILL SHOW HERE",
    "requestUri": "https://{your-service-bus-namespace}.servicebus.chinacloudapi.cn/{your-topic}/subscriptions/{your-service-bus-subscription}/messages/head",
    "entityType": "subscriber",
    "queueName": "QUEUE NAME IF QUEUE",
    "topicName": "TOPIC NAME IF TOPIC",
    "subscriptionName": "SUBSCRIPTION NAME"
  },
  "dataVersion": "1",
  "metadataVersion": "1"
}]

Dead-letter messages available with no listeners

The schema for a dead letter queue event is similar. You get at least one event per dead-letter queue that has messages and no active receivers.

[{
  "topic": "/subscriptions/{subscription-id}/resourcegroups/{your-rg}/providers/Microsoft.ServiceBus/namespaces/{your-service-bus-namespace}",
  "subject": "topics/{your-service-bus-topic}/subscriptions/{your-service-bus-subscription}",
  "eventType": "Microsoft.ServiceBus.DeadletterMessagesAvailableWithNoListeners",
  "eventTime": "2018-02-14T05:12:53.4133526Z",
  "id": "dede87b0-3656-419c-acaf-70c95ddc60f5",
  "data": {
    "namespaceName": "YOUR SERVICE BUS NAMESPACE WILL SHOW HERE",
    "requestUri": "https://{your-service-bus-namespace}.servicebus.chinacloudapi.cn/{your-topic}/subscriptions/{your-service-bus-subscription}/$deadletterqueue/messages/head",
    "entityType": "subscriber",
    "queueName": "QUEUE NAME IF QUEUE",
    "topicName": "TOPIC NAME IF TOPIC",
    "subscriptionName": "SUBSCRIPTION NAME"
  },
  "dataVersion": "1",
  "metadataVersion": "1"
}]

Active messages available periodic notifications

This event is generated periodically if you have active messages in the specific queue or subscription, even if there are active listeners for that specific queue or subscription.

[{
  "topic": "/subscriptions/<subscription id>/resourcegroups/DemoGroup/providers/Microsoft.ServiceBus/namespaces/<YOUR SERVICE BUS NAMESPACE WILL SHOW HERE>",
  "subject": "topics/<service bus topic>/subscriptions/<service bus subscription>",
  "eventType": "Microsoft.ServiceBus.ActiveMessagesAvailablePeriodicNotifications",
  "eventTime": "2018-02-14T05:12:53.4133526Z",
  "id": "dede87b0-3656-419c-acaf-70c95ddc60f5",
  "data": {
    "namespaceName": "YOUR SERVICE BUS NAMESPACE WILL SHOW HERE",
    "requestUri": "https://YOUR-SERVICE-BUS-NAMESPACE-WILL-SHOW-HERE.servicebus.chinacloudapi.cn/TOPIC-NAME/subscriptions/SUBSCRIPTIONNAME/$deadletterqueue/messages/head",
    "entityType": "subscriber",
    "queueName": "QUEUE NAME IF QUEUE",
    "topicName": "TOPIC NAME IF TOPIC",
    "subscriptionName": "SUBSCRIPTION NAME"
  },
  "dataVersion": "1",
  "metadataVersion": "1"
}]

Dead-letter messages available periodic notifications

This event is generated periodically if you have deadletter messages on the specific queue or subscription, even if there are active listeners on the deadletter entity of that specific queue or subscription.

[{
  "topic": "/subscriptions/<subscription id>/resourcegroups/DemoGroup/providers/Microsoft.ServiceBus/namespaces/<YOUR SERVICE BUS NAMESPACE WILL SHOW HERE>",
  "subject": "topics/<service bus topic>/subscriptions/<service bus subscription>",
  "eventType": "Microsoft.ServiceBus.DeadletterMessagesAvailablePeriodicNotifications",
  "eventTime": "2018-02-14T05:12:53.4133526Z",
  "id": "dede87b0-3656-419c-acaf-70c95ddc60f5",
  "data": {
    "namespaceName": "YOUR SERVICE BUS NAMESPACE WILL SHOW HERE",
    "requestUri": "https://YOUR-SERVICE-BUS-NAMESPACE-WILL-SHOW-HERE.servicebus.chinacloudapi.cn/TOPIC-NAME/subscriptions/SUBSCRIPTIONNAME/$deadletterqueue/messages/head",
    "entityType": "subscriber",
    "queueName": "QUEUE NAME IF QUEUE",
    "topicName": "TOPIC NAME IF TOPIC",
    "subscriptionName": "SUBSCRIPTION NAME"
  },
  "dataVersion": "1",
  "metadataVersion": "1"
}]

Event properties

An event has the following top-level data:

Property Type Description
topic string Full resource path to the event source. This field isn't writeable. Event Grid provides this value.
subject string Publisher-defined path to the event subject.
eventType string One of the registered event types for this event source.
eventTime string The time the event is generated based on the provider's UTC time.
id string Unique identifier for the event.
data object Blob storage event data.
dataVersion string The schema version of the data object. The publisher defines the schema version.
metadataVersion string The schema version of the event metadata. Event Grid defines the schema of the top-level properties. Event Grid provides this value.

The data object has the following properties:

Property Type Description
namespaceName string The Service Bus namespace the resource exists in.
requestUri string The URI to the specific queue or subscription emitting the event.
entityType string The type of Service Bus entity emitting events (queue or subscription).
queueName string The queue with active messages if subscribing to a queue. Value null if using topics / subscriptions.
topicName string The topic the Service Bus subscription with active messages belongs to. Value null if using a queue.
subscriptionName string The Service Bus subscription with active messages. Value null if using a queue.

Event Grid subscriptions for Service Bus namespaces

You can create Event Grid subscriptions for Service Bus namespaces in three different ways:

  • Azure portal. See the following tutorials to learn how to use Azure portal to create Event Grid subscriptions for Service Bus events with Azure Logic Apps and Azure Functions as handlers.

  • Azure CLI. The following CLI example shows how to create an Azure Functions subscription for a system topic created by a Service Bus namespace.

    namespaceid=$(az resource show --namespace Microsoft.ServiceBus --resource-type namespaces --name "<service bus namespace>" --resource-group "<resource group that contains the service bus namespace>" --query id --output tsv

az eventgrid event-subscription create --resource-id $namespaceid --name "<YOUR EVENT GRID SUBSCRIPTION NAME>" --endpoint "<your_endpoint_url>" --subject-ends-with "<YOUR SERVICE BUS SUBSCRIPTION NAME>"
  • PowerShell. Here's an example: 
    $namespaceID = (Get-AzServiceBusNamespace -ResourceGroupName "<YOUR RESOURCE GROUP NAME>" -NamespaceName "<YOUR NAMESPACE NAME>").Id

New-AzEVentGridSubscription -EventSubscriptionName "<YOUR EVENT GRID SUBSCRIPTION NAME>" -ResourceId $namespaceID -Endpoint "<YOUR ENDPOINT URL>" -SubjectEndsWith "<YOUR SERVICE BUS SUBSCRIPTION NAME>"

How many events are emitted, and how often?

If you have multiple queues and topics or subscriptions in the namespace, you get at least one event per queue and one per subscription. The events are emitted immediately if there are no messages in the Service Bus entity and a new message arrives. Or the events are emitted every two minutes unless Service Bus detects an active receiver. Message browsing doesn't interrupt the events.

By default, Service Bus emits events for all entities in the namespace. If you want to get events for specific entities only, see the next section.

Use filters to limit where you get events from

If you want to get events only from, for example, one queue or one subscription within your namespace, you can use the Begins with or Ends with filters that are provided by Event Grid. In some interfaces, the filters are called Pre and Suffix filters. If you want to get events for multiple, but not all, queues and subscriptions, you can create multiple Event Grid subscriptions and provide a filter for each.

Next steps

See the following tutorials: