Merge pull request #91848 from baanders/10-14-iothub-tutorials

IoT Hub Tutorial 1

Author: v-albemi

articles/iot-hub/media/tutorial-routing-view-message-routing-results/stream-analytics-job-query.png

@@ -26,18 +26,18 @@ If you want to view the finished script, download the [Azure IoT C# Samples](htt
 
 ## Use the Azure CLI to create your resources
 
+Copy and paste the script below into Cloud Shell and press Enter. It runs the script one line at a time. This first section of the script will create the base resources for this tutorial, including the storage account, IoT Hub, Service Bus Namespace, and Service Bus queue. As you go through the rest of the tutorial, copy each block of script and paste it into Cloud Shell to run it.
+
+> [!TIP]
+> A tip about debugging: this script uses the continuation symbol (the backslash `\`) to make the script more readable. If you have a problem running the script, make sure your Cloud Shell session is running `bash` and that there are no spaces after any of the backslashes.
+> 
+
 There are several resource names that must be globally unique, such as the IoT Hub name and the storage account name. To make this easier, those resource names are appended with a random alphanumeric value called *randomValue*. The randomValue is generated once at the top of the script and appended to the resource names as needed throughout the script. If you don't want it to be random, you can set it to an empty string or to a specific value. 
 
 > [!IMPORTANT]
 > The variables set in the initial script are also used by the routing script, so run all of the script in the same Cloud Shell session. If you open a new session to run the script for setting up the routing, several of the variables will be missing values.
 >
 
-Copy and paste the script below into Cloud Shell and press Enter. It runs the script one line at a time. This first section of the script will create the base resources for this tutorial, including the storage account, IoT Hub, Service Bus Namespace, and Service Bus queue. As you go through the rest of the tutorial, copy each block of script and paste it into Cloud Shell to run it.
-
-> [!TIP]
-> A tip about debugging: this script uses the continuation symbol (the backslash `\`) to make the script more readable. If you have a problem running the script, make sure there are no spaces after any of the backslashes.
-> 
-
 ```azurecli-interactive
 # This command retrieves the subscription id of the current Azure account. 
 # This field is used when setting up the routing queries.
@@ -151,7 +151,7 @@ To create a routing endpoint, use [az iot hub routing-endpoint create](/cli/azur
 
 First, set up the endpoint for the storage account, then set up the route. 
 
-These variables are set:
+These are the variables used by the script that must be set within your Cloud Shell session:
 
 **storageConnectionString**: This value is retrieved from the storage account set up in the previous script. It is used by the message routing to access the storage account.
 
@@ -171,7 +171,7 @@ These variables are set:
 
 **endpointName**: This field is the name identifying the endpoint. 
 
-**enabled**: This field defaults to `true`, indicating that the message route should be enabled after created.
+**enabled**: This field defaults to `true`, indicating that the message route should be enabled after being created.
 
 **condition**: This field is the query used to filter for the messages sent to this endpoint. The query condition for the messages being routed to storage is `level="storage"`.
 
@@ -253,7 +253,7 @@ sbqConnectionString=$(az servicebus queue authorization-rule keys list \
 echo "service bus queue connection string = " $sbqConnectionString
 ```
 
-Now set up the routing endpoint and the message route for the Service Bus queue. These variables are set:
+Now set up the routing endpoint and the message route for the Service Bus queue. These are the variables used by the script that must be set within your Cloud Shell session:
 
 **endpointName**: This field is the name identifying the endpoint. 
 

articles/iot-hub/tutorial-routing-config-message-routing-CLI.md

@@ -30,14 +30,14 @@ Start by creating the resources with PowerShell.
 
 ### Use PowerShell to create your base resources
 
+Copy and paste the script below into Cloud Shell and press Enter. It runs the script one line at a time. This first section of the script will create the base resources for this tutorial, including the storage account, IoT Hub, Service Bus Namespace, and Service Bus queue. As you go through the tutorial, copy each block of script and paste it into Cloud Shell to run it.
+
 There are several resource names that must be globally unique, such as the IoT Hub name and the storage account name. To make this easier, those resource names are appended with a random alphanumeric value called *randomValue*. The randomValue is generated once at the top of the script and appended to the resource names as needed throughout the script. If you don't want it to be random, you can set it to an empty string or to a specific value. 
 
 > [!IMPORTANT]
 > The variables set in the initial script are also used by the routing script, so run all of the script in the same Cloud Shell session. If you open a new session to run the script for setting up the routing, several of the variables will be missing values. 
 >
 
-Copy and paste the script below into Cloud Shell and press Enter. It runs the script one line at a time. This first section of the script will create the base resources for this tutorial, including the storage account, IoT Hub, Service Bus Namespace, and Service Bus queue. As you go through the tutorial, copy each block of script and paste it into Cloud Shell to run it.
-
 ```azurepowershell-interactive
 # This command retrieves the subscription id of the current Azure account.
 # This field is used when setting up the routing queries.
@@ -136,7 +136,7 @@ First, set up the endpoint for the storage account, then create the message rout
 
 [!INCLUDE [iot-hub-include-blob-storage-format](../../includes/iot-hub-include-blob-storage-format.md)]
 
-These variables are set:
+These are the variables used by the script that must be set within your Cloud Shell session:
 
 **resourceGroup**: There are two occurrences of this field -- set both of them to your resource group.
 
@@ -158,7 +158,7 @@ These variables are set:
 
 **condition**: This field is the query used to filter for the messages sent to this endpoint. The query condition for the messages being routed to storage is `level="storage"`.
 
-**enabled**: This field defaults to `true`, indicating that the message route should be enabled after created.
+**enabled**: This field defaults to `true`, indicating that the message route should be enabled after being created.
 
 Copy this script and paste it into your Cloud Shell window.
 
@@ -228,7 +228,7 @@ $sbqkey = Get-AzServiceBusKey `
     -Name "sbauthrule"
 ```
 
-Now set up the routing endpoint and the message route for the Service Bus queue. These variables are set:
+Now set up the routing endpoint and the message route for the Service Bus queue. These are the variables used by the script that must be set within your Cloud Shell session:
 
 **endpointName**: This field is the name identifying the endpoint. 
 

articles/iot-hub/tutorial-routing-config-message-routing-PowerShell.md

@@ -367,7 +367,7 @@ The files are uploaded to the share used by your Cloud Shell instance.
 
 Run the script to perform the deployment. The last line of this script retrieves the variable that was set up to be returned -- the Service Bus queue connection string.
 
-These variables are set in this script.
+The script sets and uses these variables:
 
 **$RGName** is the resource group name to which to deploy the template. This field is created before deploying the template.
 

articles/iot-hub/tutorial-routing-config-message-routing-RM-template.md

@@ -19,9 +19,9 @@ ms.custom: mvc
 
 ## Rules for routing the messages
 
-These are the rules for the message routing; these were set up in part 1 of this tutorial, and you see them work in this second part.
+These are the rules for the message routing; these were set up in Part 1 of this tutorial, and you see them work in this second part.
 
-|value |Result|
+|Value |Result|
 |------|------|
 |level="storage" |Write to Azure Storage.|
 |level="critical" |Write to a Service Bus queue. A Logic App retrieves the message from the queue and uses Office 365 to e-mail the message.|
@@ -47,9 +47,11 @@ The Service Bus queue is to be used for receiving messages designated as critica
 
    ![The Create Logic App screen](./media/tutorial-routing-view-message-routing-results/create-logic-app.png)
 
-   Select **Create**.
+   Select **Create**. It may take a few minutes for the app to deploy.
 
-2. Now go to the Logic App. The easiest way to get to the Logic App is to select **Resource groups**, select your resource group (this tutorial uses **ContosoResources**), then select the Logic App from the list of resources. The Logic Apps Designer page appears (you might have to scroll over to the right to see the full page). On the Logic Apps Designer page, scroll down until you see the tile that says **Blank Logic App +** and select it. The default tab is "For You". If this pane is blank, select **All** to see all of the connectors and triggers available.
+2. Now go to the Logic App. The easiest way to get to the Logic App is to select **Resource groups**, select your resource group (this tutorial uses **ContosoResources**), then select the Logic App from the list of resources. 
+
+    The Logic Apps Designer page appears (you might have to scroll over to the right to see the full page). On the Logic Apps Designer page, scroll down until you see the tile that says **Blank Logic App +** and select it. The default tab is "For You". If this pane is blank, select **All** to see all of the connectors and triggers available.
 
 3. Select **Service Bus** from the list of connectors.
 
@@ -71,7 +73,7 @@ The Service Bus queue is to be used for receiving messages designated as critica
 
    ![The queue options](./media/tutorial-routing-view-message-routing-results/logic-app-queue-options.png)
 
-7. Now set up the action to send an e-mail when a message is received in the queue. In the Logic Apps Designer, select **+ New step** to add a step, then select **All** to see all of the options available. In the **Choose an action** pane, find and select **Office 365 Outlook**. On the triggers screen, select **Send an e-mail / Office 365 Outlook**.  
+7. Now set up the action to send an e-mail when a message is received in the queue. In the Logic Apps Designer, select **+ New step** to add a step, then select **All** to see all of the options available. In the **Choose an action** pane, find and select **Office 365 Outlook**. On the Actions screen, select **Send an e-mail / Office 365 Outlook**.  
 
    ![The Office365 options](./media/tutorial-routing-view-message-routing-results/logic-app-select-outlook.png)
 
@@ -103,7 +105,9 @@ To see the data in a Power BI visualization, first set up a Stream Analytics job
 
    ![Create the stream analytics job](./media/tutorial-routing-view-message-routing-results/stream-analytics-create-job.png)
 
-3. Select **Create** to create the job. To get back to the job, select **Resource groups**. This tutorial uses **ContosoResources**. Select the resource group, then select the Stream Analytics job in the list of resources.
+3. Select **Create** to create the job. It may take a few minutes to deploy.
+
+    To get back to the job, select **Resource groups**. This tutorial uses **ContosoResources**. Select the resource group, then select the Stream Analytics job in the list of resources.
 
 ### Add an input to the Stream Analytics job
 
@@ -117,13 +121,13 @@ To see the data in a Power BI visualization, first set up a Stream Analytics job
 
    **Subscription**: Select the Azure subscription you're using for this tutorial.
 
-   **IoT Hub**: Select the IoT Hub. This tutorial uses **ContosoTestHub**.
+   **IoT Hub**: Select the IoT hub. This tutorial uses **ContosoTestHub**.
 
    **Endpoint**: Select **Messaging**. (If you select Operations Monitoring, you get the telemetry data about the IoT hub rather than the data you're sending through.) 
 
    **Shared access policy name**: Select **service**. The portal fills in the Shared Access Policy Key for you.
 
-   **Consumer group**: Select the consumer group set up in step 1 of this tutorial. This tutorial uses **contosoconsumers**.
+   **Consumer group**: Select the consumer group set up in Part 1 of this tutorial. This tutorial uses **contosoconsumers**.
 
    For the rest of the fields, accept the defaults. 
 
@@ -173,20 +177,20 @@ To set up the Power BI report, you need data, so you'll set up Power BI after cr
 
 ## Run simulated device app
 
-In the part 1 of this tutorial, you set up a device to simulate using an IoT device. In this section, you download the .NET console app that simulates that device sending device-to-cloud messages to an IoT hub, assuming you didn't already download the app and resources in part 1 of this tutorial.
+In Part 1 of this tutorial, you set up a device to simulate using an IoT device. In this section, you download the .NET console app that simulates that device sending device-to-cloud messages to an IoT hub (assuming you didn't already download the app and resources in Part 1).
 
 This application sends messages for each of the different message routing methods. There is also a folder in the download that contains the complete Azure Resource Manager template and parameters file, as well as the Azure CLI and PowerShell scripts.
 
-If you didn't download the files from the repository in step 1 of this tutorial, go ahead and download them now from [IoT Device Simulation](https://github.com/Azure-Samples/azure-iot-samples-csharp/archive/master.zip). Selecting this link downloads a repository with several applications in it; the solution you are looking for is iot-hub/Tutorials/Routing/IoT_SimulatedDevice.sln. 
+If you didn't download the files from the repository in Part 1 of this tutorial, go ahead and download them now from [IoT Device Simulation](https://github.com/Azure-Samples/azure-iot-samples-csharp/archive/master.zip). Selecting this link downloads a repository with several applications in it; the solution you are looking for is iot-hub/Tutorials/Routing/IoT_SimulatedDevice.sln. 
 
-Double-click on the solution file (IoT_SimulatedDevice.sln) to open the code in Visual Studio, then open Program.cs. Substitute `{iot hub hostname}` with the IoT hub host name. The format of the IoT hub host name is **{iot-hub-name}.azure-devices.net**. For this tutorial, the hub host name is **ContosoTestHub.azure-devices.net**. Next, substitute `{device key}` with the device key you saved earlier when setting up the simulated device. 
+Double-click on the solution file (IoT_SimulatedDevice.sln) to open the code in Visual Studio, then open Program.cs. Substitute `{your hub name}` with the IoT hub host name. The format of the IoT hub host name is **{iot-hub-name}.azure-devices.net**. For this tutorial, the hub host name is **ContosoTestHub.azure-devices.net**. Next, substitute `{your device key}` with the device key you saved earlier when setting up the simulated device. 
 
    ```csharp
-        static string myDeviceId = "contoso-test-device";
-        static string iotHubUri = "ContosoTestHub.azure-devices.net";
+        static string s_myDeviceId = "Contoso-Test-Device";
+        static string s_iotHubUri = "ContosoTestHub.azure-devices.net";
         // This is the primary key for the device. This is in the portal. 
         // Find your IoT hub in the portal > IoT devices > select your device > copy the key. 
-        static string deviceKey = "{your device key here}";
+        static string s_deviceKey = "{your device key}";
    ```
 
 ## Run and test
@@ -207,15 +211,17 @@ If everything is set up correctly, at this point you should see the following re
    * The Logic App retrieving the message from the Service Bus queue is working correctly.
    * The Logic App connector to Outlook is working correctly. 
 
-2. In the [Azure portal](https://portal.azure.com), select **Resource groups** and select your Resource Group. This tutorial uses **ContosoResources**. Select the storage account, select **Blobs**, then select the Container. This tutorial uses **contosoresults**. You should see a folder, and you can drill down through the directories until you see one or more files. Open one of those files; they contain the entries routed to the storage account. 
+2. In the [Azure portal](https://portal.azure.com), select **Resource groups** and select your Resource Group. This tutorial uses **ContosoResources**. 
+
+    Select the storage account, select **Containers**, then select the Container. This tutorial uses **contosoresults**. You should see a folder, and you can drill down through the directories until you see one or more files. Open one of those files; they contain the entries routed to the storage account. 
 
    ![The result files in storage](./media/tutorial-routing-view-message-routing-results/results-in-storage.png)
 
 This result means the following statement is true.
 
    * The routing to the storage account is working correctly.
 
-Now with the application still running, set up the Power BI visualization to see the messages coming through the default routing.
+Now, with the application still running, set up the Power BI visualization to see the messages coming through the default routing.
 
 ## Set up the Power BI visualizations
 
@@ -245,11 +251,11 @@ Now with the application still running, set up the Power BI visualization to see
 
    A line chart is created. The x-axis displays date and time in the UTC time zone. The y-axis displays temperature from the sensor.
 
-6. Create another line chart to show real-time humidity over time. To set up the second chart, follow the same steps above and place **EventEnqueuedUtcTime** on the x-axis and **humidity** on the y-axis.
+6. Create another line chart to show real-time humidity over time. To set up the second chart, follow the same process for the first chart, placing **EventEnqueuedUtcTime** on the x-axis (**Axis**) and **humidity** on the y-axis (**Values**).
 
    ![The final Power BI report with the two charts](./media/tutorial-routing-view-message-routing-results/power-bi-report.png)
 
-7. Select **Save** to save the report.
+7. Select **Save** to save the report, entering a name for the report if prompted.
 
 You should be able to see data on both charts. This result means the following statements are true:
 
@@ -261,7 +267,7 @@ You can refresh the charts to see the most recent data by selecting the Refresh
 
 ## Clean up resources 
 
-If you want to remove all of the resources you've created through both parts of this tutorial, delete the resource group. This action deletes all resources contained within the group. In this case, it removes the IoT hub, the Service Bus namespace and queue, the Logic App, the storage account, and the resource group itself. 
+If you want to remove all of the Azure resources you've created through both parts of this tutorial, delete the resource group. This action deletes all resources contained within the group. In this case, it removes the IoT hub, the Service Bus namespace and queue, the Logic App, the storage account, and the resource group itself. You can also remove the Power BI resources and clear the emails sent during the tutorial.
 
 ### Clean up resources in the Power BI visualization
 
@@ -283,6 +289,10 @@ To remove the resource group, use the [Remove-AzResourceGroup](https://docs.micr
 Remove-AzResourceGroup -Name $resourceGroup
 ```
 
+### Clean up test emails
+
+You may also want to delete the quantity of emails in your inbox that were generated through the Logic App while the device application was running.
+
 ## Next steps
 
 In this 2-part tutorial, you learned how to use message routing to route IoT Hub messages to different destinations by performing the following tasks.