Edits

Author: gsteve88

includes/iot-hub-howto-file-upload-dotnet.md

@@ -25,7 +25,7 @@ Follow this procedure to upload a file from a device to IoT Hub:
 * Connect to IoT Hub
 * Get a SAS URI from IoT Hub
 * Upload the file to Azure storage
-* Notify IoT Hub that it completed the upload
+* Notify IoT hub of the file upload status
 
 ### Connect to IoT Hub
 
@@ -38,7 +38,7 @@ deviceClient = DeviceClient.CreateFromConnectionString(connectionString);
 
 ### Get a SAS URI from IoT Hub
 
-Call [GetFileUploadSasUriAsync](/dotnet/api/microsoft.azure.devices.client.deviceclient.getfileuploadsasuriasync) to get a file upload SAS URI, which the Azure Storage SDK can use to upload a file from a device to Blob Storage.
+Call [GetFileUploadSasUriAsync](/dotnet/api/microsoft.azure.devices.client.deviceclient.getfileuploadsasuriasync) to get a file upload details. The SAS URI is used in the next step to upload a file from a device to Blob Storage.
 
 ```csharp
 const string filePath = "TestPayload.txt";
@@ -53,26 +53,28 @@ FileUploadSasUriResponse sasUri = await _deviceClient.GetFileUploadSasUriAsync(f
 Uri uploadUri = sasUri.GetBlobUri();
 ```
 
-### Upload the file to Azure storage
+### Upload a file to Azure storage
 
-Create a [blockBlobClient](/dotnet/api/azure.storage.blobs.specialized.blockblobclient) object, passing a file upload URI.
+To upload a file to Azure storage:
 
-Use the [UploadAsync](/dotnet/api/azure.storage.blobs.specialized.blockblobclient.uploadasync?#azure-storage-blobs-specialized-blockblobclient-uploadasync(system-io-stream-azure-storage-blobs-models-blobuploadoptions-system-threading-cancellationtoken)) method to upload a file to Blob Storage, passing the SAS URI.
+* Create a [blockBlobClient](/dotnet/api/azure.storage.blobs.specialized.blockblobclient) object, passing a file upload URI
+
+* Use the [UploadAsync](/dotnet/api/azure.storage.blobs.specialized.blockblobclient.uploadasync?#azure-storage-blobs-specialized-blockblobclient-uploadasync(system-io-stream-azure-storage-blobs-models-blobuploadoptions-system-threading-cancellationtoken)) method to upload a file to Blob Storage, passing the SAS URI
 
 The Azure Blob client always uses HTTPS as the protocol to upload the file to Azure Storage.
 
-In this example, `BlockBlobClient` is passed the SAS URI to create an Azure Storage block blob client and uploads the file:
+In this example, `BlockBlobClient` is passed the SAS URI to create an Azure Storage block Blob client and uploads the file:
 
 ```csharp
 var blockBlobClient = new BlockBlobClient(uploadUri);
 await blockBlobClient.UploadAsync(fileStreamSource, new BlobUploadOptions());
 ```
 
-### Notify IoT hub that it completed the upload
+### Notify IoT hub of the file upload status
 
-Use [CompleteFileUploadAsync](/dotnet/api/microsoft.azure.devices.client.deviceclient.completefileuploadasync) to notify IoT Hub that the device client completed the upload. After being notified, IoT Hub will release resources associated with the upload (the SAS URI).
+Use [CompleteFileUploadAsync](/dotnet/api/microsoft.azure.devices.client.deviceclient.completefileuploadasync) to notify IoT Hub that the device client completed the upload, passing a [FileUploadCompletionNotification](/dotnet/api/microsoft.azure.devices.client.transport.fileuploadcompletionnotification) object. The `IsSuccess` flag indicates whether or not the upload was successful. After being notified, IoT Hub will release resources associated with the upload (the SAS URI).
 
-If file upload notifications are enabled, IoT Hub sends a notification message to backend services.
+If file upload notifications are enabled, IoT Hub sends a file upload notification message to backend services that are configured for file upload notification.
 
 ```csharp
 var successfulFileUploadCompletionNotification = new FileUploadCompletionNotification
@@ -97,22 +99,7 @@ await _deviceClient.CompleteFileUploadAsync(successfulFileUploadCompletionNotifi
 
 You can create a backend service to receive file upload notification messages from IoT Hub.
 
-### Add the connection string
-
-Replace the `{IoT Hub connection string}` placeholder value with the IoT Hub connection string.
-
-```csharp
-using Microsoft.Azure.Devices;
-static ServiceClient serviceClient;
-static string connectionString = "{IoT Hub connection string}";
-serviceClient = ServiceClient.CreateFromConnectionString(connectionString);
-```
-
-### Receive file upload notification in a backend application
-
-You can create a separate backend application to receive file upload notifications.
-
-The [ServiceClient](/dotnet/api/microsoft.azure.devices.serviceclient) class contains methods that services can use to receive file upload notification.
+The [ServiceClient](/dotnet/api/microsoft.azure.devices.serviceclient) class contains methods that services can use to receive file upload notifications.
 
 To receive file upload notification:
 
@@ -121,12 +108,20 @@ To receive file upload notification:
 * Use a loop with [ReceiveAsync](/dotnet/api/microsoft.azure.devices.receiver-1.receiveasync?#microsoft-azure-devices-receiver-1-receiveasync(system-threading-cancellationtoken)) to wait for the file upload notification.
 
 ```csharp
-// Define the cancellation token.
+using Microsoft.Azure.Devices;
+static ServiceClient serviceClient;
+static string connectionString = "{IoT Hub connection string}";
+serviceClient = ServiceClient.CreateFromConnectionString(connectionString);
+
+// Define the cancellation token
 CancellationTokenSource source = new CancellationTokenSource();
 CancellationToken token = source.Token;
 
+// Create a notification receiver
 var notificationReceiver = serviceClient.GetFileNotificationReceiver();
 Console.WriteLine("\nReceiving file upload notification from service");
+
+// Check for file upload notifications
 while (true)
 {
     var fileUploadNotification = await notificationReceiver.ReceiveAsync(token);

includes/iot-hub-howto-file-upload-java.md

@@ -37,7 +37,7 @@ IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;
 
 ### Connect to IoT Hub
 
-Instantiate the DeviceClient to connect to IoT hub using the connection string and protocol parameters.
+Instantiate the DeviceClient to connect to IoT hub using the Iot hub primary connection string and protocol parameters.
 
 ```java
 String connString = "IoT hub connection string";
@@ -71,7 +71,7 @@ System.out.println("Blob Uri: " + sasUriResponse.getBlobUri());
 
 ### Upload the file to Azure Storage
 
-Pass the blob URI endpoint to [BlobClientBuilder](/java/api/com.azure.storage.blob.blobclientbuilder?#com-azure-storage-blob-blobclientbuilder-buildclient()) to create the [BlobClient](/java/api/com.azure.storage.blob.blobclient) object.
+Pass the blob URI endpoint to [BlobClientBuilder.buildclient](/java/api/com.azure.storage.blob.blobclientbuilder?#com-azure-storage-blob-blobclientbuilder-buildclient()) to create the [BlobClient](/java/api/com.azure.storage.blob.blobclient) object.
 
 ```java
 BlobClient blobClient =
@@ -130,6 +130,8 @@ ServiceClient sc = ServiceClient.createFromConnectionString(connectionString, pr
 
 ### Check for file upload status
 
+To check for file upload status:
+
 * Create a [getFileUploadNotificationReceiver](/java/api/com.microsoft.azure.sdk.iot.service.fileuploadnotificationreceiver) object.
 * Use [open](/java/api/com.microsoft.azure.sdk.iot.service.fileuploadnotificationreceiver?#com-microsoft-azure-sdk-iot-service-fileuploadnotificationreceiver-open()) to connect to IoT Hub.
 * Call [receive](/java/api/com.microsoft.azure.sdk.iot.service.fileuploadnotificationreceiver?#com-microsoft-azure-sdk-iot-service-fileuploadnotificationreceiver-receive()) to check for the file upload status. This method returns a [fileUploadNotification](/java/api/com.microsoft.azure.sdk.iot.service.fileuploadnotification) object. If an upload notice is received, you can view upload status fields using [fileUploadNotification](/java/api/com.microsoft.azure.sdk.iot.service.fileuploadnotification) methods.

includes/iot-hub-howto-file-upload-node.md

@@ -129,51 +129,52 @@ You can create a backend application to check the IoT Hub service client for dev
 
 ### Connect to the IoT Hub service client
 
-Create the [Client](/javascript/api/azure-iothub/client) using [fromConnectionString](/javascript/api/azure-iothub/client?#azure-iothub-client-fromconnectionstring).
+Create the [ServiceClient](/javascript/api/azure-iothub/client) using [fromConnectionString](/javascript/api/azure-iothub/client?#azure-iothub-client-fromconnectionstring).
 
 ```javascript
 const Client = require('azure-iothub').Client;
 const connectionString = "{IoT hub connection string}";
 const serviceClient = Client.fromConnectionString(connectionString);
 ```
 
+[Open](/javascript/api/azure-iothub/client?#azure-iothub-client-open-1) the connection to IoT hub.
+
+```javascript
+//Open the connection to IoT hub
+serviceClient.open(function (err) {
+  if (err) {
+    console.error('Could not connect: ' + err.message);
+  } else {
+    console.log('Service client connected');
+```
+
 ### Check for a file upload notification
 
 To check for file upload notifications:
 
-* [Open](/javascript/api/azure-iothub/client?#azure-iothub-client-open-1) the connection to IoT hub.
 * Call [getFileNotificationReceiver](/javascript/api/azure-iothub/client?#azure-iothub-client-getfilenotificationreceiver). Supply the name of a file upload callback method that will be called when notification messages are received.
 * Process file upload notifications in the callback method.
 
 This example sets up a `receiveFileUploadNotification` notification  callback receiver. The receiver interprets the file upload status information and prints a status messsage to the console.
 
 ```javascript
-//Open the connection to IoT hub
-serviceClient.open(function (err) {
-  if (err) {
-    console.error('Could not connect: ' + err.message);
-  } else {
-    console.log('Service client connected');
-    //Set up the receiveFileUploadNotification notification message callback receiver
-    serviceClient.getFileNotificationReceiver(function receiveFileUploadNotification(err, receiver){
+//Set up the receiveFileUploadNotification notification message callback receiver
+serviceClient.getFileNotificationReceiver(function receiveFileUploadNotification(err, receiver){
+if (err) {
+  console.error('error getting the file notification receiver: ' + err.toString());
+} else {
+  receiver.on('message', function (msg) {
+    console.log('File upload from device:')
+    console.log(msg.getData().toString('utf-8'));
+    receiver.complete(msg, function (err) {
       if (err) {
-        console.error('error getting the file notification receiver: ' + err.toString());
+        console.error('Could not finish the upload: ' + err.message);
       } else {
-        receiver.on('message', function (msg) {
-          console.log('File upload from device:')
-          console.log(msg.getData().toString('utf-8'));
-          receiver.complete(msg, function (err) {
-            if (err) {
-              console.error('Could not finish the upload: ' + err.message);
-            } else {
-              console.log('Upload complete');
-            }
-          });
-        });
+        console.log('Upload complete');
       }
     });
-  }
-});
+  });
+}
 ```
 
 ### SDK file upload sample

includes/iot-hub-howto-file-upload-python.md

@@ -34,7 +34,7 @@ Follow this procedure to upload a file from a device to IoT hub:
 * Upload the file to Blob Storage
 * Notify IoT hub of upload status
 
-### Connect to IoT hub
+### Import libraries
 
 ```python
 import os
@@ -43,31 +43,30 @@ from azure.core.exceptions import AzureError
 from azure.storage.blob import BlobClient
 ```
 
-Call [create_from_connection_string](/python/api/azure-iot-device/azure.iot.device.iothubdeviceclient?#azure-iot-device-iothubdeviceclient-create-from-connection-string) to connect to IoT hub.
+### Connect to IoT hub
+
+Call [create_from_connection_string](/python/api/azure-iot-device/azure.iot.device.iothubdeviceclient?#azure-iot-device-iothubdeviceclient-create-from-connection-string) to add the connection string. Then call [connect](/python/api/azure-iot-device/azure.iot.device.iothubdeviceclient?#azure-iot-device-iothubdeviceclient-connect) to connect the device client to an Azure IoT hub.
 
 For example:
 
 ```python
+# Add your IoT hub primary connection string
 CONNECTION_STRING = "{IoT hub connection string}"
 device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)
-```
-
-Call [connect](/python/api/azure-iot-device/azure.iot.device.iothubdeviceclient?#azure-iot-device-iothubdeviceclient-connect) to connect the device client to an Azure IoT hub.
 
-```python
 # Connect the client
 device_client.connect()
 ```
 
 ### Get Blob Storage information
 
-Call [get_storage_info_for_blob](/python/api/azure-iot-device/azure.iot.device.iothubdeviceclient?#azure-iot-device-iothubdeviceclient-get-storage-info-for-blob) to get information from an IoT hub about a linked Storage Account. This information includes the hostname, container name, blob name, and a SAS token. The storage info is passed to the `store_blob` function (created in the previous step), so that the `BlobClient` in that function can authenticate with Azure storage. The `get_storage_info_for_blob` method also returns a `correlation_id`, which is used in the notify_blob_upload_status method. The correlation_id is IoT Hub's way of marking which blob you're working on.
+Call [get_storage_info_for_blob](/python/api/azure-iot-device/azure.iot.device.iothubdeviceclient?#azure-iot-device-iothubdeviceclient-get-storage-info-for-blob) to get information from an IoT hub about a linked Azure Storage account. This information includes the hostname, container name, blob name, and a SAS token. The `get_storage_info_for_blob` method also returns a `correlation_id`, which is used in the `notify_blob_upload_status` method. The `correlation_id` is IoT Hub's way of marking which Blob you're working on.
 
 ```python
 # Get the storage info for the blob
 PATH_TO_FILE = "[Full path to local file]"
 blob_name = os.path.basename(PATH_TO_FILE)
-storage_info = device_client.get_storage_info_for_blob(blob_name)
+blob_info = device_client.get_storage_info_for_blob(blob_name)
 ```
 
 ### Upload a file into Blob Storage
@@ -77,41 +76,40 @@ To upload a file into Blob Storage:
 * Use [from_blob_url](/python/api/azure-storage-blob/azure.storage.blob.blobclient?#azure-storage-blob-blobclient-from-blob-url) to create a [BlobClient](/python/api/azure-storage-blob/azure.storage.blob.blobclient?#azure-storage-blob-blobclient-from-blob-url) object from a blob URL.
 * Call [upload_blob](/python/api/azure-storage-blob/azure.storage.blob.blobclient?#azure-storage-blob-blobclient-upload-blob) to upload the file into the Blob Storage.
 
-This example function parses the passed `blob_info` structure to create a URL that it uses to initialize an [BlobClient](/python/api/azure-storage-blob/azure.storage.blob.blobclient). Then it calls `upload_blob` to upload the file into Blob Storage.
+This example parses the `blob_info` structure to create a URL that it uses to initialize an [BlobClient](/python/api/azure-storage-blob/azure.storage.blob.blobclient). Then it calls `upload_blob` to upload the file into Blob Storage.
 
 ```python
-def store_blob(blob_info, file_name):
-    try:
-        sas_url = "https://{}/{}/{}{}".format(
-            blob_info["hostName"],
-            blob_info["containerName"],
-            blob_info["blobName"],
-            blob_info["sasToken"]
-        )
-
-        print("\nUploading file: {} to Azure Storage as blob: {} in container {}\n".format(file_name, blob_info["blobName"], blob_info["containerName"]))
-
-        # Upload the specified file
-        with BlobClient.from_blob_url(sas_url) as blob_client:
-            with open(file_name, "rb") as f:
-                result = blob_client.upload_blob(f, overwrite=True)
-                return (True, result)
-
-    except FileNotFoundError as ex:
-        # catch file not found and add an HTTP status code to return in notification to IoT Hub
-        ex.status_code = 404
-        return (False, ex)
-
-    except AzureError as ex:
-        # catch Azure errors that might result from the upload operation
-        return (False, ex)
+try:
+    sas_url = "https://{}/{}/{}{}".format(
+        blob_info["hostName"],
+        blob_info["containerName"],
+        blob_info["blobName"],
+        blob_info["sasToken"]
+    )
+
+    print("\nUploading file: {} to Azure Storage as blob: {} in container {}\n".format(file_name, blob_info["blobName"], blob_info["containerName"]))
+
+    # Upload the specified file
+    with BlobClient.from_blob_url(sas_url) as blob_client:
+        with open(file_name, "rb") as f:
+            result = blob_client.upload_blob(f, overwrite=True)
+            return (True, result)
+
+except FileNotFoundError as ex:
+    # catch file not found and add an HTTP status code to return in notification to IoT Hub
+    ex.status_code = 404
+    return (False, ex)
+
+except AzureError as ex:
+    # catch Azure errors that might result from the upload operation
+    return (False, ex)
 ```
 
 ### Notify IoT hub of upload status
 
 Use [notify_blob_upload_status](/python/api/azure-iot-device/azure.iot.device.iothubdeviceclient?#azure-iot-device-iothubdeviceclient-notify-blob-upload-status) to notify IoT hub of the status of the Blob Storage operation. Pass the `correlation_id` obtained by the `get_storage_info_for_blob` method. The `correlation_id` is used by IoT Hub to notify any service that might be listening for a notification regarding the status of the file upload task.
 
-For example:
+This example notifies IoT hub of a successful file upload:
 
 ```python
 device_client.notify_blob_upload_status(storage_info["correlationId"], True, 200, "OK: {}".format(PATH_TO_FILE)
@@ -125,43 +123,7 @@ Shut down the client. Once this method is called, any attempts at further client
 device_client.shutdown()
 ```
 
-### Error handling example
-
-This example shows a function that contains the previous steps including error handling logic.
-
-```python
-def run_sample(device_client):
-    # Connect the client
-    device_client.connect()
-
-    # Get the storage info for the blob
-    blob_name = os.path.basename(PATH_TO_FILE)
-    storage_info = device_client.get_storage_info_for_blob(blob_name)
-
-    # Upload to blob
-    success, result = store_blob(storage_info, PATH_TO_FILE)
-
-    if success == True:
-        print("Upload succeeded. Result is: \n") 
-        print(result)
-        print()
-
-        device_client.notify_blob_upload_status(
-            storage_info["correlationId"], True, 200, "OK: {}".format(PATH_TO_FILE)
-        )
-
-    else :
-        # If the upload was not successful, the result is the exception object
-        print("Upload failed. Exception is: \n") 
-        print(result)
-        print()
-
-        device_client.notify_blob_upload_status(
-            storage_info["correlationId"], False, result.status_code, str(result)
-        )
-```
-
-### Sample
+### SDK file upload sample
 
 The SDK includes two file upload samples: