Feladatok használata eszközök csoportjainak feladatainak ütemezéséhez - Azure IoT Hub

Visual Studio-t igényel

Áttekintés

Ez a cikk azt ismerteti, hogyan használható az Azure IoT SDK for .NET a háttérszolgáltatás-alkalmazás kódjának ütemezési feladathoz való létrehozásához egy közvetlen metódus meghívásához vagy ikereszköz-frissítés végrehajtásához egy vagy több eszközön.

Szolgáltatás NuGet-csomag hozzáadása

A háttérszolgáltatás-alkalmazásokhoz a Microsoft.Azure.Devices NuGet-csomag szükséges.

Állítások használata

Adja hozzá a következő utasításokat.

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

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

Csatlakozás az IoT Hubhoz

Háttérszolgáltatást az alábbi módszerekkel csatlakoztathat az IoT Hubhoz:

Megosztott hozzáférési szabályzat
Microsoft Entra

Fontos

Ez a cikk a szolgáltatáshoz való csatlakozás lépéseit tartalmazza közös hozzáférésű jogosultságkód használatával. Ez a hitelesítési módszer a teszteléshez és a kiértékeléshez kényelmes, de biztonságosabb módszer a Microsoft Entra-azonosítóval vagy felügyelt identitásokkal történő hitelesítés egy szolgáltatáshoz. További információkért tekintse meg a felhőalapú biztonság > IoT-megoldások biztonsági legjobb gyakorlatait.

Csatlakozás megosztott hozzáférési szabályzattal

Háttéralkalmazás csatlakoztatása egy eszközhöz a CreateFromConnectionString használatával.

Ez a cikk olyan háttérkódot ismertet, amely ütemezhet egy feladatot egy közvetlen metódus meghívására, ütemezhet egy feladatot egy ikereszköz frissítésére, és egy vagy több eszköz feladatának előrehaladását figyeli. Ezeknek a műveleteknek a végrehajtásához a szolgáltatásnak olvasási és beállításjegyzék-írási engedélyre van szüksége. Alapértelmezés szerint minden IoT Hub egy registryReadWrite nevű megosztott hozzáférési szabályzattal jön létre, amely ezeket az engedélyeket biztosítja.

A megosztott hozzáférési szabályzatokról további információt az IoT Hub hozzáférésének szabályozása közös hozzáférésű jogosultságkódokkal című témakörben talál.

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

Csatlakozás a Microsoft Entra használatával

A Microsoft Entrát használó háttéralkalmazásnak sikeresen hitelesítenie kell és be kell szereznie egy biztonsági jogkivonat hitelesítő adatait, mielőtt csatlakozik az IoT Hubhoz. Ez a token egy IoT Hub-kapcsolati metódusnak van átadva. A Microsoft Entra for IoT Hub beállításával és használatával kapcsolatos általános információkért tekintse meg az IoT Hubhoz való hozzáférés Szabályozása a Microsoft Entra ID használatával című témakört.

A Microsoft Entra alkalmazás konfigurálása

Be kell állítania egy Microsoft Entra-alkalmazást, amely az előnyben részesített hitelesítési hitelesítő adatokhoz van konfigurálva. Az alkalmazás olyan paramétereket tartalmaz, mint az ügyfélkulcs, amelyeket a háttéralkalmazás használ a hitelesítéshez. Az elérhető alkalmazáshitelesítési konfigurációk a következők:

Titkos ügyfélkód
Tanúsítvány
Összevont identitás hitelesítő adatai

A Microsoft Entra-alkalmazások adott szerepkör-engedélyeket igényelhetnek a végrehajtott műveletektől függően. Például az IoT Hub ikerpéldány-közreműködője az IoT Hub-eszközökhöz és modulikrekhez való olvasási és írási hozzáférés engedélyezéséhez szükséges. További információ: IoT Hub-hozzáférés kezelése Azure RBAC-szerepkör-hozzárendeléssel.

A Microsoft Entra-alkalmazások beállításáról további információt a következő útmutatóban talál: Alkalmazás regisztrálása a Microsoft identitásplatformján.

Hitelesítés DefaultAzureCredential használatával

A Microsoft Entra segítségével a legegyszerűbben a DefaultAzureCredential használatával hitelesíthet egy háttéralkalmazást, de ajánlott egy másik módszert használni egy éles környezetben, beleértve egy adott TokenCredential vagy pared-down ChainedTokenCredentialmetódust is. Az egyszerűség kedvéért ez a szakasz a hitelesítést és az ügyfél titkos kódjának használatát DefaultAzureCredential ismerteti. A használat DefaultAzureCredentialelőnyeiről és hátrányairól további információt a DefaultAzureCredential használati útmutatója tartalmaz.

DefaultAzureCredential támogatja a különböző hitelesítési mechanizmusokat, és meghatározza a megfelelő hitelesítőadat-típust az általa futtatott környezet alapján. Több hitelesítő adattípust próbál meg egy sorrendben használni, amíg nem talál egy működő hitelesítő adatot.

A Microsoft Entra megköveteli ezeket a NuGet-csomagokat és a hozzájuk tartozó using utasításokat:

Azure.Core
Azure.Identity

using Azure.Core;
using Azure.Identity;

Ebben a példában a Microsoft Entra alkalmazásregisztrációs ügyfélkulcsa, ügyfél-azonosítója és bérlőazonosítója hozzáadódik a környezeti változókhoz. Ezek a környezeti változók az DefaultAzureCredential alkalmazás hitelesítésére szolgálnak. A sikeres Microsoft Entra-hitelesítés eredménye egy biztonsági jogkivonat, amelyet az IoT Hub kapcsolati módszerének adnak át.

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

Az eredményül kapott TokenCredential ezután átadható egy IoT Hub-metódushoz való csatlakozásnak minden olyan SDK-ügyfél esetében, amely elfogadja a Microsoft Entra hitelesítő adatait:

Ebben a példában a TokenCredential átadása a ServiceClient.Create részére történik, hogy létrejöjjön egy ServiceClient kapcsolati objektum.

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

Ebben a példában a TokenCredential átadódik a RegistryManager.Create-nak/cnek egy RegistryManager objektum létrehozásához.

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

Kód példa

A Microsoft Entra szolgáltatáshitelesítés működő mintájáért tekintse meg a szerepköralapú hitelesítési mintát.

Közvetlen módszerű feladat ütemezése

A ScheduleDeviceMethodAsync használatával ütemezhet egy feladatot egy vagy több eszközön futó közvetlen metódus futtatásához.

A CloudToDeviceMethod objektummal adja meg a közvetlen metódus nevét és az eszközkapcsolat időtúllépési értékeit.

Példa:

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

Ez a példa egy "LockDoor" nevű közvetlen metódus feladatát ütemezi egy "Device-1" nevű eszközön. Az ütemezett feladatban szereplő eszközök a második paramétert tartalmazzák lekérdezési feltételként. További információért a lekérdezési feltételekről tekintse meg az IoT Hub lekérdezési nyelvét az eszköz- és modul ikrekhez, feladatokhoz, és üzenet útválasztásához.

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

Ikereszköz-frissítési feladat ütemezése

A ScheduleTwinUpdateAsync használatával ütemezhet egy új ikereszköz kívánt tulajdonságait és címkéinek frissítési feladatát úgy, hogy egy vagy több eszközön fusson.

Először hozzon létre és töltse fel a Twin objektumot a frissítéshez. Példa:

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;

Ezután hívja fel a következőt ScheduleTwinUpdateAsync. Adja meg a második paraméterben lekérdezésként frissíteni kívánt eszközöket. További információ a lekérdezési feltételekről az IoT Hub lekérdezési nyelv eszköz- és modul-ikrekhez, feladatokhoz, és üzenetirányításhoz című részben található.

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

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

Feladat nyomon követése

A GetJobAsync használatával figyelheti egy adott feladatazonosító feladatállapotát.

Ez a példa rendszeres időközönként ellenőrzi egy feladatazonosító feladatállapotát, amíg a feladat állapota nem fejeződik be vagy nem hiúsul meg. Példa:

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

SDK-ütemezési feladatok példái

A .NET-hez készült Azure IoT SDK munkamintákat biztosít a feladatütemezési feladatokat kezelő szolgáltatásalkalmazásokról. További információk:

A Java SE fejlesztői készlet 8-at igényel. A JDK 8 letöltéséhez győződjön meg arról, hogy a Hosszú távú támogatás alatt a Java 8-at választja.

Áttekintés

Ez a cikk azt ismerteti, hogyan használhatja a Java Azure IoT SDK-t háttérszolgáltatás-alkalmazáskód létrehozására a feladat ütemezéséhez egy közvetlen metódus meghívásához vagy ikereszköz-frissítés végrehajtásához egy vagy több eszközön.

Szolgáltatásimportálási utasítások

A JobClient osztály olyan metódusokat tartalmaz, amelyekkel a szolgáltatások feladatokat ütemezhetnek.

Az alábbi szolgáltatásimportálási utasítások segítségével érheti el a Java-hoz készült Azure IoT SDK-t.

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;

Csatlakozás az IoT Hubhoz

Háttérszolgáltatást az alábbi módszerekkel csatlakoztathat az IoT Hubhoz:

Megosztott hozzáférési szabályzat
Microsoft Entra

Fontos

Ez a cikk a szolgáltatáshoz való csatlakozás lépéseit tartalmazza közös hozzáférésű jogosultságkód használatával. Ez a hitelesítési módszer a teszteléshez és a kiértékeléshez kényelmes, de biztonságosabb módszer a Microsoft Entra-azonosítóval vagy felügyelt identitásokkal történő hitelesítés egy szolgáltatáshoz. További információkért tekintse meg a felhőalapú biztonság > IoT-megoldások biztonsági legjobb gyakorlatait.

Csatlakozás megosztott hozzáférési szabályzattal

A JobClient konstruktor használatával hozza létre a kapcsolatot az IoT Hubbal. Az JobClient objektum kezeli az IoT Hubbal folytatott kommunikációt.

Ez a cikk olyan háttérkódot ismertet, amely ütemezhet egy feladatot egy közvetlen metódus meghívására, ütemezhet egy feladatot egy ikereszköz frissítésére, és egy vagy több eszköz feladatának előrehaladását figyeli. Ezeknek a műveleteknek a végrehajtásához a szolgáltatásnak olvasási és beállításjegyzék-írási engedélyre van szüksége. Alapértelmezés szerint minden IoT Hub egy registryReadWrite nevű megosztott hozzáférési szabályzattal jön létre, amely ezeket az engedélyeket biztosítja.

A megosztott hozzáférési szabályzatokról további információt az IoT Hub hozzáférésének szabályozása közös hozzáférésű jogosultságkódokkal című témakörben talál.

Példa:

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

Csatlakozás a Microsoft Entra használatával

A Microsoft Entrát használó háttéralkalmazásnak sikeresen hitelesítenie kell és be kell szereznie egy biztonsági jogkivonat hitelesítő adatait, mielőtt csatlakozik az IoT Hubhoz. Ez a jogkivonat egy IoT Hub-kapcsolati metódusnak lesz átadva. A Microsoft Entra for IoT Hub beállításával és használatával kapcsolatos általános információkért tekintse meg az IoT Hubhoz való hozzáférés Szabályozása a Microsoft Entra ID használatával című témakört.

A Java SDK-hitelesítés áttekintéséhez tekintse meg a Java és az Azure Identity használatával történő Azure-hitelesítést.

Az egyszerűség kedvéért ez a szakasz az ügyféltitkos hitelesítés leírására összpontosít.

A Microsoft Entra alkalmazás konfigurálása

Be kell állítania egy Microsoft Entra-alkalmazást, amely az előnyben részesített hitelesítési hitelesítő adatokhoz van konfigurálva. Az alkalmazás olyan paramétereket tartalmaz, mint az ügyfélkulcs, amelyeket a háttéralkalmazás használ a hitelesítéshez. Az elérhető alkalmazáshitelesítési konfigurációk a következők:

Titkos ügyfélkód
Tanúsítvány
Összevont identitás hitelesítő adatai

A Microsoft Entra-alkalmazások adott szerepkör-engedélyeket igényelhetnek a végrehajtott műveletektől függően. A IoT Hub ikerhozzájárulás szükséges ahhoz, hogy engedélyezze az olvasási és írási hozzáférést IoT Hub eszközök és modul ikereihez. További információ: IoT Hub-hozzáférés kezelése Azure RBAC-szerepkör-hozzárendeléssel.

A Microsoft Entra-alkalmazások beállításáról további információért lásd a Rövid útmutató: Alkalmazás regisztrálása a Microsoft identitásplatformon.

Hitelesítés DefaultAzureCredential használatával

A Microsoft Entra segítségével a legegyszerűbben egy háttéralkalmazást a DefaultAzureCredential használatával hitelesíthet, de ajánlott egy másik módszert használni éles környezetben, beleértve egy adott TokenCredential vagy egyszerűsített ChainedTokenCredential metódust is. A használat DefaultAzureCredentialelőnyeiről és hátrányairól további információt a Java Azure Identity ügyfélkódtárában található Hitelesítőadat-láncok című témakörben talál.

A DefaultAzureCredential különböző hitelesítési mechanizmusokat támogat, és meghatározza a megfelelő hitelesítőadat-típust a környezet alapján, amelyben végrehajtja. Több hitelesítő adattípust próbál meg egy sorrendben használni, amíg nem talál egy működő hitelesítő adatot.

A Microsoft Entra alkalmazás hitelesítő adatait a DefaultAzureCredentialBuilder használatával hitelesítheti. Mentse a kapcsolati paramétereket, például az ügyfél titkos bérlőazonosítóját, az ügyfélazonosítót és az ügyfél titkos kódértékeit környezeti változóként. A TokenCredential létrehozása után adja át a ServiceClient vagy más építőnek hitelesítőadat-paraméterként.

Ebben a példában DefaultAzureCredentialBuilder megpróbál hitelesíteni egy kapcsolatot a DefaultAzureCredential leírt listából. A sikeres Microsoft Entra-hitelesítés eredménye egy biztonsági jogkivonatként szolgáló hitelesítő adat, amelyet átadnak egy konstruktornak, például a ServiceClient-nek.

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

Hitelesítés a ClientSecretCredentialBuilder használatával

A ClientSecretCredentialBuilder használatával létrehozhat egy hitelesítő adatot az ügyfél titkos adataival. Ha sikeres, ez a metódus egy TokenCredential értéket ad vissza, amely átadható a ServiceClientnek vagy más szerkesztőnek hitelesítőadat-paraméterként.

Ebben a példában a Microsoft Entra alkalmazásregisztrációs ügyfél titkos kódját, ügyfél-azonosítóját és bérlőazonosító-értékeit hozzáadtuk a környezeti változókhoz. Ezeket a környezeti változókat a hitelesítő adatok létrehozásához használják ClientSecretCredentialBuilder .

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

Egyéb hitelesítési osztályok

A Java SDK az alábbi osztályokat is tartalmazza, amelyek egy háttéralkalmazást hitelesítenek a Microsoft Entra használatával:

Kódminták

A Microsoft Entra szolgáltatáshitelesítés működő mintáiért lásd a szerepköralapú hitelesítési mintát.

Közvetlen metódusfrissítési feladat ütemezése

A scheduleDeviceMethod használatával közvetlen metódust futtathat egy vagy több eszközön.

Ez a példametódus a "lockDoor" nevű közvetlen metódus feladatát ütemezi egy "Device-1" nevű eszközön.

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

Ikereszköz-frissítési feladat ütemezése

A scheduleUpdateTwin használatával ütemezhet egy feladatot egy ikereszköz-frissítés futtatásához egy vagy több eszközön.

Először készítse elő a DeviceTwinDevice rekordot az ikereszköz frissítéséhez. Példa:

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

Ezután hívja fel a scheduleUpdateTwin-t, hogy ütemezze a frissítési feladatot. Példa:

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

Feladat monitorozása

A getJob használatával lekérheti a feladatadatokat egy adott feladatazonosító alapján. getJob Egy JobResult objektumot ad vissza, amely olyan metódusokat és tulajdonságokat tartalmaz, amelyekkel ellenőrizheti a feladatok adatait, beleértve a futó állapotot is.

Példa:

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

Feladat állapotának lekérdezése

A queryDeviceJob használatával lekérdezheti egy vagy több feladat feladatának állapotát.

Példa:

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

Példa SDK ütemezési feladatra

A Java-hoz készült Azure IoT SDK egy szolgáltatásalkalmazás működő mintáját biztosítja, amely feladatütemezési feladatokat kezel. További információ: Feladatügyfél-minta.

Python SDK – A Python 3.7-es vagy újabb verziója ajánlott. Mindenképp a rendszernek megfelelő, 32 vagy 64 bites telepítést használja. Amikor a rendszer erre kéri, mindenképp adja hozzá a Pythont a platformspecifikus környezeti változóhoz.

Áttekintés

Ez a cikk azt ismerteti, hogyan használhatja a Pythonhoz készült Azure IoT SDK-t háttérszolgáltatás-alkalmazáskód létrehozására a feladat ütemezéséhez egy közvetlen metódus meghívásához vagy egy ikereszköz kívánt tulajdonságfrissítésének végrehajtásához egy vagy több eszközön.

Csomag telepítése

A háttérszolgáltatás-alkalmazások létrehozásához telepíteni kell az azure-iot-hub kódtárat.

pip install azure-iot-hub

Importálási utasítások

Az IoTHubJobManager osztály minden olyan módszert elérhetővé tesz, amely egy háttéralkalmazás létrehozásához szükséges a feladatok szolgáltatásból való ütemezéséhez.

Adja hozzá a következő import-utasításokat.

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

Csatlakozás az IoT Hubhoz

Háttérszolgáltatást az alábbi módszerekkel csatlakoztathat az IoT Hubhoz:

Megosztott hozzáférési szabályzat
Microsoft Entra

Fontos

Ez a cikk a szolgáltatáshoz való csatlakozás lépéseit tartalmazza közös hozzáférésű jogosultságkód használatával. Ez a hitelesítési módszer a teszteléshez és a kiértékeléshez kényelmes, de biztonságosabb módszer a Microsoft Entra-azonosítóval vagy felügyelt identitásokkal történő hitelesítés egy szolgáltatáshoz. További információkért tekintse meg a felhőalapú biztonság > IoT-megoldások biztonsági legjobb gyakorlatait.

Csatlakozás megosztott hozzáférési szabályzattal

Csatlakozzon az IoT Hubhoz from_connection_string használatával.

Ez a cikk olyan háttérkódot ismertet, amely ütemezhet egy feladatot egy közvetlen metódus meghívására, ütemezhet egy feladatot egy ikereszköz frissítésére, és egy vagy több eszköz feladatának előrehaladását figyeli. Ezeknek a műveleteknek a végrehajtásához a szolgáltatásnak olvasási és beállításjegyzék-írási engedélyre van szüksége. Alapértelmezés szerint minden IoT Hub egy registryReadWrite nevű megosztott hozzáférési szabályzattal jön létre, amely ezeket az engedélyeket biztosítja.

A megosztott hozzáférési szabályzatokról további információt az IoT Hub hozzáférésének szabályozása közös hozzáférésű jogosultságkódokkal című témakörben talál.

Példa:

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

Csatlakozás a Microsoft Entra használatával

A Microsoft Entrát használó háttéralkalmazásnak sikeresen hitelesítenie kell és be kell szereznie egy biztonsági jogkivonat hitelesítő adatait, mielőtt csatlakozik az IoT Hubhoz. Ez a token egy IoT Hub-kapcsolati módszernek lesz átadva. A Microsoft Entra for IoT Hub beállításával és használatával kapcsolatos általános információkért tekintse meg az IoT Hubhoz való hozzáférés Szabályozása a Microsoft Entra ID használatával című témakört.

A Microsoft Entra alkalmazás konfigurálása

Be kell állítania egy Microsoft Entra-alkalmazást, amely az előnyben részesített hitelesítési hitelesítő adatokhoz van konfigurálva. Az alkalmazás olyan paramétereket tartalmaz, mint az ügyfélkulcs, amelyeket a háttéralkalmazás használ a hitelesítéshez. Az elérhető alkalmazáshitelesítési konfigurációk a következők:

Titkos ügyfélkód
Tanúsítvány
Összevont identitás hitelesítő adatai

A Microsoft Entra-alkalmazások adott szerepkör-engedélyeket igényelhetnek a végrehajtott műveletektől függően. Például az IoT Hub Twin Contributor szükséges az IoT Hub eszközök és modul ikrek olvasási és írási hozzáférésének engedélyezéséhez. További információ: IoT Hub-hozzáférés kezelése Azure RBAC-szerepkör-hozzárendeléssel.

A Microsoft Entra-alkalmazások beállításáról további információért lásd a Rövid útmutató: Alkalmazás regisztrálása a Microsoft identitásplatformon.

Hitelesítés DefaultAzureCredential használatával

A Microsoft Entra segítségével a legegyszerűbben a DefaultAzureCredential használatával hitelesíthet egy háttéralkalmazást, de ajánlott egy másik módszert használni egy éles környezetben, beleértve egy adott TokenCredential vagy pared-down ChainedTokenCredentialmetódust is. Az egyszerűség kedvéért ez a szakasz a hitelesítést és az ügyfél titkos kódjának használatát DefaultAzureCredential ismerteti. A használat DefaultAzureCredentialelőnyeiről és hátrányairól további információt a DefaultAzureCredential használati útmutatója tartalmaz.

DefaultAzureCredential támogatja a különböző hitelesítési mechanizmusokat, és meghatározza a megfelelő hitelesítőadat-típust az általa futtatott környezet alapján. Több hitelesítő adattípust próbál meg egy sorrendben használni, amíg nem talál egy működő hitelesítő adatot.

A Microsoft Entra megköveteli ezeket a NuGet-csomagokat és a hozzájuk tartozó using utasításokat:

Azure.Core
Azure.Identity

using Azure.Core;
using Azure.Identity;

Ebben a példában a Microsoft Entra alkalmazásregisztrációs ügyfélkulcsa, ügyfél-azonosítója és bérlőazonosítója hozzáadódik a környezeti változókhoz. Ezek a környezeti változók az DefaultAzureCredential alkalmazás hitelesítésére szolgálnak. A sikeres Microsoft Entra-hitelesítés eredménye egy biztonsági azonosítójegy, amelyet átad egy IoT Hub-kapcsolati módszernek.

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

Az eredményül kapott TokenCredential ezután átadható egy IoT Hub-metódushoz való csatlakozásnak minden olyan SDK-ügyfél esetében, amely elfogadja a Microsoft Entra hitelesítő adatait:

Ebben a példában a TokenCredential átadása a ServiceClient.Create számára történik, hogy létrehozzon egy ServiceClient kapcsolati objektumot.

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

Ebben a példában a TokenCredential átadásra kerül a RegistryManager.Create-nek, hogy létrehozzon egy RegistryManager objektumot.

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

Kódminta

A Microsoft Entra szolgáltatáshitelesítés működő mintájáért tekintse meg a szerepköralapú hitelesítési mintát.

Közvetlen metódusfeladat ütemezése

A create_scheduled_job használatával ütemezhet egy új közvetlen metódust egy vagy több eszközön futó közvetlen metódus futtatásához:

create_scheduled_job paraméterjegyzetek:

job_id egyedinek kell lennie
Állítsa a type elemet scheduleDeviceMethod értékre
Használja a cloud_to_device_method-t a közvetlen metódus neve és a terhelés beállításához.
A végrehajtási idő másodpercben történő megadására használható max_execution_time_in_seconds
A közvetlen metódushíváshoz mellékelendő eszközök megadására használható query_condition . További információ a lekérdezési feltételekről: IoT Hub lekérdezési nyelv eszköz- és modul-ikereszközökhöz, feladatokhoz és üzenet-útválasztáshoz.

Példa:

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)

Ikereszköz-frissítési feladat ütemezése

A create_scheduled_job használatával hozzon létre egy új feladatot egy ikereszköz kívánt tulajdonságfrissítésének futtatásához egy vagy több eszközön.

create_scheduled_job paraméterjegyzetek:

job_id egyedinek kell lennie
Állítsa a type elemet scheduleUpdateTwin értékre
A update_twin közvetlen metódus nevének és hasznos adatainak beállítása
A végrehajtási idő másodpercben történő megadására használható max_execution_time_in_seconds
Egy vagy több közvetlen metódushívással rendelkező eszköz feltételének megadására használható query_condition . További információ a lekérdezési feltételekről: IoT Hub lekérdezési nyelv eszköz- és modul-ikrekhez, feladatokhoz és üzenet-útválasztáshoz.

Példa:

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)

Feladat monitorozása

A get_scheduled_job használatával lekérheti egy adott feladat részleteit egy IoT Hubon.

Ez a példa öt másodpercenként ellenőrzi egy adott feladatazonosító feladatállapotát, amíg a feladat be nem fejeződik.

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)

SDK-ütemezési feladatok példái

A Pythonhoz készült Azure IoT SDK munkamintákat biztosít a feladatütemezési feladatokat kezelő szolgáltatásalkalmazásokról. További információk:

Közvetlen módszerfeladat ütemezése
Ikereszköz-frissítés ütemezése.

Node.js 10.0.x vagy újabb verziót igényel

Áttekintés

Ez a cikk azt ismerteti, hogyan használhatja az Azure IoT SDK-t Node.js háttérszolgáltatás-alkalmazás kódjának létrehozására, hogy ütemezze a feladatot egy közvetlen metódus meghívására vagy egy vagy több eszközön végzett ikereszköz-frissítés végrehajtására.

Szolgáltatás SDK-csomag telepítése

Futtassa ezt a parancsot az Azure-iotHub fejlesztői gépen való telepítéséhez:

npm install azure-iothub --save

A JobClient osztály minden olyan metódust elérhetővé tesz, amely egy háttéralkalmazás feladatütemezéséhez szükséges.

Csatlakozás az IoT Hubhoz

Háttérszolgáltatást az alábbi módszerekkel csatlakoztathat az IoT Hubhoz:

Megosztott hozzáférési szabályzat
Microsoft Entra

Fontos

Ez a cikk a szolgáltatáshoz való csatlakozás lépéseit tartalmazza közös hozzáférésű jogosultságkód használatával. Ez a hitelesítési módszer a teszteléshez és a kiértékeléshez kényelmes, de biztonságosabb módszer a Microsoft Entra-azonosítóval vagy felügyelt identitásokkal történő hitelesítés egy szolgáltatáshoz. További információkért tekintse meg a felhőalapú biztonság > IoT-megoldások biztonsági legjobb gyakorlatait.

Csatlakozás megosztott hozzáférési szabályzattal

A fromConnectionString használatával csatlakozhat az IoT Hubhoz.

Ez a cikk olyan háttérkódot ismertet, amely ütemezhet egy feladatot egy közvetlen metódus meghívására, ütemezhet egy feladatot egy ikereszköz frissítésére, és egy vagy több eszköz feladatának előrehaladását figyeli. Ezeknek a műveleteknek a végrehajtásához a szolgáltatásnak olvasási és beállításjegyzék-írási engedélyre van szüksége. Alapértelmezés szerint minden IoT Hub egy registryReadWrite nevű megosztott hozzáférési szabályzattal jön létre, amely ezeket az engedélyeket biztosítja.

A megosztott hozzáférési szabályzatokról további információt az IoT Hub hozzáférésének szabályozása közös hozzáférésű jogosultságkódokkal című témakörben talál.

Példa:

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

Csatlakozás a Microsoft Entra használatával

A Microsoft Entrát használó háttéralkalmazásnak sikeresen hitelesítenie kell és be kell szereznie egy biztonsági jogkivonat hitelesítő adatait, mielőtt csatlakozik az IoT Hubhoz. Ez a jogkivonat egy IoT Hub-kapcsolati metódusnak lesz átadva. A Microsoft Entra for IoT Hub beállításával és használatával kapcsolatos általános információkért tekintse meg az IoT Hubhoz való hozzáférés Szabályozása a Microsoft Entra ID használatával című témakört.

A Node.js SDK-hitelesítés áttekintését lásd:

A Microsoft Entra alkalmazás konfigurálása

Be kell állítania egy Microsoft Entra-alkalmazást, amely az előnyben részesített hitelesítési hitelesítő adatokhoz van konfigurálva. Az alkalmazás olyan paramétereket tartalmaz, mint az ügyfélkulcs, amelyeket a háttéralkalmazás használ a hitelesítéshez. Az elérhető alkalmazáshitelesítési konfigurációk a következők:

Titkos ügyfélkód
Tanúsítvány
Szövetségi identitás hitelesítő

A Microsoft Entra-alkalmazások adott szerepkör-engedélyeket igényelhetnek a végrehajtott műveletektől függően. Az IoT Hub ikerpéldány-közreműködője például az IoT Hub-eszközökhöz és modulikrekhez való olvasási és írási hozzáférés engedélyezéséhez szükséges. További információ: IoT Hub-hozzáférés kezelése Azure RBAC-szerepkör-hozzárendeléssel.

A Microsoft Entra-alkalmazások beállításáról további információkért lásd a következő rövid útmutatót: Alkalmazás regisztrálása a Microsoft identitásplatform.

Hitelesítés DefaultAzureCredential használatával

A Microsoft Entra segítségével a legegyszerűbben hitelesíthet egy háttéralkalmazást a DefaultAzureCredential használatával, de éles környezetben ajánlott egy másik módszert használni, beleértve egy adott módszertTokenCredential vagy egy egyszerűsített módszertChainedTokenCredential is. Az egyszerűség kedvéért ez a szakasz a hitelesítést és az ügyfél titkos kódjának használatát DefaultAzureCredential ismerteti. A használat DefaultAzureCredentialelőnyeiről és hátrányairól további információt a JavaScripthez készült Azure Identity ügyfélkódtár hitelesítőadat-láncai című témakörben talál .

A DefaultAzureCredential különböző hitelesítési mechanizmusokat támogat, és meghatározza a megfelelő hitelesítőadat-típust a környezet alapján, amelyben végrehajtja. Több hitelesítő adattípust próbál meg egy sorrendben használni, amíg nem talál egy működő hitelesítő adatot.

A Microsoft Entra a következő csomagot igényli:

npm install --save @azure/identity

Ebben a példában a Microsoft Entra alkalmazásregisztrációs ügyfél titkos kódját, ügyfél-azonosítóját és bérlőazonosítóját hozzáadtuk a környezeti változókhoz. Ezek a környezeti változók az DefaultAzureCredential alkalmazás hitelesítésére szolgálnak. A sikeres Microsoft Entra-hitelesítés eredménye egy biztonsági jogkivonat, amelyet egy IoT Hub-kapcsolati módszernek adnak át.

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

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

Az eredményül kapott hitelesítő jogkivonat ezután átadható a FromTokenCredential-nak , hogy csatlakozzon az IoT Hubhoz minden olyan SDK-ügyfélhez, amely elfogadja a Microsoft Entra hitelesítő adatait:

fromTokenCredential két paramétert igényel:

Az Azure-szolgáltatás URL-címe – Az Azure-szolgáltatás URL-címének előtag nélküli {Your Entra domain URL}.azure-devices.net formátumban https:// kell lennie. Például: MyAzureDomain.azure-devices.net.
Az Azure hitelesítőadat-jogkivonata

Ebben a példában az Azure-hitelesítő adatokat a DefaultAzureCredential használatával szerezzük be. A rendszer ezután az Azure-tartomány URL-címét és hitelesítő adatait adja meg Registry.fromTokenCredential az IoT Hubhoz való kapcsolat létrehozásához.

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

Kódminták

A Microsoft Entra szolgáltatáshitelesítés működő mintáit az Azure-identitásra vonatkozó példákban talál.

Közvetlen metódusfeladat létrehozása

A scheduleDeviceMethod használatával ütemezhet egy feladatot egy vagy több eszközön futó közvetlen metódus futtatásához.

Először hozzon létre egy közvetlen metódusfrissítési változót metódusnévvel, hasznos adatokkal és válaszidő-időtúllépési információkkal. Példa:

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

Ezután hívja meg scheduleDeviceMethod, hogy ütemezze a közvetlen metódushívási feladatot.

Minden feladatnak egyedi feladatazonosítóval kell rendelkeznie. Ezzel a feladatazonosítóval monitorozhatja a feladatokat a jelen cikk Feladat figyelése szakaszában leírtak szerint.
Adjon meg egy paramétert queryCondition , amely kiértékeli, hogy mely eszközökön kell futtatni a feladatot. További információ a lekérdezési feltételekről: IoT Hub lekérdezési nyelv eszköz- és modul-ikereszközökhöz, feladatokhoz és üzenet-útválasztáshoz.
Ellenőrizze a jobResult feladatütemezési eredmény visszahívását. Ha a feladat ütemezése sikeresen megtörtént, a feladat állapotát a cikk Egy feladat figyelése szakaszában látható módon figyelheti.

Példa:

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

Ikereszköz-frissítési feladat ütemezése

A scheduleTwinUpdate használatával hozzon létre egy új feladatot egy ikereszköz-frissítés futtatásához egy vagy több eszközön.

Először hozzon létre egy ikereszköz kívánt tulajdonságfrissítési változót.

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

Ezután hívja meg scheduleTwinUpdate az ikereszköz kívánt tulajdonságfrissítési feladatának ütemezését:

Minden feladatnak egyedi feladatazonosítóval kell rendelkeznie. Ezzel a feladatazonosítóval monitorozhatja a feladatokat a jelen cikk Feladat figyelése szakaszában leírtak szerint.
Adjon meg egy paramétert queryCondition , amely kiértékeli, hogy mely eszközökön kell futtatni a feladatot. További információ a lekérdezési feltételekről: IoT Hub lekérdezési nyelv eszköz- és modul-ikereszközökhöz, feladatokhoz és üzenet-útválasztáshoz.
Ellenőrizze a jobResult visszahívást a feladatütemezési eredményhez. Ha a feladat ütemezése sikeresen megtörtént, a feladat állapotát a cikk Egy feladat figyelése szakaszában látható módon figyelheti.

Példa:

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

Munka megfigyelése

A getJob használatával figyelheti egy adott feladatazonosító feladatállapotát.

Ez a példafüggvény rendszeresen ellenőrzi egy adott feladatazonosító feladatállapotát, amíg a feladat be nem fejeződik vagy sikertelen lesz.

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

Példa SDK ütemezési feladatra

A Node.js-hez készült Azure IoT SDK egy szolgáltatásalkalmazás működő mintáját biztosítja, amely feladatütemezési feladatokat kezel. További információ: Feladatügyfél E2E-tesztje.

Megosztás a következőn keresztül:

Feladatok ütemezése és közvetítése

Előfeltételek

Áttekintés

Szolgáltatás NuGet-csomag hozzáadása

Állítások használata

Csatlakozás az IoT Hubhoz

Csatlakozás megosztott hozzáférési szabályzattal

Csatlakozás a Microsoft Entra használatával

A Microsoft Entra alkalmazás konfigurálása

Hitelesítés DefaultAzureCredential használatával

Kód példa

Közvetlen módszerű feladat ütemezése

Ikereszköz-frissítési feladat ütemezése

Feladat nyomon követése

SDK-ütemezési feladatok példái

Áttekintés

Szolgáltatásimportálási utasítások

Csatlakozás az IoT Hubhoz

Csatlakozás megosztott hozzáférési szabályzattal

Csatlakozás a Microsoft Entra használatával

A Microsoft Entra alkalmazás konfigurálása

Hitelesítés DefaultAzureCredential használatával

Hitelesítés a ClientSecretCredentialBuilder használatával

Egyéb hitelesítési osztályok

Kódminták

Közvetlen metódusfrissítési feladat ütemezése

Ikereszköz-frissítési feladat ütemezése

Feladat monitorozása

Feladat állapotának lekérdezése

Példa SDK ütemezési feladatra

Áttekintés

Csomag telepítése

Importálási utasítások

Csatlakozás az IoT Hubhoz

Csatlakozás megosztott hozzáférési szabályzattal

Csatlakozás a Microsoft Entra használatával

A Microsoft Entra alkalmazás konfigurálása

Hitelesítés DefaultAzureCredential használatával

Kódminta

Közvetlen metódusfeladat ütemezése

Ikereszköz-frissítési feladat ütemezése

Feladat monitorozása

SDK-ütemezési feladatok példái

Áttekintés

Szolgáltatás SDK-csomag telepítése

Csatlakozás az IoT Hubhoz

Csatlakozás megosztott hozzáférési szabályzattal

Csatlakozás a Microsoft Entra használatával

A Microsoft Entra alkalmazás konfigurálása

Hitelesítés DefaultAzureCredential használatával

Kódminták

Közvetlen metódusfeladat létrehozása

Ikereszköz-frissítési feladat ütemezése

Munka megfigyelése

Példa SDK ütemezési feladatra

Visszajelzés

További források