Reacting to Events with an Event Grid System Topic

1. Start Locally

Firstly, we need to launch Locally which we can do from a terminal by running:

Once Locally has started, the Locally Dashboard will open automatically:

2. Create a Resource Group

Next we can create the Resource Group to hold everything:

There's two things to note here:

1. The Azure CLI supports Automatic Configuration, meaning that it can automatically be configured to work against Locally just by prefixing commands with locally run.
2. Locally intentionally uses a different set of locations to Azure as a safety precaution, so that you can be confident you're deploying against Locally rather than regular Azure. You can also configure Locally to use the Azure locations too, but you'll want to be extra sure that you're prefixing commands with locally run when you do.

3. Create the Storage Account

The Storage Account is both the source of the events and where we'll deliver them, so let's create it:

{
  "name": "sampleegsystopic1",
  "provisioningState": "Succeeded"
}

We need a container to upload into, and a queue for the events to arrive on:

4. Create the System Topic

A System Topic represents the events an Azure resource publishes. It points at its source by resource ID, so let's grab the Storage Account's:

Now we can create a System Topic for the Storage Account's events:

{
  "name": "sample-storage-events",
  "provisioningState": "Succeeded",
  "topicType": "Microsoft.Storage.StorageAccounts"
}

5. Subscribe a queue to blob events

The topic doesn't deliver anything until it has an event subscription. Let's send BlobCreated events to the blob-events queue:

{
  "endpointType": "StorageQueue",
  "includedEventTypes": [
    "Microsoft.Storage.BlobCreated"
  ],
  "name": "blob-created",
  "provisioningState": "Succeeded",
  "queueName": "blob-events"
}

Because of that filter, other blob events, such as deletes, won't reach the queue. We can list the topic's subscriptions:

Name          Destination    Queue        State
------------  -------------  -----------  ---------
blob-created  StorageQueue   blob-events  Succeeded

6. Upload a blob

The az storage data plane commands need the account's connection string. Putting it in AZURE_STORAGE_CONNECTION_STRING means we don't have to pass it to each one:

Now let's upload a small file:

7. See the event arrive

Event Grid writes each event to the queue as base64-encoded JSON. Let's peek at the message and decode it:

{
  "eventType": "Microsoft.Storage.BlobCreated",
  "subject": "/blobServices/default/containers/uploads/blobs/hello.txt",
  "data": {
    "api": "PutBlob",
    "blobType": "BlockBlob",
    "contentLength": 19
  }
}

Delivery happens in the background, so if the command prints nothing, give it a second and run it again. The subject tells a handler which blob was created, which is all it needs to go and process it.

8. Tidy up

Finally, we can tidy up. To remove the Resource Group and everything within it:

Doing this with other tooling

Whilst this guide used the Azure CLI, System Topics work the same way through any of the tooling that Locally supports - Microsoft.EventGrid/systemTopics and Microsoft.EventGrid/systemTopics/eventSubscriptions resources in HashiCorp Terraform or OpenTofu, Pulumi, Bicep or an ARM Template all provision against Locally in the same way.

On the receiving end, any application reading the queue with the Azure SDK for .NET, Go or Python gets the same events.

Next steps

To publish your own events rather than a service's, see Event Grid Topic. For more on working with the queue the events land on, see Storage Queues.

Should you encounter any issues, please take a look at the troubleshooting section.

Resource types this guide uses

These are the Azure resource types this guide creates in Locally:

• Microsoft.EventGrid/systemTopics
• Microsoft.EventGrid/systemTopics/eventSubscriptions
• Microsoft.Storage/storageAccounts
• Microsoft.Storage/storageAccounts/queueServices/queues