Taken plannen en uitzenden

• Requires Visual Studio

Overzicht

In dit artikel wordt beschreven hoe u de Azure IoT SDK voor .NET gebruikt om code voor de back-endservicetoepassing te maken voor een planningstaak om een directe methode aan te roepen of een apparaatdubbelupdate uit te voeren op een of meer apparaten.

NuGet-servicepakket toevoegen

Voor back-endservicetoepassingen is het NuGet-pakket Microsoft.Azure.Devices vereist.

Using statements

Add the following using statements.

using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Shared;

using System.Threading;
using System.Threading.Tasks;

Verbinding maken met IoT Hub

U kunt een back-endservice verbinden met IoT Hub met behulp van de volgende methoden:

• Beleid voor gedeelde toegang
• Microsoft Entra

Verbinding maken met behulp van een beleid voor gedeelde toegang

Een back-endtoepassing verbinden met een apparaat met createFromConnectionString.

In dit artikel wordt back-endcode beschreven die een taak kan inplannen om een directe methode aan te roepen, een taak in te plannen om een apparaat-tweeling bij te werken en de voortgang van een taak voor een of meer apparaten bewaakt. Om deze bewerkingen uit te voeren, heeft uw service de lees- en schrijfmachtigingen voor het register nodig. Standaard wordt elke IoT-hub gemaakt met een gedeeld toegangsbeleid met de naam registryReadWrite dat deze machtigingen verleent.

Zie Toegang tot IoT Hub beheren met handtekeningen voor gedeelde toegang voor meer informatie over beleid voor gedeelde toegang.

static JobClient jobClient;
static string connectionString = "{Shared access policy connection string}";
jobClient = JobClient.CreateFromConnectionString(connString);

Verbinding maken met Microsoft Entra

Een back-end-app die gebruikmaakt van Microsoft Entra, moet een beveiligingstokenreferentie verifiëren en verkrijgen voordat u verbinding maakt met IoT Hub. Dit token wordt doorgegeven aan een IoT Hub-verbindingsmethode. Zie Toegang tot IoT Hub beheren met behulp van Microsoft Entra ID voor algemene informatie over het instellen en gebruiken van Microsoft Entra voor IoT Hub.

Microsoft Entra-app configureren

U moet een Microsoft Entra-app instellen die is geconfigureerd voor uw voorkeursverificatiereferenties. De app bevat parameters zoals het clientgeheim dat door de back-endtoepassing wordt gebruikt om te verifiëren. De beschikbare configuraties voor app-verificatie zijn:

• Clientgeheim
• Certificaat
• Federated identity credential

Voor Microsoft Entra-apps zijn mogelijk specifieke rolmachtigingen vereist, afhankelijk van bewerkingen die worden uitgevoerd. For example, IoT Hub Twin Contributor is required to enable read and write access to a IoT Hub device and module twins. Zie Toegang tot IoT Hub beheren met behulp van Azure RBAC-roltoewijzing voor meer informatie.

Zie quickstart: Een toepassing registreren bij het Microsoft Identity Platform voor meer informatie over het instellen van een Microsoft Entra-app.

Verifiëren met DefaultAzureCredential

The easiest way to use Microsoft Entra to authenticate a backend application is to use DefaultAzureCredential, but it's recommended to use a different method in a production environment including a specific TokenCredential or pared-down ChainedTokenCredential. Ter vereenvoudiging beschrijft deze sectie verificatie met behulp van DefaultAzureCredential en clientgeheim. Zie Gebruiksrichtlijnen voor DefaultAzureCredential voor meer informatie over de voor- en nadelen van het gebruik.DefaultAzureCredential

DefaultAzureCredential ondersteunt verschillende verificatiemechanismen en bepaalt het juiste referentietype op basis van de omgeving waarin het wordt uitgevoerd. Er wordt geprobeerd om meerdere referentietypen in een volgorde te gebruiken totdat er een werkende referentie wordt gevonden.

Microsoft Entra vereist deze NuGet-pakketten en bijbehorende using instructies:

• Azure.Core
• Azure.Identity

using Azure.Core;
using Azure.Identity;

In dit voorbeeld worden clientgeheim, client-id en tenant-id van Microsoft Entra-app-registratie toegevoegd aan omgevingsvariabelen. Deze omgevingsvariabelen worden gebruikt om DefaultAzureCredential de toepassing te verifiëren. Het resultaat van een geslaagde Microsoft Entra-verificatie is een beveiligingstokenreferentie die wordt doorgegeven aan een IoT Hub-verbindingsmethode.

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

De resulterende TokenCredential kan vervolgens worden doorgegeven aan een verbinding met de IoT Hub-methode voor elke SDK-client die Microsoft Entra-referenties accepteert:

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

In dit voorbeeld wordt de TokenCredential doorgegeven aan ServiceClient.Create om een ServiceClient-verbindingsobject te maken.

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

In dit voorbeeld wordt het TokenCredential aan RegistryManager.Create doorgegeven om een RegistryManager object te maken.

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);

Voorbeeld van code

Zie Het voorbeeld van verificatie op basis van rollen voor een werkende voorbeeld van Microsoft Entra-serviceverificatie.

Schedule a direct method job

Gebruik ScheduleDeviceMethodAsync om een taak te plannen om een directe methode uit te voeren op een of meer apparaten.

Gebruik het object CloudToDeviceMethod om de naam van de directe methode en time-outwaarden voor apparaatverbindingen op te geven.

Voorbeeld:

// The CloudToDeviceMethod record specifies the direct method name and device connection time-out
CloudToDeviceMethod directMethod = 
new CloudToDeviceMethod("LockDoor", TimeSpan.FromSeconds(5), 
TimeSpan.FromSeconds(5));

In dit voorbeeld wordt een taak gepland voor een directe methode met de naam 'LockDoor' op één apparaat met de naam 'Device-1'. De apparaten die zijn opgenomen in de geplande taak, bevatten de tweede parameter als een queryvoorwaarde. Zie ioT Hub-querytaal voor apparaat- en moduledubbels, taken en berichtroutering voor meer informatie over queryvoorwaarden.

string methodJobId = Guid.NewGuid().ToString();  // a unique job ID
static string deviceId = "Device-1";             // In this example, there is only one device affected
JobResponse result = await jobClient.ScheduleDeviceMethodAsync(methodJobId,
   $"DeviceId IN ['{deviceId}']",
   directMethod,
   DateTime.UtcNow,
   (long)TimeSpan.FromMinutes(2).TotalSeconds);

Schedule a device twin update job

Use ScheduleTwinUpdateAsync to schedule a new device twin desired properties and tags update job to run on one or more devices.

First, create and populate a device Twin object for the update. Voorbeeld:

static string deviceId = "Device-1";

Twin twin = new Twin(deviceId);
twin.Tags = new TwinCollection();
twin.Tags["Building"] = "43";
twin.Tags["Floor"] = "3";
twin.ETag = "*";
twin.Properties.Desired["LocationUpdate"] = DateTime.UtcNow;

Next, call ScheduleTwinUpdateAsync. Geef de apparaten op die moeten worden bijgewerkt als een query in de tweede parameter. Zie ioT Hub-querytaal voor apparaat- en moduledubbels, taken en berichtroutering voor meer informatie over queryvoorwaarden.

string twinJobId = Guid.NewGuid().ToString();

JobResponse createJobResponse = jobClient.ScheduleTwinUpdateAsync(
   twinJobId,
   $"DeviceId IN ['{deviceId}']", 
   twin, 
   DateTime.UtcNow, 
   (long)TimeSpan.FromMinutes(2).TotalSeconds).Result;

Een taak bewaken

Gebruik GetJobAsync om de taakstatus voor een specifieke taak-id te controleren.

In dit voorbeeld wordt de taakstatus van een taak-id periodiek gecontroleerd totdat de taakstatus is voltooid of mislukt. Voorbeeld:

JobResponse result;
do
{
   result = await jobClient.GetJobAsync(jobId);
   Console.WriteLine("Job Status : " + result.Status.ToString());
   Thread.Sleep(2000);
} while ((result.Status != JobStatus.Completed) && (result.Status != JobStatus.Failed));

Voorbeelden van geplande SDK-taken

De Azure IoT SDK voor .NET biedt werkende voorbeelden van service-apps die taakplanningstaken verwerken. Zie voor meer informatie:

• Schedule twin update sample
• E2E schedule twin update sample.

• Requires Java SE Development Kit 8. Zorg ervoor dat u Java 8 selecteert onder Langetermijnondersteuning om naar downloads voor JDK 8 te gaan.

Overzicht

In dit artikel wordt beschreven hoe u de Azure IoT SDK voor Java gebruikt om code voor de back-endservicetoepassing te maken om een taak te plannen om een directe methode aan te roepen of een apparaatdubbelupdate uit te voeren op een of meer apparaten.

Service import statements

De JobClient-klasse bevat methoden die services kunnen gebruiken om taken te plannen.

Gebruik de volgende importinstructies voor services voor toegang tot de Azure IoT SDK voor Java.

import com.microsoft.azure.sdk.iot.service.devicetwin.DeviceTwinDevice;
import com.microsoft.azure.sdk.iot.service.devicetwin.Pair;
import com.microsoft.azure.sdk.iot.service.devicetwin.Query;
import com.microsoft.azure.sdk.iot.service.devicetwin.SqlQuery;
import com.microsoft.azure.sdk.iot.service.jobs.JobClient;
import com.microsoft.azure.sdk.iot.service.jobs.JobResult;
import com.microsoft.azure.sdk.iot.service.jobs.JobStatus;

import java.util.Date;
import java.time.Instant;
import java.util.HashSet;
import java.util.Set;
import java.util.UUID;

Verbinding maken met de IoT Hub

U kunt een back-endservice verbinden met IoT Hub met behulp van de volgende methoden:

• Beleid voor gedeelde toegang
• Microsoft Entra

Verbinding maken met behulp van een beleid voor gedeelde toegang

Gebruik een JobClient-constructor om de verbinding met IoT Hub te maken. Het JobClient object verwerkt de communicatie met uw IoT-hub.

In dit artikel wordt back-endcode beschreven die een taak kan inplannen om een directe methode aan te roepen, een taak in te plannen om een apparaat-tweeling bij te werken en de voortgang van een taak voor een of meer apparaten bewaakt. Om deze bewerkingen uit te voeren, heeft uw service de lees- en schrijfmachtigingen voor het register nodig. Standaard wordt elke IoT-hub gemaakt met een gedeeld toegangsbeleid met de naam registryReadWrite dat deze machtigingen verleent.

Zie Toegang tot IoT Hub beheren met handtekeningen voor gedeelde toegang voor meer informatie over beleid voor gedeelde toegang.

Voorbeeld:

public static final String iotHubConnectionString = "{Shared access policy connection string}";
JobClient jobClient = new JobClient(iotHubConnectionString);

Verbinding maken met Microsoft Entra

Een back-end-app die gebruikmaakt van Microsoft Entra, moet een beveiligingstokenreferentie verifiëren en verkrijgen voordat u verbinding maakt met IoT Hub. Dit token wordt doorgegeven aan een IoT Hub-verbindingsmethode. Zie Toegang tot IoT Hub beheren met behulp van Microsoft Entra ID voor algemene informatie over het instellen en gebruiken van Microsoft Entra voor IoT Hub.

Zie Azure-verificatie met Java en Azure Identity voor een overzicht van Java SDK-verificatie.

Ter vereenvoudiging richt deze sectie zich op het beschrijven van verificatie met behulp van clientgeheim.

Microsoft Entra-app configureren

U moet een Microsoft Entra-app instellen die is geconfigureerd voor uw voorkeursverificatiereferenties. De app bevat parameters zoals het clientgeheim dat door de back-endtoepassing wordt gebruikt om te verifiëren. De beschikbare configuraties voor app-verificatie zijn:

• Clientgeheim
• Certificaat
• Federated identity credential

Voor Microsoft Entra-apps zijn mogelijk specifieke rolmachtigingen vereist, afhankelijk van bewerkingen die worden uitgevoerd. For example, IoT Hub Twin Contributor is required to enable read and write access to a IoT Hub device and module twins. Zie Toegang tot IoT Hub beheren met behulp van Azure RBAC-roltoewijzing voor meer informatie.

Zie quickstart: Een toepassing registreren bij het Microsoft Identity Platform voor meer informatie over het instellen van een Microsoft Entra-app.

Verifiëren met DefaultAzureCredential

The easiest way to use Microsoft Entra to authenticate a backend application is to use DefaultAzureCredential, but it's recommended to use a different method in a production environment including a specific TokenCredential or pared-down ChainedTokenCredential. Zie Referentieketens in de Azure Identity-clientbibliotheek voor Java voor meer informatie over de voor- en nadelen van het gebruik.DefaultAzureCredential

DefaultAzureCredential ondersteunt verschillende verificatiemechanismen en bepaalt het juiste referentietype op basis van de omgeving waarin het wordt uitgevoerd. Er wordt geprobeerd om meerdere referentietypen in een volgorde te gebruiken totdat er een werkende referentie wordt gevonden.

U kunt microsoft Entra-app-referenties verifiëren met behulp van DefaultAzureCredentialBuilder. Sla verbindingsparameters zoals tenantID, client-id en clientgeheimwaarden op als omgevingsvariabelen. Once the TokenCredential is created, pass it to ServiceClient or other builder as the 'credential' parameter.

In dit voorbeeld DefaultAzureCredentialBuilder wordt geprobeerd een verbinding te verifiëren vanuit de lijst die wordt beschreven in DefaultAzureCredential. Het resultaat van een geslaagde Microsoft Entra-verificatie is een beveiligingstokenreferentie die wordt doorgegeven aan een constructor zoals ServiceClient.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();

Verifiëren met ClientSecretCredentialBuilder

U kunt ClientSecretCredentialBuilder gebruiken om een referentie te maken met behulp van clientgeheiminformatie. Als dit lukt, retourneert deze methode een TokenCredential die kan worden doorgegeven aan ServiceClient of een andere builder als de 'credential' parameter.

In dit voorbeeld zijn clientgeheim, client-id en tenant-id van Microsoft Entra-app-registratie toegevoegd aan omgevingsvariabelen. Deze omgevingsvariabelen worden door ClientSecretCredentialBuilder gebruikt om de referentie te maken.

string clientSecretValue = System.getenv("AZURE_CLIENT_SECRET");
string clientID = System.getenv("AZURE_CLIENT_ID");
string tenantID = System.getenv("AZURE_TENANT_ID");

TokenCredential credential =
     new ClientSecretCredentialBuilder()
          .tenantId(tenantID)
          .clientId(clientID)
          .clientSecret(clientSecretValue)
          .build();

Andere verificatieklassen

De Java SDK bevat ook deze klassen die een back-end-app verifiëren met Microsoft Entra:

• AuthorizationCodeCredential
• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePipelinesCredential
• ChainedTokenCredential
• ClientAssertionCredential
• ClientCertificateCredential
• DeviceCodeCredential
• EnvironmentCredential
• InteractiveBrowserCredential
• ManagedIdentityCredential
• OnBehalfOfCredential

Codevoorbeelden

Zie het voorbeeld van verificatie op basis van rollen voor werkvoorbeelden van de Microsoft Entra-service.

Schedule a direct method update job

Gebruik scheduleDeviceMethod om een directe methode uit te voeren op een of meer apparaten.

Met deze voorbeeldmethode wordt een taak gepland voor een directe methode met de naam 'lockDoor' op een apparaat met de naam 'Device-1'.

// Schedule a job now to call the lockDoor direct method
// against a single device. Response and connection
// timeouts are set to 5 seconds.
String deviceId = "Device-1";
String jobId = "DMCMD" + UUID.randomUUID();  //Job ID must be unique

// How long the job is permitted to run without
// completing its work on the set of devices
private static final long maxExecutionTimeInSeconds = 30;

System.out.println("Schedule job " + jobId + " for device " + deviceId);
try {
  JobResult jobResult = jobClient.scheduleDeviceMethod(jobId,
    "deviceId='" + deviceId + "'",
    "lockDoor",
    5L, 5L, null,
    new Date(),
    maxExecutionTimeInSeconds);
} catch (Exception e) {
  System.out.println("Exception scheduling direct method job: " + jobId);
  System.out.println(e.getMessage());
}

Schedule a device twin update job

Use scheduleUpdateTwin to schedule a job to run a device twin update on one or multiple devices.

First, prepare a DeviceTwinDevice record for the device twin update. Voorbeeld:

String deviceId = "Device-1";

//Create a device twin desired properties update object
DeviceTwinDevice twin = new DeviceTwinDevice(deviceId);
Set<Pair> desiredProperties = new HashSet<Pair>();
desiredProperties.add(new Pair("Building", 43));
desiredProperties.add(new Pair("Floor", 3));
twin.setDesiredProperties(desiredProperties);
// Optimistic concurrency control
twin.setETag("*");

scheduleUpdateTwin Roep vervolgens aan om de updatetaak te plannen. Voorbeeld:

String jobId = "DPCMD" + UUID.randomUUID();  //Unique job ID

// How long the job is permitted to run without
// completing its work on the set of devices
private static final long maxExecutionTimeInSeconds = 30;

// Schedule the update twin job to run now for a single device
System.out.println("Schedule job " + jobId + " for device " + deviceId);
try {
  JobResult jobResult = jobClient.scheduleUpdateTwin(jobId, 
    "deviceId='" + deviceId + "'",
    twin,
    new Date(),
    maxExecutionTimeInSeconds);
} catch (Exception e) {
  System.out.println("Exception scheduling desired properties job: " + jobId);
  System.out.println(e.getMessage());
}

Een taak bewaken

Gebruik getJob om taakgegevens op te halen op basis van een specifieke taak-id. getJob retourneert een JobResult-object dat methoden en eigenschappen bevat die u kunt gebruiken om taakgegevens te controleren, inclusief de actieve status.

Voorbeeld:

try {
  JobResult jobResult = jobClient.getJob(jobId);
  if(jobResult == null)
  {
    System.out.println("No JobResult for: " + jobId);
    return;
  }
  // Check the job result until it's completed
  while(jobResult.getJobStatus() != JobStatus.completed)
  {
    Thread.sleep(100);
    jobResult = jobClient.getJob(jobId);
    System.out.println("Status " + jobResult.getJobStatus() + " for job " + jobId);
  }
  System.out.println("Final status " + jobResult.getJobStatus() + " for job " + jobId);
} catch (Exception e) {
  System.out.println("Exception monitoring job: " + jobId);
  System.out.println(e.getMessage());
  return;
}

Een query uitvoeren op een taakstatus

Gebruik queryDeviceJob om een query uit te voeren op de taakstatus voor een of meer taken.

Voorbeeld:

private static void queryDeviceJobs(JobClient jobClient, String start) throws Exception {
  System.out.println("\nQuery device jobs since " + start);

  // Create a jobs query using the time the jobs started
  Query deviceJobQuery = jobClient
      .queryDeviceJob(SqlQuery.createSqlQuery("*", SqlQuery.FromType.JOBS, "devices.jobs.startTimeUtc > '" + start + "'", null).getQuery());

  // Iterate over the list of jobs and print the details
  while (jobClient.hasNextJob(deviceJobQuery)) {
    System.out.println(jobClient.getNextJob(deviceJobQuery));
  }
}

Voorbeeld van een SDK-planningstaak

De Azure IoT SDK voor Java biedt een werkend voorbeeld van een service-app waarmee taakplanningstaken worden verwerkt. Zie Job Client Sample voor meer informatie.

• Python SDK : Python-versie 3.7 of hoger wordt aanbevolen. Zorg ervoor dat u de 32-bits of 64-bits installatie gebruikt, zoals vereist door uw configuratie. Zorg ervoor dat u Python toevoegt aan uw platformspecifieke omgevingsvariabele als u hierom wordt gevraagd tijdens de installatie.

Overzicht

In dit artikel wordt beschreven hoe u de Azure IoT SDK voor Python gebruikt om code voor de back-endservicetoepassing te maken om een taak te plannen om een directe methode aan te roepen of een gewenste eigenschapsupdate voor een apparaatdubbel uit te voeren op een of meer apparaten.

Pakket installeren

De azure-iot-hub-bibliotheek moet zijn geïnstalleerd om back-endservicetoepassingen te maken.

pip install azure-iot-hub

Importverklaringen

De IoTHubJobManager-klasse bevat alle methoden die nodig zijn om een back-endtoepassing te maken om taken van de service te plannen.

Add the following import statements.

import os
import sys
import datetime
import time
import threading
import uuid
import msrest

from azure.iot.hub import IoTHubJobManager
from azure.iot.hub.models import JobProperties, JobRequest, Twin, TwinProperties, CloudToDeviceMethod

Verbinding maken met IoT Hub

U kunt een back-endservice verbinden met IoT Hub met behulp van de volgende methoden:

• Beleid voor gedeelde toegang
• Microsoft Entra

Verbinding maken met behulp van een beleid voor gedeelde toegang

Maak verbinding met IoT Hub met behulp van from_connection_string.

In dit artikel wordt back-endcode beschreven die een taak kan inplannen om een directe methode aan te roepen, een taak in te plannen om een apparaat-tweeling bij te werken en de voortgang van een taak voor een of meer apparaten bewaakt. Om deze bewerkingen uit te voeren, heeft uw service de lees- en schrijfmachtigingen voor het register nodig. Standaard wordt elke IoT-hub gemaakt met een gedeeld toegangsbeleid met de naam registryReadWrite dat deze machtigingen verleent.

Zie Toegang tot IoT Hub beheren met handtekeningen voor gedeelde toegang voor meer informatie over beleid voor gedeelde toegang.

Voorbeeld:

IoTHubConnectionString = "{Shared access policy connection string}"
iothub_job_manager = IoTHubJobManager.from_connection_string(IoTHubConnectionString)

Verbinding maken met Microsoft Entra

Een back-end-app die gebruikmaakt van Microsoft Entra, moet een beveiligingstokenreferentie verifiëren en verkrijgen voordat u verbinding maakt met IoT Hub. Dit token wordt doorgegeven aan een IoT Hub-verbindingsmethode. Zie Toegang tot IoT Hub beheren met behulp van Microsoft Entra ID voor algemene informatie over het instellen en gebruiken van Microsoft Entra voor IoT Hub.

Microsoft Entra-app configureren

U moet een Microsoft Entra-app instellen die is geconfigureerd voor uw voorkeursverificatiereferenties. De app bevat parameters zoals het clientgeheim dat door de back-endtoepassing wordt gebruikt om te verifiëren. De beschikbare configuraties voor app-verificatie zijn:

• Clientgeheim
• Certificaat
• Federated identity credential

Voor Microsoft Entra-apps zijn mogelijk specifieke rolmachtigingen vereist, afhankelijk van bewerkingen die worden uitgevoerd. For example, IoT Hub Twin Contributor is required to enable read and write access to a IoT Hub device and module twins. Zie Toegang tot IoT Hub beheren met behulp van Azure RBAC-roltoewijzing voor meer informatie.

Zie quickstart: Een toepassing registreren bij het Microsoft Identity Platform voor meer informatie over het instellen van een Microsoft Entra-app.

Verifiëren met DefaultAzureCredential

The easiest way to use Microsoft Entra to authenticate a backend application is to use DefaultAzureCredential, but it's recommended to use a different method in a production environment including a specific TokenCredential or pared-down ChainedTokenCredential. Ter vereenvoudiging beschrijft deze sectie verificatie met behulp van DefaultAzureCredential en clientgeheim. Zie Gebruiksrichtlijnen voor DefaultAzureCredential voor meer informatie over de voor- en nadelen van het gebruik.DefaultAzureCredential

DefaultAzureCredential ondersteunt verschillende verificatiemechanismen en bepaalt het juiste referentietype op basis van de omgeving waarin het wordt uitgevoerd. Er wordt geprobeerd om meerdere referentietypen in een volgorde te gebruiken totdat er een werkende referentie wordt gevonden.

Microsoft Entra vereist deze NuGet-pakketten en bijbehorende using instructies:

• Azure.Core
• Azure.Identity

using Azure.Core;
using Azure.Identity;

In dit voorbeeld worden clientgeheim, client-id en tenant-id van Microsoft Entra-app-registratie toegevoegd aan omgevingsvariabelen. Deze omgevingsvariabelen worden gebruikt om DefaultAzureCredential de toepassing te verifiëren. Het resultaat van een geslaagde Microsoft Entra-verificatie is een beveiligingstokenreferentie die wordt doorgegeven aan een IoT Hub-verbindingsmethode.

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

De resulterende TokenCredential kan vervolgens worden doorgegeven aan een verbinding met de IoT Hub-methode voor elke SDK-client die Microsoft Entra-referenties accepteert:

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

In dit voorbeeld wordt de TokenCredential doorgegeven aan ServiceClient.Create om een ServiceClient-verbindingsobject te maken.

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

In dit voorbeeld wordt het TokenCredential aan RegistryManager.Create doorgegeven om een RegistryManager object te maken.

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);

Voorbeeld van code

Zie Het voorbeeld van verificatie op basis van rollen voor een werkende voorbeeld van Microsoft Entra-serviceverificatie.

Schedule a direct method job

Gebruik create_scheduled_job om een nieuwe directe methode te plannen om een directe methode uit te voeren op een of meer apparaten:

create_scheduled_job parameter notes:

• job_id moet uniek zijn
• Stel type in op scheduleDeviceMethod
• Gebruik cloud_to_device_method om de naam en payload van de directe methode in te stellen
• Gebruiken max_execution_time_in_seconds om de uitvoeringstijd in seconden op te geven
• Use query_condition to specify the devices to be included for the direct method call. Zie ioT Hub-querytaal voor apparaat- en moduledubbels, taken en berichtroutering voor meer informatie over queryvoorwaarden.

Voorbeeld:

METHOD_NAME = "lockDoor"
METHOD_PAYLOAD = "{\"lockTime\":\"10m\"}"
job_id = uuid.uuid4()
DEVICE_ID = "Device-1"
TIMEOUT = 60

job_request = JobRequest()
job_request.job_id = job_id
job_request.type = "scheduleDeviceMethod"
job_request.start_time = datetime.datetime.utcnow().isoformat()
job_request.cloud_to_device_method = CloudToDeviceMethod(method_name=METHOD_NAME, payload=METHOD_PAYLOAD)
job_request.max_execution_time_in_seconds = TIMEOUT
job_request.query_condition = "DeviceId in ['{}']".format(device_id)

new_job_response = iothub_job_manager.create_scheduled_job(job_id, job_request)

Schedule a device twin update job

Use create_scheduled_job to create a new job to run a device twin desired properties update on one or multiple devices.

create_scheduled_job parameter notes:

• job_id moet uniek zijn
• Stel type in op scheduleUpdateTwin
• Gebruik update_twin om de naam en payload van de directe methode in te stellen
• Gebruiken max_execution_time_in_seconds om de uitvoeringstijd in seconden op te geven
• Use query_condition to specify a condition for one or more devices that have the direct method call. Zie ioT Hub-querytaal voor apparaat- en moduledubbels, taken en berichtroutering voor meer informatie over queryvoorwaarden.

Voorbeeld:

UPDATE_PATCH = {"building":43,"floor":3}
job_id = uuid.uuid4()
TIMEOUT = 60

job_request = JobRequest()
job_request.job_id = job_id
job_request.type = "scheduleUpdateTwin"
job_request.start_time = datetime.datetime.utcnow().isoformat()
job_request.update_twin = Twin(etag="*", properties=TwinProperties(desired=UPDATE_PATCH))
job_request.max_execution_time_in_seconds = TIMEOUT
job_request.query_condition = "DeviceId in ['{}']".format(device_id)

new_job_response = iothub_job_manager.create_scheduled_job(job_id, job_request)

Een taak bewaken

Gebruik get_scheduled_job om de details van een specifieke taak op een IoT Hub op te halen.

In dit voorbeeld wordt elke vijf seconden de taakstatus gecontroleerd op een specifieke taak-id totdat de taak is voltooid.

while True:
    get_job_response = iothub_job_manager.get_scheduled_job(job_request.job_id)
    print_job_response("Get job response: ", get_job_response)
    if get_job_response.status == "completed":
      print ( "Job is completed." )
    time.sleep(5)

Voorbeelden van geplande SDK-taken

De Azure IoT SDK voor Python biedt werkende voorbeelden van service-apps die taakplanningstaken verwerken. Zie voor meer informatie:

• Schedule a direct method job
• Schedule a device twin update.

• Vereist Node.js versie 10.0.x of hoger

Overzicht

In dit artikel wordt beschreven hoe u de Azure IoT SDK voor Node.js kunt gebruiken om code te schrijven voor een backendserviceapplicatie die een taak plant om een directe methode aan te roepen of een update van een apparaatstatus uit te voeren op een of meer apparaten.

Service SDK-pakket installeren

Voer deze opdracht uit om azure-iothub te installeren op uw ontwikkelcomputer:

npm install azure-iothub --save

De JobClient-klasse bevat alle methoden die nodig zijn om te communiceren met taakplanning vanuit een back-endtoepassing.

Verbinding maken met IoT Hub

U kunt een back-endservice verbinden met IoT Hub met behulp van de volgende methoden:

• Beleid voor gedeelde toegang
• Microsoft Entra

Verbinding maken met behulp van een beleid voor gedeelde toegang

Gebruik fromConnectionString om verbinding te maken met IoT Hub.

In dit artikel wordt back-endcode beschreven die een taak kan inplannen om een directe methode aan te roepen, een taak in te plannen om een apparaat-tweeling bij te werken en de voortgang van een taak voor een of meer apparaten bewaakt. Om deze bewerkingen uit te voeren, heeft uw service de lees- en schrijfmachtigingen voor het register nodig. Standaard wordt elke IoT-hub gemaakt met een gedeeld toegangsbeleid met de naam registryReadWrite dat deze machtigingen verleent.

Zie Toegang tot IoT Hub beheren met handtekeningen voor gedeelde toegang voor meer informatie over beleid voor gedeelde toegang.

Voorbeeld:

'use strict';
var JobClient = require('azure-iothub').JobClient;
var connectionString = '{Shared access policy connection string}';
var jobClient = JobClient.fromConnectionString(connectionString);

Verbinding maken met Microsoft Entra

Een back-end-app die gebruikmaakt van Microsoft Entra, moet een beveiligingstokenreferentie verifiëren en verkrijgen voordat u verbinding maakt met IoT Hub. Dit token wordt doorgegeven aan een IoT Hub-verbindingsmethode. Zie Toegang tot IoT Hub beheren met behulp van Microsoft Entra ID voor algemene informatie over het instellen en gebruiken van Microsoft Entra voor IoT Hub.

Zie voor een overzicht van Node.js SDK-verificatie:

• Aan de slag met gebruikersverificatie in Azure
• Azure Identity-clientbibliotheek voor JavaScript

Microsoft Entra-app configureren

U moet een Microsoft Entra-app instellen die is geconfigureerd voor uw voorkeursverificatiereferenties. De app bevat parameters zoals het clientgeheim dat door de back-endtoepassing wordt gebruikt om te verifiëren. De beschikbare configuraties voor app-verificatie zijn:

• Clientgeheim
• Certificaat
• Federated identity credential

Voor Microsoft Entra-apps zijn mogelijk specifieke rolmachtigingen vereist, afhankelijk van bewerkingen die worden uitgevoerd. For example, IoT Hub Twin Contributor is required to enable read and write access to a IoT Hub device and module twins. Zie Toegang tot IoT Hub beheren met behulp van Azure RBAC-roltoewijzing voor meer informatie.

Zie quickstart: Een toepassing registreren bij het Microsoft Identity Platform voor meer informatie over het instellen van een Microsoft Entra-app.

Verifiëren met DefaultAzureCredential

The easiest way to use Microsoft Entra to authenticate a backend application is to use DefaultAzureCredential, but it's recommended to use a different method in a production environment including a specific TokenCredential or pared-down ChainedTokenCredential. Ter vereenvoudiging beschrijft deze sectie verificatie met behulp van DefaultAzureCredential en clientgeheim. Zie Referentieketens in de Azure Identity-clientbibliotheek voor JavaScript voor meer informatie over de voor- en nadelen van het gebruik DefaultAzureCredential

DefaultAzureCredential ondersteunt verschillende verificatiemechanismen en bepaalt het juiste referentietype op basis van de omgeving waarin het wordt uitgevoerd. Er wordt geprobeerd om meerdere referentietypen in een volgorde te gebruiken totdat er een werkende referentie wordt gevonden.

Microsoft Entra vereist dit pakket:

npm install --save @azure/identity

In dit voorbeeld zijn clientgeheim, client-id en tenant-id van Microsoft Entra-app-registratie toegevoegd aan omgevingsvariabelen. Deze omgevingsvariabelen worden gebruikt om DefaultAzureCredential de toepassing te verifiëren. Het resultaat van een geslaagde Microsoft Entra-verificatie is een beveiligingstokenreferentie die wordt doorgegeven aan een IoT Hub-verbindingsmethode.

import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

Het resulterende referentietoken kan vervolgens worden doorgegeven aan fromTokenCredential om verbinding te maken met IoT Hub voor elke SDK-client die Microsoft Entra-referenties accepteert:

• Register
• Client
• JobClient

fromTokenCredential vereist twee parameters:

• De URL van de Azure-service: de Azure-service-URL moet de indeling {Your Entra domain URL}.azure-devices.net hebben zonder voorvoegsel https:// . Bijvoorbeeld: MyAzureDomain.azure-devices.net.
• Het Azure-referentietoken

In dit voorbeeld wordt de Azure-referentie verkregen met behulp van DefaultAzureCredential. The Azure domain URL and credential are then supplied to Registry.fromTokenCredential to create the connection to IoT Hub.

const { DefaultAzureCredential } = require("@azure/identity");

let Registry = require('azure-iothub').Registry;

// Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

// Set environment variables
process.env['AZURE_CLIENT_SECRET'] = clientSecretValue;
process.env['AZURE_CLIENT_ID'] = clientID;
process.env['AZURE_TENANT_ID'] = tenantID;

// Acquire a credential object
const credential = new DefaultAzureCredential()

// Create an instance of the IoTHub registry
hostName = 'MyAzureDomain.azure-devices.net';
let registry = Registry.fromTokenCredential(hostName,credential);

Codevoorbeelden

Zie Voorbeelden van Azure-identiteiten voor werkvoorbeelden van Microsoft Entra-serviceverificatie.

Een directe methodetaak maken

Gebruik scheduleDeviceMethod om een taak te plannen om een directe methode uit te voeren op een of meer apparaten.

First, create a direct method update variable with method name, payload, and response time-out information. Voorbeeld:

var methodParams = {
    methodName: 'lockDoor',
    payload: null,
    responseTimeoutInSeconds: 15 // Time-out after 15 seconds if device is unable to process method
};

Then call scheduleDeviceMethod to schedule the direct method call job:

• Elke taak moet een unieke taak-id hebben. U kunt deze taak-id gebruiken om een taak te bewaken, zoals beschreven in de sectie Een taak bewaken van dit artikel.
• Geef een queryCondition parameter op om te evalueren op welke apparaten de taak moet worden uitgevoerd. Zie ioT Hub-querytaal voor apparaat- en moduledubbels, taken en berichtroutering voor meer informatie over queryvoorwaarden.
• Check the jobResult callback for the job schedule result. Als de taak met succes is gepland, kunt u de taakstatus controleren zoals weergegeven in de sectie Bewaken van een taak van dit artikel.

Voorbeeld:

var methodJobId = uuid.v4();
var queryCondition = "deviceId IN ['myDeviceId']";
var startTime = new Date();
var maxExecutionTimeInSeconds =  300;

jobClient.scheduleDeviceMethod(methodJobId,
                            queryCondition,
                            methodParams,
                            startTime,
                            maxExecutionTimeInSeconds,
                            function(err) {
    if (err) {
        console.error('Could not schedule direct method job: ' + err.message);
    } else {
        monitorJob(methodJobId, function(err, result) {
            if (err) {
                console.error('Could not monitor direct method job: ' + err.message);
            } else {
                console.log(JSON.stringify(result, null, 2));
            }
        });
    }
});

Schedule a device twin update job

Use scheduleTwinUpdate to create a new job to run a device twin update on one or multiple devices.

First, create a device twin desired property update variable.

var twinPatch = {
   etag: '*',
   properties: {
       desired: {
           building: '43',
           floor: 3
       }
   }
};

Roep dan scheduleTwinUpdate aan om de gewenste eigenschapsupdate-taak van de device twin te plannen.

• Elke taak moet een unieke taak-id hebben. U kunt deze taak-id gebruiken om een taak te bewaken, zoals beschreven in de sectie Een taak bewaken van dit artikel.
• Geef een queryCondition parameter op om te evalueren op welke apparaten de taak moet worden uitgevoerd. Zie ioT Hub-querytaal voor apparaat- en moduledubbels, taken en berichtroutering voor meer informatie over queryvoorwaarden.
• Check the jobResult callback for the job schedule result. Als de taak met succes is gepland, kunt u de taakstatus controleren zoals weergegeven in de sectie Bewaken van een taak van dit artikel.

Voorbeeld:

var twinJobId = uuid.v4();
var queryCondition = "deviceId IN ['myDeviceId']";
var startTime = new Date();
var maxExecutionTimeInSeconds =  300;

console.log('scheduling Twin Update job with id: ' + twinJobId);
jobClient.scheduleTwinUpdate(twinJobId,
                            queryCondition,
                            twinPatch,
                            startTime,
                            maxExecutionTimeInSeconds,
                            function(err) {
    if (err) {
        console.error('Could not schedule twin update job: ' + err.message);
    } else {
        monitorJob(twinJobId, function(err, result) {
            if (err) {
                console.error('Could not monitor twin update job: ' + err.message);
            } else {
                console.log(JSON.stringify(result, null, 2));
            }
        });
    }
});

Een taak bewaken

Gebruik getJob om de taakstatus voor een specifieke taak-id te controleren.

Met deze voorbeeldfunctie wordt de taakstatus voor een specifieke taak-id periodiek gecontroleerd totdat de taak is voltooid of mislukt.

function monitorJob (jobId, callback) {
    var jobMonitorInterval = setInterval(function() {
        jobClient.getJob(jobId, function(err, result) {
        if (err) {
            console.error('Could not get job status: ' + err.message);
        } else {
            console.log('Job: ' + jobId + ' - status: ' + result.status);
            if (result.status === 'completed' || result.status === 'failed' || result.status === 'cancelled') {
            clearInterval(jobMonitorInterval);
            callback(null, result);
            }
        }
        });
    }, 5000);
}

Voorbeeld van een SDK-planningstaak

De Azure IoT SDK voor Node.js biedt een werkend voorbeeld van een service-app waarmee taakplanningstaken worden verwerkt. Zie De E2E-test van jobclient voor meer informatie.