Merge pull request #204528 from JimacoMS4/fix-feedback-94680-request-id-for-method-invocation

Fix feedback 94680 direct methods request ID

Author: PRMerger3

articles/iot-hub/iot-hub-devguide-direct-methods.md

@@ -5,7 +5,7 @@ author: kgremban
 ms.service: iot-hub
 services: iot-hub
 ms.topic: conceptual
-ms.date: 07/17/2018
+ms.date: 07/15/2022
 ms.author: kgremban
 ms.custom: [amqp, mqtt,'Role: Cloud Development', 'Role: IoT Device']
 ---
@@ -40,26 +40,27 @@ The payload for method requests and responses is a JSON document up to 128 KB.
 
 ## Invoke a direct method from a back-end app
 
-Now, invoke a direct method from a back-end app.
+To invoke a direct method from a back-end app use the [Invoke device method](/rest/api/iothub/service/devices/invoke-method) REST API or its equivalent in one of the [IoT Hub service SDKs](iot-hub-devguide-sdks.md#azure-iot-hub-service-sdks).
 
 ### Method invocation
 
 Direct method invocations on a device are HTTPS calls that are made up of the following items:
 
-* The *request URI* specific to the device along with the [API version](/rest/api/iothub/service/devices/invokemethod):
+* The *request URI* specific to the device along with the API version:
 
     ```http
     https://fully-qualified-iothubname.azure-devices.net/twins/{deviceId}/methods?api-version=2021-04-12
     ```
 
 * The POST *method*
 
-* *Headers* that contain the authorization, request ID, content type, and content encoding.
+* *Headers* that contain the authorization, content type, and content encoding.
 
 * A transparent JSON *body* in the following format:
 
     ```json
     {
+        "connectTimeoutInSeconds": 200,
         "methodName": "reboot",
         "responseTimeoutInSeconds": 200,
         "payload": {
@@ -75,7 +76,7 @@ The value provided as `connectTimeoutInSeconds` in the request is the amount of
 
 #### Example
 
-This example will allow you to securely initiate a request to invoke a Direct Method on an IoT device registered to an Azure IoT Hub.
+This example will allow you to securely initiate a request to invoke a direct method on an IoT device registered to an Azure IoT hub.
 
 To begin, use the [Microsoft Azure IoT extension for Azure CLI](https://github.com/Azure/azure-iot-cli-extension) to create a SharedAccessSignature.
 
@@ -100,14 +101,15 @@ curl -X POST \
 }'
 ```
 
-Execute the modified command to invoke the specified Direct Method. Successful requests will return an HTTP 200 status code.
+Execute the modified command to invoke the specified direct method. Successful requests will return an HTTP 200 status code.
 
 > [!NOTE]
-> The above example demonstrates invoking a Direct Method on a device.  If you wish to invoke a Direct Method in an IoT Edge Module, you would need to modify the url request as shown below:
+> The example above demonstrates invoking a direct method on a device.  If you want to invoke a direct method in an IoT Edge Module, you would need to modify the url request as shown below:
+>
+> ```bash
+> https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12
+> ```
 
-```bash
-https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12
-```
 ### Response
 
 The back-end app receives a response that is made up of the following items:
@@ -117,7 +119,7 @@ The back-end app receives a response that is made up of the following items:
   * 404 indicates that either device ID is invalid, or that the device was not online upon invocation of a direct method and for `connectTimeoutInSeconds` thereafter (use accompanied error message to understand the root cause);
   * 504 indicates gateway timeout caused by device not responding to a direct method call within `responseTimeoutInSeconds`.
 
-* *Headers* that contain the ETag, request ID, content type, and content encoding.
+* *Headers* that contain the request ID, content type, and content encoding.
 
 * A JSON *body* in the following format:
 
@@ -128,25 +130,25 @@ The back-end app receives a response that is made up of the following items:
     }
     ```
 
-    Both `status` and `body` are provided by the device and used to respond with the device's own status code and/or description.
+    Both `status` and `payload` are provided by the device and used to respond with the device's own status code and the method response.
 
 ### Method invocation for IoT Edge modules
 
-Invoking direct methods using a module ID is supported in the [IoT Service Client C# SDK](https://www.nuget.org/packages/Microsoft.Azure.Devices/).
+Invoking direct methods on a module is supported by the [Invoke module method](/rest/api/iothub/service/modules/invoke-method) REST API or its equivalent in one of the IoT Hub service SDKs.
 
-For this purpose, use the `ServiceClient.InvokeDeviceMethodAsync()` method and pass in the `deviceId` and `moduleId` as parameters.
+The `moduleId` is passed along with the `deviceId` in the request URI when using the REST API or as a parameter when using a service SDK. For example, `https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12`. The request body and response is similar to that of direct methods invoked on the device.
 
 ## Handle a direct method on a device
 
-Let's look at how to handle a direct method on an IoT device.
+On an IoT device, direct methods can be received over MQTT, AMQP, or either of these protocols over WebSockets. The [IoT Hub device SDKs](iot-hub-devguide-sdks.md#azure-iot-hub-device-sdks) help you receive and respond to direct methods on devices without having to worry about the underlying protocol details.
 
 ### MQTT
 
-The following section is for the MQTT protocol.
+The following section is for the MQTT protocol. To learn more about using the MQTT protocol directly with IoT Hub, see [MQTT protocol support](iot-hub-mqtt-support.md).
 
 #### Method invocation
 
-Devices receive direct method requests on the MQTT topic: `$iothub/methods/POST/{method name}/?$rid={request id}`. The number of subscriptions per device is limited to 5. It is therefore recommended not to subscribe to each direct method individually. Instead consider subscribing to `$iothub/methods/POST/#` and then filter the delivered messages based on your desired method names.
+Devices receive direct method requests on the MQTT topic: `$iothub/methods/POST/{method name}/?$rid={request id}`. However, the `request id` is generated by IoT Hub and cannot be known ahead of time, so subscribe to `$iothub/methods/POST/#` and then filter the delivered messages based on method names supported by your device. (You'll use the `request id` to respond.)
 
 The body that the device receives is in the following format:
 
@@ -171,7 +173,7 @@ The body is set by the device and can be any status.
 
 ### AMQP
 
-The following section is for the AMQP protocol.
+The following section is for the AMQP protocol. To learn more about using the AMQP protocol directly with IoT Hub, see [AMQP protocol support](iot-hub-amqp-support.md).
 
 #### Method invocation