Skip to content

Commit 150f8eb

Browse files
gsteve88gsteve88
committed
Update how to schedule and broadcast jobs article
1 parent 54e9a11 commit 150f8eb

5 files changed

+531
-0
lines changed

‎articles/iot-hub/how-to-schedule-broadcast-jobs.md

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
title: Use jobs to schedule tasks for groups of devices
3+
titleSuffix: Azure IoT Hub
4+
description: How to use the service SDK to schedule a job that invokes a device direct method and updates desired device twin properties.
5+
author: kgremban
6+
ms.author: kgremban
7+
manager: lizross
8+
ms.service: azure-iot-hub
9+
ms.devlang: csharp
10+
ms.topic: how-to
11+
ms.date: 1/7/2025
12+
zone_pivot_groups: iot-hub-howto-c2d-1
13+
---
14+
15+
This article shows you how to create back-end app code to schedule device direct method and device twin desired property updates.
16+
17+
Use Azure IoT Hub to schedule and track jobs that update millions of devices. Use jobs to:
18+
19+
* Update desired properties
20+
* Update tags
21+
* Invoke direct methods
22+
23+
A job wraps one of these actions and tracks the execution against a set of devices that is defined by a device twin query. For example, a back-end app can use a job to invoke a direct method on 10,000 devices that reboots the devices. You specify the set of devices with a device twin query and schedule the job to run at a future time. The job tracks progress as each of the devices receives and executes the reboot direct method.
24+
25+
To learn more about each of these capabilities, see:
26+
27+
* Device twin and properties: [Get started with device twins](device-twins-dotnet.md) and [Understand and use device twins in IoT Hub](iot-hub-devguide-device-twins.md)
28+
* Direct methods: [IoT Hub developer guide - direct methods](iot-hub-devguide-direct-methods.md)
29+
30+
[!INCLUDE [iot-hub-basic](../../includes/iot-hub-basic-whole.md)]
31+
32+
> [!NOTE]
33+
> This article is meant to complement [Azure IoT SDKs](iot-hub-devguide-sdks.md) samples that are referenced from within this article. You can use SDK tools to build both device and back-end applications.
34+
35+
## Prerequisites
36+
37+
* An IoT hub
38+
39+
* A registered device
40+
41+
* If your application uses the MQTT protocol, make sure that port 8883 is open in your firewall. The MQTT protocol 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)](../iot/iot-mqtt-connect-to-iot-hub.md#connecting-to-iot-hub).
42+
43+
:::zone pivot="programming-language-csharp"
44+
45+
[!INCLUDE [iot-hub-howto-schedule-broadcast-jobs-dotnet](../../includes/iot-hub-howto-schedule-broadcast-jobs-dotnet.md)]
46+
47+
:::zone-end
48+
49+
:::zone pivot="programming-language-java"
50+
51+
[!INCLUDE [iot-hub-howto-schedule-broadcast-jobs-java](../../includes/iot-hub-howto-schedule-broadcast-jobs-java.md)]
52+
53+
:::zone-end
54+
55+
:::zone pivot="programming-language-python"
56+
57+
[!INCLUDE [iot-hub-howto-schedule-broadcast-jobs-python](../../includes/iot-hub-howto-schedule-broadcast-jobs-python.md)]
58+
59+
:::zone-end
60+
61+
:::zone pivot="programming-language-node"
62+
63+
[!INCLUDE [iot-hub-howto-schedule-broadcast-jobs-node](../../includes/iot-hub-howto-schedule-broadcast-jobs-node.md)]
64+
65+
:::zone-end

‎includes/iot-hub-howto-schedule-broadcast-jobs-dotnet.md

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
title: Schedule and broadcast jobs (.NET)
3+
titleSuffix: Azure IoT Hub
4+
description: How to use the Azure IoT SDK for .NET to create backend service application code for job scheduling.
5+
author: kgremban
6+
ms.author: kgremban
7+
ms.service: azure-iot-hub
8+
ms.devlang: csharp
9+
ms.topic: include
10+
ms.date: 1/7/2025
11+
ms.custom: [amqp, mqtt, "Role: Cloud Development", "Role: IoT Device", devx-track-csharp, devx-track-dotnet]
12+
---
13+
14+
* Requires Visual Studio
15+
16+
## Overview
17+
18+
This article describes how to use the [Azure IoT SDK for .NET](https://github.com/Azure/azure-iot-sdk-csharp/blob/main/readme.md) to create backend service application code for job scheduling.
19+
20+
### Add service NuGet Package
21+
22+
Backend service applications require the **Microsoft.Azure.Devices** NuGet package.
23+
24+
### Using statements
25+
26+
Add the following using statements.
27+
28+
```csharp
29+
using Microsoft.Azure.Devices;
30+
using Microsoft.Azure.Devices.Shared;
31+
32+
using System.Threading;
33+
using System.Threading.Tasks;
34+
```
35+
36+
### Connect to IoT hub
37+
38+
You can connect a backend service to IoT Hub using the following methods:
39+
40+
* Shared access policy
41+
* Microsoft Entra
42+
43+
[!INCLUDE [iot-authentication-service-connection-string.md](iot-authentication-service-connection-string.md)]
44+
45+
#### Connect using a shared access policy
46+
47+
Connect a backend application to a device using [CreateFromConnectionString](/dotnet/api/microsoft.azure.devices.jobclient.createfromconnectionstring).
48+
49+
In this article, you create a back-end service that schedules a job to invoke a direct method on a device, schedules a job to update the device twin, and monitors the progress of each job. To perform these operations, your service needs the **registry read** and **registry write permissions**. By default, every IoT hub is created with a shared access policy named **registryReadWrite** that grants these permissions.
50+
51+
For more information about shared access policies, see [Control access to IoT Hub with shared access signatures](/azure/iot-hub/authenticate-authorize-sas).
52+
53+
```csharp
54+
static JobClient jobClient;
55+
static string connectionString = "{Shared access policy connection string}";
56+
jobClient = JobClient.CreateFromConnectionString(connString);
57+
```
58+
59+
#### Connect using Microsoft Entra
60+
61+
[!INCLUDE [iot-hub-howto-connect-service-iothub-entra-dotnet](iot-hub-howto-connect-service-iothub-entra-dotnet.md)]
62+
63+
### Create a device method update job
64+
65+
Use [ScheduleDeviceMethodAsync](/dotnet/api/microsoft.azure.devices.jobclient.scheduledevicemethodasync) to create a new device method to run a device method on one or multiple devices.
66+
67+
This example schedules a device method call job for a specific job Id.
68+
69+
```csharp
70+
string methodJobId = Guid.NewGuid().ToString();
71+
static string deviceId = "Device-1";
72+
73+
CloudToDeviceMethod directMethod =
74+
new CloudToDeviceMethod("LockDoor", TimeSpan.FromSeconds(5),
75+
TimeSpan.FromSeconds(5));
76+
77+
JobResponse result = await jobClient.ScheduleDeviceMethodAsync(methodJobId,
78+
$"DeviceId IN ['{deviceId}']",
79+
directMethod,
80+
DateTime.UtcNow,
81+
(long)TimeSpan.FromMinutes(2).TotalSeconds);
82+
83+
Console.WriteLine("Started Method Job");
84+
```
85+
86+
### Schedule a device twin update job
87+
88+
Use [ScheduleTwinUpdateAsync](/dotnet/api/microsoft.azure.devices.jobclient.scheduledevicemethodasync) to create a new device twin update job to run a device twin update on one or multiple devices.
89+
90+
This example schedules a device twin update job for a specific job Id.
91+
92+
```csharp
93+
string twinJobId = Guid.NewGuid().ToString();
94+
static string deviceId = "Device-1";
95+
96+
Twin twin = new Twin(deviceId);
97+
twin.Tags = new TwinCollection();
98+
twin.Tags["Building"] = "43";
99+
twin.Tags["Floor"] = "3";
100+
twin.ETag = "*";
101+
102+
twin.Properties.Desired["LocationUpdate"] = DateTime.UtcNow;
103+
104+
JobResponse createJobResponse = jobClient.ScheduleTwinUpdateAsync(
105+
twinJobId,
106+
$"DeviceId IN ['{deviceId}']",
107+
twin,
108+
DateTime.UtcNow,
109+
(long)TimeSpan.FromMinutes(2).TotalSeconds).Result;
110+
111+
Console.WriteLine("Started Twin Update Job");
112+
```
113+
114+
### Monitor a job
115+
116+
Use [GetJobAsync](/dotnet/api/microsoft.azure.devices.jobclient.getjobasync?#microsoft-azure-devices-jobclient-getjobasync(system-string)) to monitor a job status.
117+
118+
This example checks the job status for a specific job Id periodically until the job has completed or failed.
119+
120+
```csharp
121+
JobResponse result;
122+
do
123+
{
124+
result = await jobClient.GetJobAsync(jobId);
125+
Console.WriteLine("Job Status : " + result.Status.ToString());
126+
Thread.Sleep(2000);
127+
} while ((result.Status != JobStatus.Completed) && (result.Status != JobStatus.Failed));
128+
```
129+
130+
### SDK schedule job examples
131+
132+
The Azure IoT SDK for .NET provides working samples of service apps that handles job scheduling tasks. For more information, see:
133+
134+
* [Schedule twin update sample](https://github.com/Azure/azure-iot-sdk-csharp/blob/main/iothub/service/samples/getting%20started/JobsSample/JobsSample.cs)
135+
* [E2E schedule twin update sample](https://github.com/Azure/azure-iot-sdk-csharp/blob/86065001a92fedb42877722c6a57ae37e45eed30/e2e/test/iothub/service/IoTHubCertificateValidationE2ETest.cs#L69)

‎includes/iot-hub-howto-schedule-broadcast-jobs-java.md

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
---
2+
title: Schedule and broadcast jobs (Java)
3+
titleSuffix: Azure IoT Hub
4+
description: How to use the Azure IoT SDK for Java to create backend service application code for job scheduling.
5+
author: kgremban
6+
ms.author: kgremban
7+
ms.service: azure-iot-hub
8+
ms.devlang: java
9+
ms.topic: include
10+
ms.date: 1/7/2025
11+
ms.custom: mqtt, devx-track-java, devx-track-extended-java
12+
---
13+
14+
* Requires [Java SE Development Kit 8](/azure/developer/java/fundamentals/). Make sure you select **Java 8** under **Long-term support** to navigate to downloads for JDK 8.
15+
16+
## Overview
17+
18+
This article describes how to use the [Azure IoT SDK for Java](https://github.com/Azure/azure-iot-sdk-java) to create backend service application code for job scheduling.
19+
20+
The [JobClient](/java/api/com.microsoft.azure.sdk.iot.service.jobs.jobclient) class contains methods that services can use to schedule jobs.
21+
22+
### Service import statements
23+
24+
Use the following service import statements to access the Azure IoT SDK for Java.
25+
26+
```java
27+
import com.microsoft.azure.sdk.iot.service.devicetwin.DeviceTwinDevice;
28+
import com.microsoft.azure.sdk.iot.service.devicetwin.Pair;
29+
import com.microsoft.azure.sdk.iot.service.devicetwin.Query;
30+
import com.microsoft.azure.sdk.iot.service.devicetwin.SqlQuery;
31+
import com.microsoft.azure.sdk.iot.service.jobs.JobClient;
32+
import com.microsoft.azure.sdk.iot.service.jobs.JobResult;
33+
import com.microsoft.azure.sdk.iot.service.jobs.JobStatus;
34+
35+
import java.util.Date;
36+
import java.time.Instant;
37+
import java.util.HashSet;
38+
import java.util.Set;
39+
import java.util.UUID;
40+
```
41+
42+
### Connect to the IoT Hub
43+
44+
You can connect a backend service to IoT Hub using the following methods:
45+
46+
* Shared access policy
47+
* Microsoft Entra
48+
49+
[!INCLUDE [iot-authentication-service-connection-string.md](iot-authentication-service-connection-string.md)]
50+
51+
#### Connect using a shared access policy
52+
53+
Use a [JobClient](/java/api/com.microsoft.azure.sdk.iot.service.jobs.jobclient) constructor to create the connection to IoT hub. The `JobClient` object handles the communication with your IoT hub.
54+
55+
In this article, you create a back-end service that schedules a job to invoke a direct method on a device, schedules a job to update the device twin, and monitors the progress of each job. To perform these operations, your service needs the **registry read** and **registry write permissions**. By default, every IoT hub is created with a shared access policy named **registryReadWrite** that grants these permissions.
56+
57+
For more information about shared access policies, see [Control access to IoT Hub with shared access signatures](/azure/iot-hub/authenticate-authorize-sas).
58+
59+
For example:
60+
61+
```java
62+
public static final String iotHubConnectionString = "{Shared access policy connection string}";
63+
public static final String deviceId = "myDeviceId";
64+
65+
JobClient jobClient = new JobClient(iotHubConnectionString);
66+
```
67+
68+
#### Connect using Microsoft Entra
69+
70+
[!INCLUDE [iot-hub-howto-connect-service-iothub-entra-java](iot-hub-howto-connect-service-iothub-entra-java.md)]
71+
72+
### Create a device method update job
73+
74+
Use [scheduleDeviceMethod](/java/api/com.microsoft.azure.sdk.iot.service.jobs.jobclient?#com-microsoft-azure-sdk-iot-service-jobs-jobclient-scheduledevicemethod(java-lang-string-java-lang-string-java-lang-string-java-lang-long-java-lang-long-java-lang-object-java-util-date-long)) to to run a device method on one or multiple devices.
75+
76+
This example schedules a device method call job for a specific job Id.
77+
78+
```java
79+
private static JobResult scheduleJobCallDirectMethod(JobClient jobClient, String jobId) {
80+
// Schedule a job now to call the lockDoor direct method
81+
// against a single device. Response and connection
82+
// timeouts are set to 5 seconds.
83+
System.out.println("Schedule job " + jobId + " for device " + deviceId);
84+
try {
85+
JobResult jobResult = jobClient.scheduleDeviceMethod(jobId,
86+
"deviceId='" + deviceId + "'",
87+
"lockDoor",
88+
5L, 5L, null,
89+
new Date(),
90+
maxExecutionTimeInSeconds);
91+
return jobResult;
92+
} catch (Exception e) {
93+
System.out.println("Exception scheduling direct method job: " + jobId);
94+
System.out.println(e.getMessage());
95+
return null;
96+
}
97+
};
98+
```
99+
100+
### Schedule a device twin update job
101+
102+
Use [scheduleUpdateTwin](/java/api/com.microsoft.azure.sdk.iot.service.jobs.jobclient?#com-microsoft-azure-sdk-iot-service-jobs-jobclient-scheduleupdatetwin(java-lang-string-java-lang-string-com-microsoft-azure-sdk-iot-service-devicetwin-devicetwindevice-java-util-date-long)) to create a new job to run a device twin update on one or multiple devices.
103+
104+
This example schedules a device twin update job for a specific job Id.
105+
106+
```java
107+
private static JobResult scheduleJobSetDesiredProperties(JobClient jobClient, String jobId) {
108+
DeviceTwinDevice twin = new DeviceTwinDevice(deviceId);
109+
Set<Pair> desiredProperties = new HashSet<Pair>();
110+
desiredProperties.add(new Pair("Building", 43));
111+
desiredProperties.add(new Pair("Floor", 3));
112+
twin.setDesiredProperties(desiredProperties);
113+
// Optimistic concurrency control
114+
twin.setETag("*");
115+
116+
// Schedule the update twin job to run now
117+
// against a single device
118+
System.out.println("Schedule job " + jobId + " for device " + deviceId);
119+
try {
120+
JobResult jobResult = jobClient.scheduleUpdateTwin(jobId,
121+
"deviceId='" + deviceId + "'",
122+
twin,
123+
new Date(),
124+
maxExecutionTimeInSeconds);
125+
return jobResult;
126+
} catch (Exception e) {
127+
System.out.println("Exception scheduling desired properties job: " + jobId);
128+
System.out.println(e.getMessage());
129+
return null;
130+
}
131+
}
132+
```
133+
134+
### Monitor a job
135+
136+
Use [getJob](/java/api/com.microsoft.azure.sdk.iot.service.jobs.jobclient?#com-microsoft-azure-sdk-iot-service-jobs-jobclient-getjob(java-lang-string)) to access job status.
137+
138+
```java
139+
private static void monitorJob(JobClient jobClient, String jobId) {
140+
try {
141+
JobResult jobResult = jobClient.getJob(jobId);
142+
if(jobResult == null)
143+
{
144+
System.out.println("No JobResult for: " + jobId);
145+
return;
146+
}
147+
// Check the job result until it's completed
148+
while(jobResult.getJobStatus() != JobStatus.completed)
149+
{
150+
Thread.sleep(100);
151+
jobResult = jobClient.getJob(jobId);
152+
System.out.println("Status " + jobResult.getJobStatus() + " for job " + jobId);
153+
}
154+
System.out.println("Final status " + jobResult.getJobStatus() + " for job " + jobId);
155+
} catch (Exception e) {
156+
System.out.println("Exception monitoring job: " + jobId);
157+
System.out.println(e.getMessage());
158+
return;
159+
}
160+
}
161+
```
162+
163+
### Query a job status
164+
165+
Use [queryDeviceJob](/java/api/com.microsoft.azure.sdk.iot.service.jobs.jobclient?#com-microsoft-azure-sdk-iot-service-jobs-jobclient-querydevicejob(java-lang-string)) to query job status.
166+
167+
```java
168+
private static void queryDeviceJobs(JobClient jobClient, String start) throws Exception {
169+
System.out.println("\nQuery device jobs since " + start);
170+
171+
// Create a jobs query using the time the jobs started
172+
Query deviceJobQuery = jobClient
173+
.queryDeviceJob(SqlQuery.createSqlQuery("*", SqlQuery.FromType.JOBS, "devices.jobs.startTimeUtc > '" + start + "'", null).getQuery());
174+
175+
// Iterate over the list of jobs and print the details
176+
while (jobClient.hasNextJob(deviceJobQuery)) {
177+
System.out.println(jobClient.getNextJob(deviceJobQuery));
178+
}
179+
}
180+
```
181+
182+
### SDK schedule job example
183+
184+
The Azure IoT SDK for Java provides a working sample of a service app that handles job scheduling tasks. For more information, see [Job Client Sample](https://github.com/Azure/azure-iot-service-sdk-java/blob/main/service/iot-service-samples/job-client-sample/src/main/java/samples/com/microsoft/azure/sdk/iot/JobClientSample.java)

0 commit comments

Comments
 (0)