Previous

Next

Exercise - Integrate Azure Cosmos DB with the IoT data pipeline

Completed

This exercise provides an overview of setting up the collection, processing, and storage of IoT telemetry generated, by using an Azure IoT Central application.

In this exercise, you:

• Create an Azure IoT Central application.
• Create an Azure function that logs an HTTP request payload.
• Configure and validate IoT telemetry rules of an Azure IoT Central application.

Prerequisites

To perform this exercise, you need:

• A Microsoft account or a Microsoft Entra account with the Global Administrator role in the Microsoft Entra tenant. The tenant must be associated with the Azure subscription and with the Owner or Contributor role in the Azure subscription.
• To complete the exercise unit Set up Azure Cosmos DB.
• An active Azure subscription. If you don't have an Azure subscription, create a free account before you begin.

Create an Azure IoT Central application

1. Navigate to the Create IoT Central Application page in the Azure portal. If prompted, sign in with your Azure account.

2. Enter the following information:

   Field	Description
   Subscription	The Azure subscription you want to use.
   Resource group	The resource group you want to use. You can create a new resource group or use an existing one.
   Resource name	A valid Azure resource name such as adatum-iot-custom-application.
   Application URL	A URL subdomain for your application such as adatum-iot-custom-application. The URL for an IoT Central application looks like https://adatum-iot-custom-application.azureiotcentral.com.
   Template	In-store Analytics - Condition Monitoring
   Region	The Azure region you want to use.
   Pricing plan	Select one of the standard pricing plans. To learn about pricing, see Azure IoT Central pricing.

3. Select Review + create. Then select Create.

When the app is ready, you can navigate to it from the Azure portal:

Tip

To list all the IoT Central applications you have access to, navigate to IoT Central Applications.

In a few minutes or less, the Dashboard page is displayed. Review the telemetry and analytics of the sample Azure IoT Central application:

1. On the Dashboard page of the IoT Central Application portal, in the vertical menu, select Devices.

2. In the Thermostat section, select Thermostat-Zone1.

3. On the Thermostat-Zone1 pane, review the content of the Dashboard tab.

   

4. Select the Raw data tab, and review the content.

   

Create an Azure function that logs an HTTP request payload

In this task, you're creating an Azure Function app that implements the HTTP webhook functionality. Apply this functionality to forward the telemetry data from the Azure IoT Central application by creating an application rule.

1. Start a web browser, navigate to the Azure portal, and sign in to the Azure subscription you're using for this module.

2. Use the Search resources, services, and docs text box to search for Function App.

3. On the Function App pane, select + Create.

4. On the Basics tab, configure the following settings, and then select Review + create.

   Setting	Configuration
   Subscription	Select the name of the Azure subscription you're using for this module.
   Resource Group	Create a new resource group named function-app-RG.
   Function App name	Enter a unique name that consists of lower-case letters, digits, or dashes, and starts with a letter.
   Publish	Select Code.
   Runtime stack	Select .NET.
   Version	Select Version 6 (LTS), in-process model.
   Region	Select the Azure region closest to the location of your lab environment, preferably matching the location you chose for the Azure IoT Central deployment.
   Operating system	Windows
   Plan type	Consumption (serverless)

   

5. Select Create.

   Note

   Wait for the Azure Function app provisioning to complete. This might take about two minutes.

6. When the Azure Function app deployment is complete, select Go to resource.

7. On the Azure Function app pane, under Create in Azure portal, select Create function.

8. On the Add function pane, specify the following settings, and then select Create.

   Setting	Configuration
   Development environment	Develop in portal
   Template	HTTP trigger
   New Function	HttpTrigger1
   Authorization level	Function

   

9. On the HttpTrigger1 pane, select Integration from the menu.

   

10. In the rectangle labeled Outputs, select + Add output.

11. Configure the following settings, and then select Add:

    Setting	Configuration
    Binding type	Select Azure Cosmos DB.
    Document parameter name	Replace the default value with outDoc.
    Database name	Enter the name of the database you created in the previous exercise, iotdb.
    Collection Name	Enter iotcollection.
    If true, creates the Cosmos DB database	Select Yes.
    Cosmos DB account connection	Select New. In the New Cosmos DB connection popup window, ensure that the Azure Cosmos DB Account option is selected. In the Database Account drop-down list, select the entry representing the Cosmos DB account you created in the previous exercise, and then select OK.
    Partition key (optional)	Enter /pk/timestamp/deviceid.

    

    Note

    When choosing an optimal partition key, it's important to consider the usage patterns and the 20 GB logical partition size limit. You could, for example, create a synthetic partition key consisting of a combination of deviceId and date.

12. Select Code + Test.

13. Replace the existing code with the following content, and then select Save.

    #r "Newtonsoft.Json"
    
    using Microsoft.Azure.WebJobs.Host;
    using Newtonsoft.Json;
    using Newtonsoft.Json.Linq;
    using Microsoft.Extensions.Logging;
    using Microsoft.AspNetCore.Mvc;
    
    public static void Run(HttpRequest req, out object outDoc, ILogger log)
    {
      log.LogInformation($"C# Queue trigger function processed: {req.Body}");
    
      string requestBody = new StreamReader(req.Body).ReadToEnd();
      dynamic iotDataJson = JObject.Parse(requestBody);
      dynamic iotData = JsonConvert.DeserializeObject<dynamic>(iotDataJson.ToString());
    
      log.LogInformation($"{iotData}");
    
      outDoc = new {
        pk = iotData.device.id + "-" + iotData.timestamp.ToString("yyyyMMdd"),
        timestamp = iotData.timestamp,
        deviceId = iotData.device.id,
        temperature = iotData.device.telemetry.Thermostat_1o.temp.value
      };
    }
    

    

    Note

    The function logs the JSON-based payload of the HTTP request and constructs individual JSON elements to be stored in an individual document of the target Cosmos DB collection corresponding to the function output you configured. You could use the pk element, which consists of the concatenated deviceId property and date of the collected telemetry data point, as the partition key.

14. Select Get function URL for the function key and record its value.

    

Configure and validate IoT telemetry rules of an Azure IoT Central application

1. Switch back to the web browser window displaying the Devices page of Azure IoT Central application you created previously in this exercise.

2. In the vertical menu of the IoT Central Application portal, select Rules.

3. Select + New, and configure the following settings:

   Setting	Configuration
   Rule name	Enter Adatum IoT telemetry rule.
   Device template	Select Thermostat.
   Time aggregation	Ensure that the settings are turned Off.
   Telemetry	Select Temperature.
   Operator	Select is greater than.
   Enter a value	Enter 0.
   Action	Select + Webhook.
   Display name	Enter Azure function webhook.
   Callback URL	Paste the value of the Azure function URL you recorded in the previous task of this exercise.

   

   

   Note

   The value of the temperature telemetry is intentionally artificially low to invoke the webhook functionality and trigger the function. In real-life scenarios, you'd adjust it to correspond to the condition that warrants the data collection that you intend to store in the target Cosmos DB collection.

4. Select Done, and then select Save.

5. Switch back to the web browser window displaying the HttpTrigger1 | Code + Test pane in the Azure portal.

6. Select Monitor, and then select the Logs tab.

7. Verify that the logs pane displays the messages generated in response to the HTTP trigger originating from the Azure IoT Central application webhook you configured previously in this task.

8. Switch to the web browser window displaying the Data Explorer pane of the Cosmos DB account you provisioned in the previous exercise.

9. In the NOSQL API section, select the circular arrow Refresh button, expand the iotdb node and the iotcollection within it. Select the Items node, and then select the first document in the list of items.

10. Verify that the details pane of the Items tab in the Data Explorer window displays the telemetry data generated by devices registered with the Azure Central IoT application and processed by the Azure function, including pk, timestamp, deviceId, and temperature.

    

Results

Congratulations! You completed the second exercise of this module. In this exercise, you created an Azure IoT Central application.

Continue