Merge pull request #191361 from kgremban/mar9-hubquickstart2

v-regandowner · web-flow · commit 55823c99c4fe · 2022-03-11T16:30:54.000-05:00
Review hub quickstarts -- direct method node, java, python
diff --git a/includes/iot-hub-include-create-hub-quickstart.md b/includes/iot-hub-include-create-hub-quickstart.md
@@ -0,0 +1,45 @@
+---
+title: include file
+description: include file
+author: kgremban
+ms.author: kgremban
+ms.service: iot-hub
+ms.topic: include
+ms.date: 03/10/2022
+---
+
+## Create an IoT hub
+
+In this section, you use Azure CLI to create an IoT hub and a resource group.  An Azure resource group is a logical container into which Azure resources are deployed and managed. An IoT hub acts as a central message hub for bi-directional communication between your IoT application and the devices.
+
+If you already have an IoT hub in your Azure subscription, you can skip this section.
+
+To create an IoT hub and a resource group:
+
+1. Launch your CLI app. To run the CLI commands in the rest of this quickstart, copy the command syntax, paste it into your CLI app, edit variable values, and press `Enter`.
+
+    - If you're using Cloud Shell, select the **Try It** button on the CLI commands to launch Cloud Shell in a split browser window. Or you can open the [Cloud Shell](https://shell.azure.com/bash) in a separate browser tab.
+    - If you're using Azure CLI locally, start your CLI console app and sign in to Azure CLI.
+
+1. Run [az extension add](/cli/azure/extension#az_extension_add) to install or upgrade the *azure-iot* extension to the current version.
+
+    ```azurecli-interactive
+    az extension add --upgrade --name azure-iot
+    ```
+
+1. In your CLI app, run the [az group create](/cli/azure/group#az_group_create) command to create a resource group. The following command creates a resource group named *MyResourceGroup* in the *eastus* location.
+
+    >[!NOTE]
+    > Optionally, you can set a different location. To see available locations, run `az account list-locations`.
+
+    ```azurecli-interactive
+    az group create --name MyResourceGroup --location eastus
+    ```
+
+1. Run the [az iot hub create](/cli/azure/iot/hub#az_iot_hub_create) command to create an IoT hub. It might take a few minutes to create an IoT hub.
+
+    *YourIotHubName*. Replace this placeholder and the surrounding braces in the following command, using the name you chose for your IoT hub. An IoT hub name must be globally unique in Azure. Use your IoT hub name in the rest of this quickstart wherever you see the placeholder.
+
+    ```azurecli-interactive
+    az iot hub create --resource-group MyResourceGroup --name {YourIoTHubName}
+    ```
diff --git a/includes/quickstart-control-device-java.md b/includes/quickstart-control-device-java.md
@@ -1,15 +1,18 @@
 ---
-author: phlmea
-ms.author: philmea
+author: kgremban
+ms.author: kgremban
 ms.service: iot-hub
 services: iot-hub
 ms.devlang: java
 ms.topic: include
 ms.custom: [mvc, seo-java-august2019, seo-java-september2019, mqtt, devx-track-java, devx-track-azurecli]
-ms.date: 06/21/2019
+ms.date: 03/10/2022
 ---
 
-This quickstart uses two Java applications: a simulated device application that responds to direct methods called from a back-end application and a service application that calls the direct method on the simulated device.
+This quickstart uses two Java applications: 
+
+* A simulated device application that responds to direct methods called from a back-end application.
+* A service application that calls the direct method on the simulated device.
 
 ## Prerequisites
 
@@ -31,27 +34,23 @@ This quickstart uses two Java applications: a simulated device application that
     mvn --version
     ```
 
-* [A sample Java project](https://github.com/Azure-Samples/azure-iot-samples-java/archive/master.zip).
+* Clone or download the [Azure IoT Java samples](https://github.com/Azure-Samples/azure-iot-samples-java/) from GitHub.
 
-* Port 8883 open in your firewall. The device sample in this quickstart uses MQTT protocol, which communicates over port 8883. This port may be blocked in some corporate and educational network environments. For more information and ways to work around this issue, see [Connecting to IoT Hub (MQTT)](../articles/iot-hub/iot-hub-mqtt-support.md#connecting-to-iot-hub).
+* Make sure that port 8883 open in your firewall. The device sample in this quickstart uses MQTT protocol, which communicates over port 8883. This port may be blocked in some corporate and educational network environments. For more information and ways to work around this issue, see [Connecting to IoT Hub (MQTT)](../articles/iot-hub/iot-hub-mqtt-support.md#connecting-to-iot-hub).
 
 [!INCLUDE [azure-cli-prepare-your-environment.md](azure-cli-prepare-your-environment-no-header.md)]
 
 [!INCLUDE [iot-hub-cli-version-info](iot-hub-cli-version-info.md)]
 
-## Create an IoT hub
-
-If you completed the previous [Quickstart: Send telemetry from a device to an IoT hub](../articles/iot-develop/quickstart-send-telemetry-iot-hub.md?pivots=programming-language-java), you can skip this step.
-
-[!INCLUDE [iot-hub-include-create-hub](iot-hub-include-create-hub.md)]
+[!INCLUDE [iot-hub-include-create-hub](iot-hub-include-create-hub-quickstart.md)]
 
 ## Register a device
 
-If you completed the previous [Quickstart: Send telemetry from a device to an IoT hub](../articles/iot-develop/quickstart-send-telemetry-iot-hub.md?pivots=programming-language-java), you can skip this step.
+A device must be registered with your IoT hub before it can connect. In this quickstart, you use the Azure Cloud Shell to create a device identity.
 
-A device must be registered with your IoT hub before it can connect. In this quickstart, you use the Azure Cloud Shell to register a simulated device.
+If you already have a device registered in your IoT hub, you can skip this section.
 
-1. Run the following command in Azure Cloud Shell to create the device identity.
+1. Run the [az iot hub device-identity create](/cli/azure/iot/hub/device-identity#az_iot_hub_device_identity_create) command in Azure Cloud Shell to create the device identity.
 
    **YourIoTHubName**: Replace this placeholder below with the name you chose for your IoT hub.
 
@@ -62,7 +61,7 @@ A device must be registered with your IoT hub before it can connect. In this qui
       --hub-name {YourIoTHubName} --device-id MyJavaDevice
     ```
 
-2. Run the following commands in Azure Cloud Shell to get the _device connection string_ for the device you just registered:
+2. Run the [az iot hub device-identity connection-string show](/cli/azure/iot/hub/device-identity/connection-string#az_iot_hub_device_identity_connection_string_show) command in Azure Cloud Shell to get the _device connection string_ for the device you just registered:
 
    **YourIoTHubName**: Replace this placeholder below with the name you choose for your IoT hub.
 
@@ -95,7 +94,7 @@ Make a note of the service connection string, which looks like:
 
 You use this value later in the quickstart. This service connection string is different from the device connection string you noted in the previous step.
 
-## Listen for direct method calls
+## Simulate a device
 
 The simulated device application connects to a device-specific endpoint on your IoT hub, sends simulated telemetry, and listens for direct method calls from your hub. In this quickstart, the direct method call from the hub tells the device to change the interval at which it sends telemetry. The simulated device sends an acknowledgment back to your hub after it executes the direct method.
 
diff --git a/includes/quickstart-control-device-node.md b/includes/quickstart-control-device-node.md
@@ -1,15 +1,18 @@
 ---
-author: philmea
-ms.author: philmea
+author: kgremban
+ms.author: kgremban
 ms.service: iot-hub
 services: iot-hub
 ms.devlang: nodejs
 ms.topic: include
 ms.custom: [mvc, seo-javascript-september2019, seo-javascript-october2019, mqtt, 'Role: Cloud Development', devx-track-js, devx-track-azurecli]
-ms.date: 06/21/2019
+ms.date: 03/09/2022
 ---
 
-This quickstart uses two Node.js applications: a simulated device application that responds to direct methods called from a back-end application and a back-end application that calls the direct methods on the simulated device.
+This quickstart uses two Node.js applications: 
+
+* A simulated device application that responds to direct methods called from a back-end application. To receive the direct method calls, this application connects to a device-specific endpoint on your IoT hub.
+* A back-end application that calls the direct methods on the simulated device. To call a direct method on a device, this application connects to a service-specific endpoint on your IoT hub.
 
 ## Prerequisites
 
@@ -23,27 +26,23 @@ This quickstart uses two Node.js applications: a simulated device application th
     node --version
     ```
 
-* [A sample Node.js project](https://github.com/Azure-Samples/azure-iot-samples-node/archive/master.zip).
+* Clone or download the [Azure IoT Node.js samples](https://github.com/Azure-Samples/azure-iot-samples-node/) from GitHub.
 
-* Port 8883 open in your firewall. The device sample in this quickstart uses MQTT protocol, which communicates over port 8883. This port may be blocked in some corporate and educational network environments. For more information and ways to work around this issue, see [Connecting to IoT Hub (MQTT)](../articles/iot-hub/iot-hub-mqtt-support.md#connecting-to-iot-hub).
+* Make sure that port 8883 is open in your firewall. The device sample in this quickstart uses MQTT protocol, which communicates over port 8883. This port may be blocked in some corporate and educational network environments. For more information and ways to work around this issue, see [Connecting to IoT Hub (MQTT)](../articles/iot-hub/iot-hub-mqtt-support.md#connecting-to-iot-hub).
 
 [!INCLUDE [azure-cli-prepare-your-environment.md](azure-cli-prepare-your-environment-no-header.md)]
 
 [!INCLUDE [iot-hub-cli-version-info](iot-hub-cli-version-info.md)]
 
-## Create an IoT hub
-
-If you completed the previous [Quickstart: Send telemetry from a device to an IoT hub](../articles/iot-develop/quickstart-send-telemetry-iot-hub.md?pivots=programming-language-nodejs), you can skip this step.
-
-[!INCLUDE [iot-hub-include-create-hub](iot-hub-include-create-hub.md)]
+[!INCLUDE [iot-hub-include-create-hub](iot-hub-include-create-hub-quickstart.md)]
 
 ## Register a device
 
-If you completed the previous [Quickstart: Send telemetry from a device to an IoT hub](../articles/iot-develop/quickstart-send-telemetry-iot-hub.md?pivots=programming-language-nodejs), you can skip this step.
+A device must be registered with your IoT hub before it can connect. In this quickstart, you use Azure CLI to create a device identity.
 
-A device must be registered with your IoT hub before it can connect. In this quickstart, you use the Azure Cloud Shell to register a simulated device.
+If you already have a device registered in your IoT hub, you can skip this section.
 
-1. Run the following command in Azure Cloud Shell to create the device identity.
+1. Run the [az iot hub device-identity create](/cli/azure/iot/hub/device-identity#az_iot_hub_device_identity_create) command in Azure Cloud Shell to create the device identity.
 
    **YourIoTHubName**: Replace this placeholder below with the name you chose for your IoT hub.
 
@@ -54,7 +53,7 @@ A device must be registered with your IoT hub before it can connect. In this qui
       --hub-name {YourIoTHubName} --device-id MyNodeDevice
     ```
 
-2. Run the following commands in Azure Cloud Shell to get the _device connection string_ for the device you just registered:
+2. Run the [az iot hub device-identity connection-string show](/cli/azure/iot/hub/device-identity/connection-string#az_iot_hub_device_identity_connection_string_show) command in Azure Cloud Shell to get the _device connection string_ for the device you just registered:
 
     **YourIoTHubName**: Replace this placeholder below with the name you chose for your IoT hub.
 
@@ -71,23 +70,24 @@ A device must be registered with your IoT hub before it can connect. In this qui
 
     You use this value later in the quickstart.
 
-3. You also need a _service connection string_ to enable the back-end application to connect to your IoT hub and retrieve the messages. The following command retrieves the service connection string for your IoT hub:
+## Retrieve the service connection string
 
-    **YourIoTHubName**: Replace this placeholder below with the name you chose for your IoT hub.
+You also need your IoT hub's _service connection string_ to enable the back-end application to connect to your IoT hub and retrieve the messages. The following command retrieves the service connection string for your IoT hub:
 
-    ```azurecli-interactive
-    az iot hub connection-string show \
-      --policy-name service --name {YourIoTHubName} --output table
+**YourIoTHubName**: Replace this placeholder below with the name you chose for your IoT hub.
 
-    ```
+```azurecli-interactive
+az iot hub connection-string show \
+  --policy-name service --name {YourIoTHubName} --output table
+```
 
-    Make a note of the service connection string, which looks like:
+Make a note of the service connection string, which looks like:
 
-   `HostName={YourIoTHubName}.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey={YourSharedAccessKey}`
+`HostName={YourIoTHubName}.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey={YourSharedAccessKey}`
 
-    You use this value later in the quickstart. This service connection string is different from the device connection string you noted in the previous step.
+You use this value later in the quickstart. This service connection string is different from the device connection string you noted in the previous step.
 
-## Listen for direct method calls
+## Simulate a device
 
 The simulated device application connects to a device-specific endpoint on your IoT hub, sends simulated telemetry, and listens for direct method calls from your hub. In this quickstart, the direct method call from the hub tells the device to change the interval at which it sends telemetry. The simulated device sends an acknowledgment back to your hub after it executes the direct method.
 
@@ -110,7 +110,7 @@ The simulated device application connects to a device-specific endpoint on your
 
 ## Call the direct method
 
-The back-end application connects to a service-side endpoint on your IoT Hub. The application makes direct method calls to a device through your IoT hub and listens for acknowledgments. An IoT Hub back-end application typically runs in the cloud.
+The back-end application connects to a service-side endpoint on your IoT hub. The application makes direct method calls to a device through your IoT hub and listens for acknowledgments. An IoT Hub back-end application typically runs in the cloud.
 
 1. In another local terminal window, navigate to the root folder of the sample Node.js project. Then navigate to the **iot-hub\Quickstarts\back-end-application** folder.
 
diff --git a/includes/quickstart-control-device-python.md b/includes/quickstart-control-device-python.md
