Tutorial: Publish, subscribe to events locally

This article walks you through all the steps needed to publish and subscribe to events using Event Grid on IoT Edge.

Note

To learn about Azure Event Grid topics and subscriptions, see Event Grid Concepts.

Prerequisites

In order to complete this tutorial, you will need:

  • Azure subscription - Create a free account if you don't already have one.
  • Azure IoT Hub and IoT Edge device - Follow the steps in the quickstart for Linux or Windows devices if you don't already have one.

Deploy Event Grid IoT Edge module

There are several ways to deploy modules to an IoT Edge device and all of them work for Azure Event Grid on IoT Edge. This article describes the steps to deploy Event Grid on IoT Edge from the Azure portal.

Note

In this tutorial, you will deploy the Event Grid module without persistence. It means that any topics and subscriptions you create in this tutorial will be deleted when you redeploy the module. For more information on how to setup persistence, see the following articles: Persist state in Linux or Persist state in Windows. For production workloads, we recommend that you install the Event Grid module with persistence.

Select your IoT Edge device

  1. Sign in to the Azure portal
  2. Navigate to your IoT Hub.
  3. Select IoT Edge from the menu in the Automatic Device Management section.
  4. Click on the ID of the target device from the list of devices
  5. Select Set Modules. Keep the page open. You will continue with the steps in the next section.

Configure a deployment manifest

A deployment manifest is a JSON document that describes which modules to deploy, how data flows between the modules, and desired properties of the module twins. The Azure portal has a wizard that walks you through creating a deployment manifest, instead of building the JSON document manually. It has three steps: Add modules, Specify routes, and Review deployment.

Add modules

  1. In the Deployment Modules section, select Add

  2. From the types of modules in the drop-down list, select IoT Edge Module

  3. Provide the name, image, container create options of the container:

    • Name: eventgridmodule
    • Image URI: mcr.microsoft.com/azure-event-grid/iotedge:latest
    • Container Create Options:
        {
          "Env": [
            "inbound:clientAuth:clientCert:enabled=false",
            "outbound:webhook:httpsOnly=false"
          ],
          "HostConfig": {
            "PortBindings": {
              "4438/tcp": [
                {
                    "HostPort": "4438"
                }
              ]
            }
          }
        }
    
  4. Click Save

  5. Continue to the next section to add the Azure Functions module before deploying them together.

    Important

    In this tutorial, you will deploy the Event Grid module with client authentication disabled and allow HTTP subscribers. For production workloads, we recommend that you enable the client authentication and allow only HTTPs subscribers. For more information on how to configure Event Grid module securely, see Security and authentication.

    If you are using an Azure VM as an edge device, add an inbound port rule to allow inbound traffic on the port 4438. For instructions on adding the rule, see How to open ports to a VM.

Deploy Azure Function IoT Edge module

This section shows you how to deploy the Azure Functions IoT module, which would act as an Event Grid subscriber to which events can be delivered.

Important

In this section, you will deploy a sample Azure Function-based subscribing module. It can of course be any custom IoT Module that can listen for HTTP POST requests.

Add modules

  1. In the Deployment Modules section, select Add again.

  2. From the types of modules in the drop-down list, select IoT Edge Module

  3. Provide the name, image, and container create options of the container:

    • Name: subscriber

    • Image URI: mcr.microsoft.com/azure-event-grid/iotedge-samplesubscriber-azfunc:latest

    • Container Create Options:

           {
             "HostConfig": {
               "PortBindings": {
                 "80/tcp": [
                   {
                     "HostPort": "8080"
                   }
                 ]
               }
             }
           }
      
  4. Click Save

  5. Click Next to continue to the routes section

Setup routes

Keep the default routes, and select Next to continue to the review section

Submit the deployment request

  1. The review section shows you the JSON deployment manifest that was created based on your selections in the previous section. Confirm that you see both the modules: eventgridmodule and subscriber listed in the JSON.

  2. Review your deployment information, then select Submit. After you submit the deployment, you return to the device page.

  3. In the Modules section, verify that both eventgrid and subscriber modules are listed. And, verify that the Specified in deployment and Reported by device columns are set to Yes.

    It may take a few moments for the module to be started on the device and then reported back to IoT Hub. Refresh the page to see an updated status.

Create a topic

As a publisher of an event, you need to create an event grid topic. In Azure Event Grid, a topic refers to an endpoint where publishers can send events to.

  1. Create topic.json with the following content. For details about the payload, see our API documentation.

        {
          "name": "sampleTopic1",
          "properties": {
            "inputschema": "eventGridSchema"
          }
        }
    
  2. Run the following command to create an event grid topic. Confirm that you see the HTTP status code is 200 OK.

    curl -k -H "Content-Type: application/json" -X PUT -g -d @topic.json https://<your-edge-device-public-ip-here>:4438/topics/sampleTopic1?api-version=2019-01-01-preview
    
  3. Run the following command to verify topic was created successfully. HTTP Status Code of 200 OK should be returned.

    curl -k -H "Content-Type: application/json" -X GET -g https://<your-edge-device-public-ip-here>:4438/topics/sampleTopic1?api-version=2019-01-01-preview
    

    Sample output:

         [
           {
             "id": "/iotHubs/eg-iot-edge-hub/devices/eg-edge-device/modules/eventgridmodule/topics/sampleTopic1",
             "name": "sampleTopic1",
             "type": "Microsoft.EventGrid/topics",
             "properties": {
               "endpoint": "https://<edge-vm-ip>:4438/topics/sampleTopic1/events?api-version=2019-01-01-preview",
               "inputSchema": "EventGridSchema"
             }
           }
         ]
    

Create an event subscription

Subscribers can register for events published to a topic. To receive any event, you'll need to create an Event Grid subscription for a topic of interest.

  1. Create subscription.json with the following content. For details about the payload, see our API documentation

        {
          "properties": {
            "destination": {
              "endpointType": "WebHook",
              "properties": {
                "endpointUrl": "http://subscriber:80/api/subscriber"
              }
            }
          }
        }
    

    Note

    The endpointType property specifies that the subscriber is a Webhook. The endpointUrl specifies the URL at which the subscriber is listening for events. This URL corresponds to the Azure Function sample you deployed earlier.

  2. Run the following command to create a subscription for the topic. Confirm that you see the HTTP status code is 200 OK.

    curl -k -H "Content-Type: application/json" -X PUT -g -d @subscription.json https://<your-edge-device-public-ip-here>:4438/topics/sampleTopic1/eventSubscriptions/sampleSubscription1?api-version=2019-01-01-preview
    
  3. Run the following command to verify subscription was created successfully. HTTP Status Code of 200 OK should be returned.

    curl -k -H "Content-Type: application/json" -X GET -g https://<your-edge-device-public-ip-here>:4438/topics/sampleTopic1/eventSubscriptions/sampleSubscription1?api-version=2019-01-01-preview
    

    Sample output:

         {
           "id": "/iotHubs/eg-iot-edge-hub/devices/eg-edge-device/modules/eventgridmodule/topics/sampleTopic1/eventSubscriptions/sampleSubscription1",
           "type": "Microsoft.EventGrid/eventSubscriptions",
           "name": "sampleSubscription1",
           "properties": {
             "Topic": "sampleTopic1",
             "destination": {
               "endpointType": "WebHook",
               "properties": {
                 "endpointUrl": "http://subscriber:80/api/subscriber"
               }
             }
           }
         }
    

Publish an event

  1. Create event.json with the following content. For details about the payload, see our API documentation.

        [
          {
            "id": "eventId-func-0",
            "eventType": "recordInserted",
            "subject": "myapp/vehicles/motorcycles",
            "eventTime": "2019-07-28T21:03:07+00:00",
            "dataVersion": "1.0",
            "data": {
              "make": "Ducati",
              "model": "Monster"
            }
          }
        ]
    
  2. Run the following command to publish an event.

    curl -k -H "Content-Type: application/json" -X POST -g -d @event.json https://<your-edge-device-public-ip-here>:4438/topics/sampleTopic1/events?api-version=2019-01-01-preview
    

Verify event delivery

  1. SSH or RDP into your IoT Edge VM.

  2. Check the subscriber logs:

    On Windows, run the following command:

    docker -H npipe:////./pipe/iotedge_moby_engine container logs subscriber
    

    On Linux, run the following command:

    sudo docker logs subscriber
    

    Sample output:

        Received event data [
            {
              "id": "eventId-func-0",
              "topic": "sampleTopic1",
              "subject": "myapp/vehicles/motorcycles",
              "eventType": "recordInserted",
              "eventTime": "2019-07-28T21:03:07+00:00",
              "dataVersion": "1.0",
              "metadataVersion": "1",
              "data": {
                "make": "Ducati",
                "model": "Monster"
              }
            }
          ]
    

Cleanup resources

  • Run the following command to delete the topic and all its subscriptions.

    curl -k -H "Content-Type: application/json" -X DELETE https://<your-edge-device-public-ip-here>:4438/topics/sampleTopic1?api-version=2019-01-01-preview
    
  • Delete the subscriber module from your IoT Edge device.

Next steps

In this tutorial, you created an event grid topic, subscription, and published events. Now that you know the basic steps, see the following articles: