Skip to content

Commit f8e5f3a

Browse files
gsteve88gsteve88
committed
Edits
1 parent c636030 commit f8e5f3a

File tree

4 files changed

+95
-45
lines changed

4 files changed

+95
-45
lines changed

‎articles/iot-hub/how-to-file-upload.md

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -31,26 +31,22 @@ These files are typically batch processed in the cloud, using tools such as [Azu
3131
For more information, see:
3232

3333
* [Overview of file uploads with IoT Hub](iot-hub-devguide-file-upload.md)
34-
3534
* [Configure IoT Hub file uploads](iot-hub-configure-file-upload.md)
36-
3735
* [Azure blob storage documentation](../storage/blobs/storage-blobs-introduction.md)
38-
3936
* [Azure blob storage API reference](../storage/blobs/reference.md)
40-
4137
* [Azure IoT SDKs](iot-hub-devguide-sdks.md)
4238

4339
[!INCLUDE [iot-hub-include-x509-ca-signed-file-upload-support-note](../../includes/iot-hub-include-x509-ca-signed-file-upload-support-note.md)]
4440

4541
## Prerequisites
4642

47-
* An IoT hub. Create one with the [CLI](iot-hub-create-using-cli.md) or the [Azure portal](iot-hub-create-through-portal.md). Some SDK calls require the IoT Hub connection string.
43+
* **An IoT hub**. Create one with the [Azure CLI](iot-hub-create-using-cli.md) or the [Azure portal](iot-hub-create-through-portal.md). Some SDK calls require the IoT Hub connection string.
4844

49-
* A registered device. Register one in the [Azure portal](iot-hub-create-through-portal.md).
45+
* **A registered device**. Register one in the [Azure portal](iot-hub-create-through-portal.md).
5046

51-
* IoT Hub **Service Connect** permission - To receive file upload notification messages, your backend service needs the **Service Connect** permission. By default, every IoT Hub is created with a shared access policy named **service** that grants this permission. For more information, see [Create an IoT hub using the Azure portal](/azure/iot-hub/iot-hub-create-through-portal).
47+
* IoT Hub **Service Connect** permission - To receive file upload notification messages, your backend service needs the **Service Connect** permission. By default, every IoT Hub is created with a shared access policy named **service** that grants this permission. For more information, see [Create an IoT hub using the Azure portal](/azure/iot-hub/iot-hub-create-through-portal?#shared-access-policies).
5248

53-
* An Azure Storage account and Azure Blob Storage container associated with IoT Hub. You can configure this using the [Azure portal](/azure/iot-hub/iot-hub-configure-file-upload), [Azure CLI](/azure/iot-hub/iot-hub-configure-file-upload-cli), or [Azure PowerShell](/azure/iot-hub/iot-hub-configure-file-upload-powershell).
49+
* An **Azure Storage account** and **Azure Blob Storage container** associated with IoT Hub. You can configure these using the [Azure portal](/azure/iot-hub/iot-hub-configure-file-upload), [Azure CLI](/azure/iot-hub/iot-hub-configure-file-upload-cli), or [Azure PowerShell](/azure/iot-hub/iot-hub-configure-file-upload-powershell).
5450

5551
:::zone pivot="programming-language-csharp"
5652

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

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,7 @@ Follow this procedure for uploading a file from a device to IoT Hub:
2020
* Upload the file to Azure storage
2121
* Notify IoT Hub that it completed the upload
2222

23-
There are two SDK classes that are used to upload files to IoT Hub.
24-
25-
* The [DeviceClient](/dotnet/api/microsoft.azure.devices.client.deviceclient) class contains methods that a device can use to upload files to IoT Hub.
26-
* The [ServiceClient](/dotnet/api/microsoft.azure.devices.serviceclient) class contains methods that services can use to receive file upload notification.
23+
The [DeviceClient](/dotnet/api/microsoft.azure.devices.client.deviceclient) class contains methods that a device can use to upload files to IoT Hub.
2724

2825
### Connect to IoT Hub
2926

@@ -95,7 +92,7 @@ await _deviceClient.CompleteFileUploadAsync(successfulFileUploadCompletionNotifi
9592

9693
## Receive a file upload notification in a backend application
9794

98-
This section describes how to receive file upload notification messages from IoT Hub.
95+
You can create a backend service to receive file upload notification messages from IoT Hub.
9996

10097
### Instantiate the service client
10198

@@ -115,7 +112,15 @@ serviceClient = ServiceClient.CreateFromConnectionString(connectionString);
115112

116113
### Receive the file upload notification
117114

118-
Call [GetFileNotificationReceiver](/dotnet/api/microsoft.azure.devices.serviceclient.getfilenotificationreceiver?#microsoft-azure-devices-serviceclient-getfilenotificationreceiver) to create a notification receiver. Then 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.
115+
You can create a separate backend service to receive file upload notifications.
116+
117+
The [ServiceClient](/dotnet/api/microsoft.azure.devices.serviceclient) class contains methods that services can use to receive file upload notification.
118+
119+
To receive file upload notification:
120+
121+
* Create a [CancellationToken](/dotnet/api/azure.core.httpmessage.cancellationtoken?view=azure-dotnet&branch=main#azure-core-httpmessage-cancellationtoken).
122+
* Call [GetFileNotificationReceiver](/dotnet/api/microsoft.azure.devices.serviceclient.getfilenotificationreceiver?#microsoft-azure-devices-serviceclient-getfilenotificationreceiver) to create a notification receiver.
123+
* 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.
119124

120125
```csharp
121126
// Define the cancellation token.
@@ -138,4 +143,4 @@ while (true)
138143

139144
### Sample
140145

141-
The SDK includes one [sample](https://github.com/Azure/azure-iot-sdk-csharp/blob/main/iothub/device/samples/getting%20started/FileUploadSample/FileUploadSample.cs).
146+
The SDK includes this [sample](https://github.com/Azure/azure-iot-sdk-csharp/blob/main/iothub/device/samples/getting%20started/FileUploadSample/FileUploadSample.cs).

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

Lines changed: 61 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,14 @@ ms.custom: amqp, mqtt, devx-track-java, devx-track-extended-java
1313

1414
## Upload a file from a device
1515

16-
There are two SDK classes that are used to upload files to IoT Hub.
16+
Follow this procedure for uploading a file from a device to IoT Hub:
1717

18-
* The [DeviceClient](/dotnet/api/microsoft.azure.devices.client.deviceclient) class contains methods that a device can use to upload files to IoT Hub.
19-
* The [ServiceClient](/dotnet/api/microsoft.azure.devices.serviceclient) class contains methods that services can use to receive file upload notification.
18+
* Connect to IoT Hub
19+
* Get a SAS URI from IoT Hub
20+
* Upload the file to Azure Storage
21+
* Send file upload status notification to IoT Hub
22+
23+
The [DeviceClient](/java/api/com.microsoft.azure.sdk.iot.device.deviceclient) class contains methods that a device can use to upload files to IoT Hub.
2024

2125
### Connection protocol
2226

@@ -35,16 +39,16 @@ String connString = "Your device connection string here";
3539
DeviceClient client = new DeviceClient(connString, protocol);
3640
```
3741

38-
### Retrieve the SAS URI from Iot Hub
42+
### Get a SAS URI from Iot Hub
3943

4044
Call [getFileUploadSasUri](/java/api/com.microsoft.azure.sdk.iot.device.deviceclient?#com-microsoft-azure-sdk-iot-device-deviceclient-getfileuploadsasuri(com-microsoft-azure-sdk-iot-deps-serializer-fileuploadsasurirequest)) to obtain a [FileUploadSasUriResponse](/java/api/com.microsoft.azure.sdk.iot.deps.serializer.fileuploadsasuriresponse) object.
4145

42-
FileUploadSasUriResponse includes these methods, which are passed to file upload methods. The Blob URI (SAS URI) is used to upload a file to blob storage.
46+
`FileUploadSasUriResponse` includes these methods and return values. The return values can be passed to file upload methods.
4347

44-
* Correlation ID - `getCorrelationId())`
45-
* Container name - `getContainerName())`
46-
* Blob name - `getBlobName())`
47-
* Blob Uri - `getBlobUri())`
48+
* `getCorrelationId())` - Correlation ID
49+
* `getContainerName())` - Container name
50+
* `getBlobName())` - Blob name
51+
* `getBlobUri())` - Blob URI
4852

4953
For example:
5054

@@ -58,7 +62,7 @@ System.out.println("Blob name: " + sasUriResponse.getBlobName());
5862
System.out.println("Blob Uri: " + sasUriResponse.getBlobUri());
5963
```
6064

61-
### Upload the file
65+
### Upload the file to Azure Storage
6266

6367
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.
6468

@@ -78,6 +82,8 @@ blobClient.uploadFromFile(fullFileName);
7882

7983
## Send file upload status notification to IoT Hub
8084

85+
Send an upload status notification to IoT hub after a file upload attempt.
86+
8187
Create a [FileUploadCompletionNotification](/java/api/com.microsoft.azure.sdk.iot.deps.serializer.fileuploadcompletionnotification?#com-microsoft-azure-sdk-iot-deps-serializer-fileuploadcompletionnotification-fileuploadcompletionnotification(java-lang-string-java-lang-boolean)) object. Pass the `correlationId` and `isSuccess` file upload success status. Pass an `isSuccess` `true` value when file upload was successful, `false` when not.
8288

8389
`FileUploadCompletionNotification` must be called even when the file upload fails. IoT Hub has a fixed number of SAS URI allowed to be active at any given time. Once you're done with the file upload, you should free your SAS URI so that other SAS URI can be generated. If a SAS URI isn't freed through this API, then it frees itself eventually based on how long SAS URI are configured to live on an IoT Hub.
@@ -97,6 +103,50 @@ Free the `client` resources.
97103
client.closeNow();
98104
```
99105

100-
### Samples
106+
## Receive a file upload notification
107+
108+
You can create an application to receive file upload notifications.
109+
110+
The [ServiceClient](/java/api/com.azure.core.annotation.serviceclient) class contains methods that services can use to receive file upload notifications.
111+
112+
### Connect the client to IoT hub
113+
114+
Create a `IotHubServiceClientProtocol` object. The connection uses the `AMQPS` protocol.
115+
116+
Call `createFromConnectionString` to connect to IoT hub.
117+
118+
```java
119+
private static final String connectionString = "{Your service connection string here}";
120+
private static final IotHubServiceClientProtocol protocol = IotHubServiceClientProtocol.AMQPS;
121+
ServiceClient sc = ServiceClient.createFromConnectionString(connectionString, protocol);
122+
```
123+
124+
### Check for file upload status
125+
126+
```java
127+
FileUploadNotificationReceiver receiver = sc.getFileUploadNotificationReceiver();
128+
receiver.open();
129+
FileUploadNotification fileUploadNotification = receiver.receive(2000);
130+
131+
if (fileUploadNotification != null)
132+
{
133+
System.out.println("File Upload notification received");
134+
System.out.println("Device Id : " + fileUploadNotification.getDeviceId());
135+
System.out.println("Blob Uri: " + fileUploadNotification.getBlobUri());
136+
System.out.println("Blob Name: " + fileUploadNotification.getBlobName());
137+
System.out.println("Last Updated : " + fileUploadNotification.getLastUpdatedTimeDate());
138+
System.out.println("Blob Size (Bytes): " + fileUploadNotification.getBlobSizeInBytes());
139+
System.out.println("Enqueued Time: " + fileUploadNotification.getEnqueuedTimeUtcDate());
140+
}
141+
else
142+
{
143+
System.out.println("No file upload notification");
144+
}
145+
146+
// Close the receiver object
147+
receiver.close();
148+
```
149+
150+
## Samples
101151

102152
There are two Java file upload [samples](https://github.com/Azure/azure-iot-sdk-java/tree/main/iothub/device/iot-device-samples/file-upload-sample/src/main/java/samples/com/microsoft/azure/sdk/iot).

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

Lines changed: 18 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -27,12 +27,11 @@ pip install azure.storage.blob
2727

2828
## Upload file from a device application
2929

30-
Follow this procedure for uploading a file from a device to IoT Hub:
30+
Follow this procedure for uploading a file from a device to IoT hub:
3131

32-
* Connect to IoT Hub
33-
* Get a SAS URI from IoT Hub
34-
* Upload the file to Azure storage
35-
* Notify IoT Hub that it completed the upload
32+
* Connect the client to IoT hub and get storage information
33+
* Upload the file to BloB Storage
34+
* Notify IoT hub of upload status
3635

3736
### Import statements
3837

@@ -45,18 +44,18 @@ from azure.core.exceptions import AzureError
4544
from azure.storage.blob import BlobClient
4645
```
4746

48-
### Connect the client and get storage information
47+
### Connect the client to IoT hub and get storage information
4948

50-
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.
49+
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.
5150

5251
For example:
5352

5453
```python
55-
CONNECTION_STRING = "[Device Connection String]"
54+
CONNECTION_STRING = "[IoT hub Connection String]"
5655
device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)
5756
```
5857

59-
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.
58+
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.
6059

6160
For example:
6261

@@ -76,13 +75,14 @@ blob_name = os.path.basename(PATH_TO_FILE)
7675
storage_info = device_client.get_storage_info_for_blob(blob_name)
7776
```
7877

79-
### Upload the file to blob storage
78+
### Upload a file into Blob Storage
8079

81-
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.
80+
To upload a file into Blob Storage:
8281

83-
Then 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.
82+
* 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.
83+
* 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.
8484

85-
This example function parses the passed `blob_info` structure passed 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 Azure blob storage.
85+
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.
8686

8787
```python
8888
def store_blob(blob_info, file_name):
@@ -112,9 +112,9 @@ def store_blob(blob_info, file_name):
112112
return (False, ex)
113113
```
114114

115-
### Wait for upload status
115+
### Notify IoT hub of upload status
116116

117-
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.
117+
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.
118118

119119
For example:
120120

@@ -124,16 +124,15 @@ device_client.notify_blob_upload_status(storage_info["correlationId"], True, 200
124124

125125
### Shut down the device client
126126

127-
Shut down the client for graceful exit. Once this method is called, any attempts at further client calls result in a [ClientError](/python/api/azure-iot-device/azure.iot.device.exceptions.clienterror) being raised.
127+
Shut down the client. Once this method is called, any attempts at further client calls result in a [ClientError](/python/api/azure-iot-device/azure.iot.device.exceptions.clienterror) being raised.
128128

129129
```python
130-
# Graceful exit
131-
device_client.shutdown()
130+
device_client.shutdown()
132131
```
133132

134133
### Error handling example
135134

136-
This example shows a function that contains the previous steps with error handling logic.
135+
This example shows a function that contains the previous steps including error handling logic.
137136

138137
```python
139138
def run_sample(device_client):

0 commit comments

Comments
 (0)