Schemalägga och sända jobb

• Kräver Visual Studio

Översikt

Den här artikeln beskriver hur du använder Azure IoT SDK för .NET för att skapa backend-tjänstapplikationskod för ett schemalagt jobb för att anropa en direktmetod eller utföra en uppdatering av enhetstvilling på en eller flera enheter.

Lägg till tjänstens NuGet-paket

Serverdelstjänstprogram kräver NuGet-paketet Microsoft.Azure.Devices .

Använda instruktioner

Lägg till följande using-instruktioner.

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

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

Ansluta till IoT Hub

Du kan ansluta en serverdelstjänst till IoT Hub med hjälp av följande metoder:

• Princip för delad åtkomst
• Microsoft Entra

Anslut med en delad åtkomstpolicy

Anslut ett serverdelsprogram till en enhet med CreateFromConnectionString.

I den här artikeln beskrivs backend-kod som kan schemalägga ett jobb för att anropa en direktmetod, schemalägga ett jobb för att uppdatera en enhetstvilling och övervaka förloppet för ett jobb för en eller flera enheter. För att utföra dessa åtgärder behöver tjänsten behörigheterna för registerläsning och registerskrivning. Som standard skapas varje IoT-hubb med en princip för delad åtkomst med namnet registryReadWrite som ger dessa behörigheter.

Mer information om principer för delad åtkomst finns i Kontrollera åtkomst till IoT Hub med signaturer för delad åtkomst.

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

Ansluta med Microsoft Entra

En backend-app som använder Microsoft Entra måste framgångsrikt autentisera och hämta en säkerhetstokenuppgift innan den ansluter till IoT Hub. Den här token skickas till en IoT Hub-anslutningsmetod. Allmän information om hur du konfigurerar och använder Microsoft Entra för IoT Hub finns i Kontrollera åtkomst till IoT Hub med hjälp av Microsoft Entra-ID.

Konfigurera Microsoft Entra-app

Du måste konfigurera en Microsoft Entra-app som är inställd för dina önskade autentiseringsuppgifter. Appen innehåller parametrar som klienthemlighet som används av serverdelsprogrammet för att autentisera. De tillgängliga appautentiseringskonfigurationerna är:

• Klienthemlighet
• Certifikat
• Federerade identitetsautentiseringsuppgifter

Microsoft Entra-appar kan kräva specifika rollbehörigheter beroende på åtgärder som utförs. Till exempel krävs IoT Hub Twin Contributor för att aktivera läs- och skrivåtkomst till en IoT Hub-enhet och modultvillingar. Mer information finns i Hantera åtkomst till IoT Hub med hjälp av Rolltilldelning i Azure RBAC.

Mer information om hur du konfigurerar en Microsoft Entra-app finns i Snabbstart: Registrera ett program med Microsofts identitetsplattform.

Autentisera med defaultAzureCredential

Det enklaste sättet att använda Microsoft Entra för att autentisera ett bakgrundsprogram är att använda DefaultAzureCredential, men vi rekommenderar att du i en produktionsmiljö använder en annan metod, inklusive en specifik TokenCredential eller avskalad ChainedTokenCredential. För enkelhetens skull beskriver det här avsnittet autentisering med hjälp av DefaultAzureCredential och klienthemlighet. Mer information om fördelar och nackdelar med att använda finns DefaultAzureCredentiali Användningsvägledning för DefaultAzureCredential.

DefaultAzureCredential stöder olika autentiseringsmekanismer och avgör lämplig typ av autentiseringsuppgifter baserat på den miljö som körs i. Den försöker använda flera typer av autentiseringsuppgifter i en ordning tills den hittar en fungerande autentiseringsuppgift.

Microsoft Entra kräver dessa NuGet-paket och motsvarande using instruktioner:

• Azure.Core
• Azure.Identity

using Azure.Core;
using Azure.Identity;

I det här exemplet läggs Microsoft Entra-appregistreringens klienthemlighet, klient-ID och klientorganisationens ID till i miljövariabler. Dessa miljövariabler används av DefaultAzureCredential för att autentisera programmet. Resultatet av en lyckad Microsoft Entra-autentisering är en säkerhetstokenautentiseringsuppgift som skickas till en IoT Hub-anslutningsmetod.

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();

Den resulterande TokenCredential kan sedan skickas till en connect to IoT Hub-metod för alla SDK-klienter som accepterar Microsoft Entra-autentiseringsuppgifter:

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

I det här exemplet skickas TokenCredential till ServiceClient.Create för att skapa ett ServiceClient-anslutningsobjekt.

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

I det här exemplet skickas TokenCredential till RegistryManager.Create för att skapa ett RegistryManager-objekt.

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

Kodexempel

Ett fungerande exempel på Microsoft Entra-tjänstautentisering finns i Exempel på rollbaserad autentisering.

Schemalägg ett direkt metoduppdrag

Använd ScheduleDeviceMethodAsync för att schemalägga ett jobb för att köra en direktmetod på en eller flera enheter.

Använd objektet CloudToDeviceMethod för att ange tidsgränsvärdena för direktmetod och enhetsanslutning.

Till exempel:

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

I det här exemplet schemaläggs ett jobb för en direktmetod med namnet "LockDoor" på en enhet med namnet "Device-1". Enheterna som ingår i det schemalagda jobbet innehåller den andra parametern som ett frågevillkor. Mer information om frågevillkor finns i IoT Hub-frågespråk för enhets- och modultvillingar, jobb och meddelanderoutning.

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);

Schemalägga ett uppdateringsjobb för enhetstvillingar

Använd ScheduleTwinUpdateAsync för att schemalägga en uppdatering av önskade egenskaper och taggar för enhetstvillingar, för att köras på en eller flera enheter.

Skapa och fyll först i ett enhetstvillingobjekt för uppdateringen. Till exempel:

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;

Nästa, anropa ScheduleTwinUpdateAsync. Ange vilka enheter som ska uppdateras som en fråga i den andra parametern. Mer information om frågevillkor finns i IoT Hub-frågespråk för enhets- och modultvillingar, jobb och meddelanderoutning.

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

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

Övervaka ett jobb

Använd GetJobAsync för att övervaka jobbstatusen för ett specifikt jobb-ID.

I det här exemplet kontrolleras jobbstatusen för ett jobb-ID regelbundet tills jobbstatusen har slutförts eller misslyckats. Till exempel:

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));

Exempel på SDK-schemajobb

Azure IoT SDK för .NET innehåller arbetsexempel på tjänstappar som hanterar jobbschemaläggningsuppgifter. Mer information finns i:

• Schemalägg exempel på dubbeluppdatering
• Exempel på E2E-tidsschema för parallelluppdatering.

• Kräver Java SE Development Kit 8. Se till att du väljer Java 8 under Långsiktigt stöd för att gå till nedladdningar för JDK 8.

Översikt

Den här artikeln beskriver hur du använder Azure IoT SDK för Java för att skapa programkod för serverdelstjänsten för att schemalägga jobb för att anropa en direktmetod eller utföra en uppdatering av enhetstvillingar på en eller flera enheter.

Tjänstimportutlåtanden

Klassen JobClient innehåller metoder som tjänster kan använda för att schemalägga jobb.

Använd följande tjänstimportinstruktioner för att få åtkomst till Azure IoT SDK för 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;

Ansluta till IoT Hub

Du kan ansluta en serverdelstjänst till IoT Hub med hjälp av följande metoder:

• Princip för delad åtkomst
• Microsoft Entra

Anslut med en delad åtkomstpolicy

Använd en JobClient-konstruktor för att skapa anslutningen till IoT Hub. Objektet JobClient hanterar kommunikationen med din IoT-hubb.

I den här artikeln beskrivs bakgrundskod som kan schemalägga ett jobb för att anropa en direkt metod, schemalägga ett jobb för att uppdatera en enhetstvilling och övervaka förloppet av ett jobb för en eller flera enheter. För att utföra dessa åtgärder behöver tjänsten behörigheterna för registerläsning och registerskrivning. Som standard skapas varje IoT-hubb med en princip för delad åtkomst med namnet registryReadWrite som ger dessa behörigheter.

Mer information om principer för delad åtkomst finns i Kontrollera åtkomst till IoT Hub med signaturer för delad åtkomst.

Till exempel:

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

Ansluta med Microsoft Entra

En bakgrundsapp som använder Microsoft Entra måste framgångsrikt autentisera sig och hämta ett säkerhetsuppgift för token innan den ansluter till IoT Hub. Den här token skickas till en IoT Hub-anslutningsmetod. Allmän information om hur du konfigurerar och använder Microsoft Entra för IoT Hub finns i Kontrollera åtkomst till IoT Hub med hjälp av Microsoft Entra-ID.

En översikt över Java SDK-autentisering finns i Azure-autentisering med Java och Azure Identity.

För enkelhetens skull fokuserar det här avsnittet på att beskriva autentisering med hjälp av klienthemlighet.

Konfigurera Microsoft Entra-app

Du måste konfigurera en Microsoft Entra-app som är inställd för dina önskade autentiseringsuppgifter. Appen innehåller parametrar som klienthemlighet som används av serverdelsprogrammet för att autentisera. De tillgängliga appautentiseringskonfigurationerna är:

• Klienthemlighet
• Certifikat
• Federerad identitetsbehörighet

Microsoft Entra-appar kan kräva specifika rollbehörigheter beroende på åtgärder som utförs. Till exempel krävs IoT Hub Twin-bidragsgivare för att aktivera läs- och skrivåtkomst till en IoT Hub-enhet och modultvillingar. Mer information finns i Hantera åtkomst till IoT Hub med hjälp av Rolltilldelning i Azure RBAC.

Mer information om hur du konfigurerar en Microsoft Entra-app finns i Snabbstart: Registrera ett program med Microsofts identitetsplattform.

Autentisera med defaultAzureCredential

Det enklaste sättet att använda Microsoft Entra för att autentisera ett serverdelsprogram är att använda DefaultAzureCredential, men det rekommenderas att använda en annan metod i en produktionsmiljö, såsom en specifik TokenCredential eller avskalad ChainedTokenCredential. Mer information om fördelar och nackdelar med att använda finns DefaultAzureCredentiali Kedjor för autentiseringsuppgifter i Azure Identity-klientbiblioteket för Java.

DefaultAzureCredential stöder olika autentiseringsmekanismer och bestämmer lämplig typ av autentiseringsuppgifter baserat på den miljö som körs i. Den försöker använda flera typer av autentiseringsuppgifter i en ordning tills den hittar en fungerande autentiseringsuppgift.

Du kan autentisera autentiseringsuppgifter för Microsoft Entra-appen med defaultAzureCredentialBuilder. Spara anslutningsparametrar som klienthemlighet, tenantID, klient-ID och värden för klienthemligheter som miljövariabler. När du har skapat den TokenCredential skickar du den till ServiceClient eller någon annan byggare som parametern "autentiseringsuppgifter".

I det här exemplet DefaultAzureCredentialBuilder försöker autentisera en anslutning från listan som beskrivs i DefaultAzureCredential. Resultatet av en lyckad Microsoft Entra-autentisering är en säkerhetstokenautentiseringsuppgift som skickas till en konstruktor, till exempel ServiceClient.

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

Autentisera med ClientSecretCredentialBuilder

Du kan använda ClientSecretCredentialBuilder för att skapa en autentiseringsuppgift med hjälp av klienthemlig information. Om det lyckas returnerar den här metoden en TokenCredential som kan skickas till ServiceClient eller annan byggare som parametern "autentiseringsuppgifter".

I det här exemplet har Microsoft Entra-appregistreringsklienthemlighet, klient-ID och klient-ID-värden lagts till i miljövariabler. Dessa miljövariabler används av ClientSecretCredentialBuilder för att skapa autentiseringsuppgifterna.

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();

Andra autentiseringsklasser

Java SDK innehåller även dessa klasser som autentiserar en serverdelsapp med Microsoft Entra:

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

Kodexempel

Arbetsexempel för Microsoft Entra-tjänstautentisering finns i Exempel på rollbaserad autentisering.

Schemalägga ett direkt metoduppdateringsjobb

Använd scheduleDeviceMethod för att köra en direktmetod på en eller flera enheter.

Den här exempelmetoden schemalägger ett jobb för en direktmetod med namnet "lockDoor" på en enhet med namnet "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());
}

Schemalägga ett uppdateringsjobb för enhetstvillingar

Använd scheduleUpdateTwin för att schemalägga ett jobb för att köra en enhetstvillinguppdatering på en eller flera enheter.

Förbered först en DeviceTwinDevice-post för enhetstvillinguppdateringen. Till exempel:

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("*");

Anropa scheduleUpdateTwin sedan för att schemalägga uppdateringsjobbet. Till exempel:

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());
}

Övervaka ett jobb

Använd getJob för att hämta jobbinformation baserat på ett specifikt jobb-ID. getJob returnerar ett JobResult-objekt som innehåller metoder och egenskaper som du kan använda för att kontrollera jobbinformationen, inklusive körningsstatus.

Till exempel:

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;
}

Fråga efter jobbstatus

Använd queryDeviceJob för att fråga efter jobbstatus för ett eller flera jobb.

Till exempel:

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));
  }
}

Exempel på SDK schemajobb

Azure IoT SDK för Java innehåller ett fungerande exempel på en tjänstapp som hanterar jobbschemaläggningsuppgifter. Mer information finns i Exempel på jobbklient.

• Python SDK – Python version 3.7 eller senare rekommenderas. Se till att använda en 32-bitars eller 64-bitars installation beroende på vad som krävs för din konfiguration. Se till att du lägger till Python i den plattformsspecifika miljövariabeln när du uppmanas att göra det under installationen.

Översikt

Den här artikeln beskriver hur du använder Azure IoT SDK för Python för att skapa programkod för serverdelstjänsten för att schemalägga jobb för att anropa en direktmetod eller utföra en önskad egenskapsuppdatering för enhetstvillingar på en eller flera enheter.

Installationspaket

Biblioteket azure-iot-hub måste installeras för att skapa serverdelstjänstprogram.

pip install azure-iot-hub

Importinstruktioner

Klassen IoTHubJobManager visar alla metoder som krävs för att skapa ett serverdelsprogram för att schemalägga jobb från tjänsten.

Lägg till följande import-uttryck.

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

Ansluta till IoT Hub

Du kan ansluta en serverdelstjänst till IoT Hub med hjälp av följande metoder:

• Princip för delad åtkomst
• Microsoft Entra

Anslut med en delad åtkomstpolicy

Anslut till IoT Hub med hjälp av from_connection_string.

I den här artikeln beskrivs backend-kod som kan schemalägga ett jobb för att anropa en direktmetod, schemalägga ett jobb för att uppdatera en enhetstvilling och övervaka förloppet för ett jobb för en eller flera enheter. För att utföra dessa åtgärder behöver tjänsten behörigheterna för registerläsning och registerskrivning. Som standard skapas varje IoT-hubb med en princip för delad åtkomst med namnet registryReadWrite som ger dessa behörigheter.

Mer information om principer för delad åtkomst finns i Kontrollera åtkomst till IoT Hub med signaturer för delad åtkomst.

Till exempel:

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

Ansluta med Microsoft Entra

En back-end-app som använder Microsoft Entra måste autentisera och hämta en autentiseringstoken innan den ansluter till IoT Hub. Den här token skickas till en IoT Hub-anslutningsmetod. Allmän information om hur du konfigurerar och använder Microsoft Entra för IoT Hub finns i Kontrollera åtkomst till IoT Hub med hjälp av Microsoft Entra-ID.

Konfigurera Microsoft Entra-app

Du måste konfigurera en Microsoft Entra-app som är inställd för dina önskade autentiseringsuppgifter. Appen innehåller parametrar som klienthemlighet som används av serverdelsprogrammet för att autentisera. De tillgängliga appautentiseringskonfigurationerna är:

• Klienthemlighet
• Certifikat
• Federerade identitetsautentiseringsuppgifter

Microsoft Entra-appar kan kräva specifika rollbehörigheter beroende på åtgärder som utförs. Till exempel krävs IoT Hub Twin-bidragsgivare för att ge läs- och skrivåtkomst till en IoT Hub-enhet och modultvillingar. Mer information finns i Hantera åtkomst till IoT Hub med hjälp av Rolltilldelning i Azure RBAC.

Mer information om hur du konfigurerar en Microsoft Entra-app finns i Snabbstart: Registrera ett program med Microsofts identitetsplattform.

Autentisera med defaultAzureCredential

Det enklaste sättet att använda Microsoft Entra för att autentisera ett serverdelsprogram är att använda DefaultAzureCredential, men vi rekommenderar att du använder en annan metod i en produktionsmiljö, inklusive en specifik TokenCredential eller avskalad ChainedTokenCredential. För enkelhetens skull beskriver det här avsnittet autentisering med hjälp av DefaultAzureCredential och klienthemlighet. Mer information om fördelar och nackdelar med att använda finns DefaultAzureCredentiali Användningsvägledning för DefaultAzureCredential.

DefaultAzureCredential stöder olika autentiseringsmekanismer och avgör lämplig typ av autentiseringsuppgifter baserat på den miljö som körs i. Den försöker använda flera typer av autentiseringsuppgifter i en ordning tills den hittar en fungerande autentiseringsuppgift.

Microsoft Entra kräver dessa NuGet-paket och motsvarande using instruktioner:

• Azure.Core
• Azure.Identity

using Azure.Core;
using Azure.Identity;

I det här exemplet läggs Microsoft Entra-app-registreringsklientens hemlighet, klient-ID och tenant-ID till i miljövariabler. Dessa miljövariabler används av DefaultAzureCredential för att autentisera programmet. Resultatet av en lyckad Microsoft Entra-autentisering är en säkerhetstokenautentiseringsuppgift som skickas till en IoT Hub-anslutningsmetod.

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();

Den resulterande TokenCredential kan sedan skickas till en connect to IoT Hub-metod för alla SDK-klienter som accepterar Microsoft Entra-autentiseringsuppgifter:

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

I det här exemplet skickas TokenCredential till ServiceClient.Create för att skapa ett ServiceClient-anslutningsobjekt.

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

I det här exemplet skickas TokenCredential till RegistryManager.Create för att skapa ett RegistryManager-objekt.

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

Kodexempel

Ett fungerande exempel på Microsoft Entra-tjänstautentisering finns i Exempel på rollbaserad autentisering.

Schemalägga ett direktmetodjobb

Använd create_scheduled_job för att schemalägga en ny direktmetod för att köra en direktmetod på en eller flera enheter:

create_scheduled_job parameteranteckningar:

• job_id måste vara unikt
• Ställ in type på scheduleDeviceMethod
• Använd cloud_to_device_method för att ange namnet på den direkta metoden och nyttolasten
• Använd max_execution_time_in_seconds för att ange exekveringstiden i sekunder
• Använd query_condition för att ange vilka enheter som ska ingå i direktmetodanropet. Mer information om frågevillkor finns i IoT Hub-frågespråk för enhets- och modultvillingar, jobb och meddelanderoutning.

Till exempel:

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)

Schemalägg en uppdateringsuppgift för enhetstwin

Använd create_scheduled_job för att skapa ett nytt jobb för att köra en uppdatering av önskade egenskaper för enhetstvillingar på en eller flera enheter.

create_scheduled_job parameteranteckningar:

• job_id måste vara unikt
• Ställ in type på scheduleUpdateTwin
• Använd update_twin för att ange namnet på den direkta metoden och nyttolasten
• Använd max_execution_time_in_seconds för att ange körningstiden i sekunder
• Använd query_condition för att ange ett villkor för en eller flera enheter som har direktmetodanropet. Mer information om frågevillkor finns i IoT Hub-frågespråk för enhets- och modultvillingar, jobb och meddelanderoutning.

Till exempel:

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)

Övervaka ett jobb

Använd get_scheduled_job för att hämta information om ett visst jobb på en IoT Hub.

I det här exemplet kontrolleras jobbstatusen för ett specifikt jobb-ID var femte sekund tills jobbet har slutförts.

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)

Exempel på SDK-schemajobb

Azure IoT SDK för Python innehåller arbetsexempel på tjänstappar som hanterar jobbschemaläggningsuppgifter. Mer information finns i:

• Schemalägga ett direkt metodjobb
• Schemalägg en uppdatering av enhetstvillingar.

• Kräver Node.js version 10.0.x eller senare

Översikt

Den här artikeln beskriver hur du använder Azure IoT SDK för Node.js för att skapa programkod för serverdelstjänsten för att schemalägga jobb för att anropa en direktmetod eller utföra en enhetstvillinguppdatering på en eller flera enheter.

Installera tjänst-SDK-paketet

Kör det här kommandot för att installera azure-iothub på utvecklingsdatorn:

npm install azure-iothub --save

Klassen JobClient exponerar alla metoder som krävs för att interagera med jobbschemaläggning från ett serverdelsprogram.

Ansluta till IoT Hub

Du kan ansluta en serverdelstjänst till IoT Hub med hjälp av följande metoder:

• Princip för delad åtkomst
• Microsoft Entra

Ansluta med en princip för delad åtkomst

Använd fromConnectionString för att ansluta till IoT Hub.

I den här artikeln beskrivs back-end-kod som kan schemalägga ett jobb för att anropa en direktmetod, schemalägga ett jobb för att uppdatera en enhetstvilling och övervaka ett jobbs förlopp för en eller flera enheter. För att utföra dessa åtgärder behöver tjänsten behörigheterna för registerläsning och registerskrivning. Som standard skapas varje IoT-hubb med en princip för delad åtkomst med namnet registryReadWrite som ger dessa behörigheter.

Mer information om principer för delad åtkomst finns i Kontrollera åtkomst till IoT Hub med signaturer för delad åtkomst.

Till exempel:

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

Ansluta med Microsoft Entra

En backend-applikation som använder Microsoft Entra måste lyckas autentisera sig och erhålla en säkerhetstokenreferens innan den ansluter till IoT Hub. Den här token skickas till en IoT Hub-anslutningsmetod. Allmän information om hur du konfigurerar och använder Microsoft Entra för IoT Hub finns i Kontrollera åtkomst till IoT Hub med hjälp av Microsoft Entra-ID.

En översikt över Node.js SDK-autentisering finns i:

• Komma igång med användarautentisering i Azure
• Azure Identity-klientbibliotek för JavaScript

Konfigurera Microsoft Entra-app

Du måste konfigurera en Microsoft Entra-app som är inställd för dina önskade autentiseringsuppgifter. Appen innehåller parametrar som klienthemlighet som används av serverdelsprogrammet för att autentisera. De tillgängliga appautentiseringskonfigurationerna är:

• Klienthemlighet
• Certifikat
• Federerade identitetsautentiseringsuppgifter

Microsoft Entra-appar kan kräva specifika rollbehörigheter beroende på åtgärder som utförs. Till exempel IoT Hub Twin Contributor krävs för att aktivera läs- och skrivåtkomst till en IoT Hub-enhet och modultvillingar. Mer information finns i Hantera åtkomst till IoT Hub med hjälp av Rolltilldelning i Azure RBAC.

Mer information om hur du konfigurerar en Microsoft Entra-app finns i Snabbstart: Registrera ett program med Microsofts identitetsplattform.

Autentisera med defaultAzureCredential

Det enklaste sättet att använda Microsoft Entra för att autentisera ett serverdelsprogram är att använda DefaultAzureCredential, men vi rekommenderar att du använder en annan metod i en produktionsmiljö, inklusive en specifik TokenCredential eller avskalad ChainedTokenCredential. För enkelhetens skull beskriver det här avsnittet autentisering med hjälp av DefaultAzureCredential och klienthemlighet. Mer information om fördelar och nackdelar med att använda finns DefaultAzureCredentiali Kedjor för autentiseringsuppgifter i Azure Identity-klientbiblioteket för JavaScript

DefaultAzureCredential stöder olika autentiseringsmekanismer och bestämmer lämplig typ av autentiseringsuppgifter baserat på den miljö som körs i. Den försöker använda flera typer av autentiseringsuppgifter i en ordning tills den hittar en fungerande autentiseringsuppgift.

Microsoft Entra kräver det här paketet:

npm install --save @azure/identity

I det här exemplet har Microsoft Entra-appregistreringsklienthemlighet, klient-ID och klient-ID lagts till i miljövariabler. Dessa miljövariabler används av DefaultAzureCredential för att autentisera programmet. Resultatet av en lyckad Microsoft Entra-autentisering är en säkerhetstokenautentiseringsuppgift som skickas till en IoT Hub-anslutningsmetod.

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

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

Den resulterande token för autentiseringsuppgifter kan sedan skickas till frånTokenCredential för att ansluta till IoT Hub för alla SDK-klienter som accepterar Microsoft Entra-autentiseringsuppgifter:

• Register
• Client
• JobClient

fromTokenCredential kräver två parametrar:

• Url:en för Azure-tjänsten – Azure-tjänst-URL:en ska vara i formatet {Your Entra domain URL}.azure-devices.net utan prefix https:// . Exempel: MyAzureDomain.azure-devices.net
• Azure-token för autentiseringsuppgifter

I det här exemplet hämtas Azure-autentiseringsuppgifterna med hjälp av DefaultAzureCredential. Azure-domänens URL och autentiseringsuppgifter skickas sedan till Registry.fromTokenCredential för att skapa anslutningen till 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);

Kodexempel

Arbetsexempel för Microsoft Entra-tjänstautentisering finns i Azure-identitetsexempel.

Skapa ett direkt metodjobb

Använd scheduleDeviceMethod för att schemalägga ett jobb för att köra en direktmetod på en eller flera enheter.

Skapa först en direkt metoduppdateringsvariabel med information om metodnamn, nyttolast och svarstimeout. Till exempel:

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

scheduleDeviceMethod Anropa sedan för att schemalägga direktmetodanropsjobbet:

• Varje jobb måste ha ett unikt jobb-ID. Du kan använda det här jobb-ID:t för att övervaka ett jobb enligt beskrivningen i avsnittet Övervaka ett jobb i den här artikeln.
• Ange en queryCondition parameter för att utvärdera vilka enheter som jobbet ska köras på. Mer information om frågevillkor finns i IoT Hub-frågespråk för enhets- och modultvillingar, jobb och meddelanderoutning.
• Kontrollera jobResult callbacken för resultatet av jobbschemat. Om jobbet har schemalagts kan du övervaka jobbstatusen enligt beskrivningen i avsnittet Övervaka ett jobb i den här artikeln.

Till exempel:

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));
            }
        });
    }
});

Schemalägga ett uppdateringsjobb för enhetstvillingar

Använd scheduleTwinUpdate för att skapa ett nytt jobb för att köra en enhetstvillinguppdatering på en eller flera enheter.

Skapa först en variabel för önskad egenskapsuppdatering för enhetstvillingar.

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

Anropa scheduleTwinUpdate sedan för att schemalägga det önskade egenskapsuppdateringsjobbet för enhetstvillingen:

• Varje jobb måste ha ett unikt jobb-ID. Du kan använda det här jobb-ID:t för att övervaka ett jobb enligt beskrivningen i avsnittet Övervaka ett jobb i den här artikeln.
• Ange en queryCondition parameter för att utvärdera vilka enheter som jobbet ska köras på. Mer information om frågevillkor finns i IoT Hub-frågespråk för enhets- och modultvillingar, jobb och meddelanderoutning.
• Kontrollera återanropet jobResult för jobbschemaresultatet. Om jobbet har schemalagts kan du övervaka jobbstatusen enligt beskrivningen i avsnittet Övervaka ett jobb i den här artikeln.

Till exempel:

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));
            }
        });
    }
});

Övervaka ett jobb

Använd getJob för att övervaka jobbstatusen för ett specifikt jobb-ID.

Den här exempelfunktionen kontrollerar jobbstatusen för ett specifikt jobb-ID regelbundet tills jobbet har slutförts eller misslyckats.

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);
}

Exempel på schemajobb för SDK

Azure IoT SDK för Node.js innehåller ett fungerande exempel på en tjänstapp som hanterar jobbschemaläggningsuppgifter. Mer information finns i E2E-test för jobbklient.