Sdílet prostřednictvím

Plánování a vysílání úloh

V tomto článku se dozvíte, jak vytvořit kód back-endové aplikace pro plánování a vysílání úloh.

Pomocí služby Azure IoT Hub můžete plánovat a sledovat úlohy, které aktualizují až miliony zařízení pro tyto operace:

  • Vyvolání přímých metod
  • Aktualizace digitálních dvojníků zařízení

Úloha obsahuje jednu z těchto akcí a sleduje průběh vůči sadě zařízení definované dotazem na dvojče zařízení. Back-endová aplikace může například pomocí úlohy vyvolat přímou metodu na 10 000 zařízeních, která zařízení restartuje. Zadáte sadu zařízení dotazem na dvojče zařízení a naplánujete úlohu ke spuštění v budoucnu. Úloha monitoruje průběh, když každé zařízení přijme a spustí přímou metodu restartování.

Další informace o každé z těchto funkcí najdete tady:

Poznámka:

Funkce popsané v tomto článku jsou k dispozici pouze na úrovni Standard služby IoT Hub. Další informace o úrovních Basic a Standard/Free IoT Hub najdete v tématu Volba správné úrovně a velikosti služby IoT Hub pro vaše řešení.

Poznámka:

Tento článek je určený k doplnění vzorků SDK Azure IoT, na které je odkazováno v tomto článku. Nástroje sady SDK můžete použít k sestavení zařízení i back-endových aplikací.

Požadavky

  • IoT centrum

  • Zaregistrované zařízení

  • Pokud vaše aplikace používá protokol MQTT, ujistěte se, že je v bráně firewall otevřený port 8883. Protokol MQTT komunikuje přes port 8883. Tento port může být blokovaný v některých podnikových a vzdělávacích síťových prostředích. Další informace a způsoby řešení tohoto problému najdete v tématu Připojení ke službě IoT Hub (MQTT).

  • Vyžaduje Visual Studio.

Přehled

Tento článek popisuje, jak pomocí sady Azure IoT SDK pro platformu .NET vytvořit kód aplikace back-endové služby pro naplánování úlohy k vyvolání přímého volání metody nebo provedení aktualizace dvojčete zařízení u jednoho nebo více zařízení.

Přidejte balíček NuGet pro službu

Aplikace back-endových služeb vyžadují balíček NuGet Microsoft.Azure.Devices .

Použití příkazů

Přidejte následující příkazy using.

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

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

Připojení ke službě IoT Hub

Back-endovou službu můžete ke službě IoT Hub připojit pomocí následujících metod:

  • Zásady sdíleného přístupu
  • Microsoft Entra

Důležité

Tento článek obsahuje postup připojení ke službě pomocí sdíleného přístupového podpisu. Tato metoda ověřování je vhodná pro testování a vyhodnocení, ale ověřování ve službě pomocí MICROSOFT Entra ID nebo spravovaných identit je bezpečnější přístup. Další informace najdete v tématu Osvědčené postupy zabezpečení zabezpečení řešení > IoT v cloudu.

Připojení pomocí zásad sdíleného přístupu

Připojte back-endovou aplikaci k zařízení pomocí createFromConnectionString.

Tento článek popisuje back-endový kód, který může naplánovat úlohu pro vyvolání přímé metody, naplánování úlohy pro aktualizaci dvojčete zařízení a monitorování průběhu úlohy pro jedno nebo více zařízení. K provedení těchto operací potřebuje vaše služba oprávnění ke čtení registru a zápisu do registru. Ve výchozím nastavení se každé centrum IoT vytvoří se zásadami sdíleného přístupu nazvanými registryReadWrite, které udělí tato oprávnění.

Další informace o zásadách sdíleného přístupu najdete v tématu Řízení přístupu ke službě IoT Hub pomocí sdílených přístupových podpisů.

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

Připojení pomocí Microsoft Entra

Back-endová aplikace, která používá Microsoft Entra, se musí před připojením ke službě IoT Hub úspěšně ověřit a získat přihlašovací údaje tokenu zabezpečení. Tento token se předá metodě připojení IoT Hubu. Obecné informace o nastavení a používání Microsoft Entra pro IoT Hub naleznete v tématu Řízení přístupu ke službě IoT Hub pomocí Microsoft Entra ID.

Konfigurace aplikace Microsoft Entra

Musíte nastavit aplikaci Microsoft Entra, která je nakonfigurovaná pro vaše upřednostňované přihlašovací údaje ověřování. Aplikace obsahuje parametry, jako je tajný klíč klienta, který používá back-endová aplikace k ověření. Dostupné konfigurace ověřování aplikací:

  • Klientské tajemství
  • Certifikát
  • Pověření federované identity

Aplikace Microsoft Entra mohou v závislosti na provedených operacích vyžadovat určitá oprávnění role. K povolení přístupu ke čtení a zápisu k dvojicím zařízení a modulů IoT Hub je například potřeba Přispěvatel dvojčete IoT Hub. Pro více informací si přečtěte Správa přístupu ke službě IoT Hub pomocí přiřazení rolí Azure RBAC.

Další informace o nastavení aplikace Microsoft Entra najdete v tématu Rychlý start: Registrace aplikace na platformě Microsoft Identity Platform.

Ověřování pomocí DefaultAzureCredential

Nejjednodušší způsob, jak použít Microsoft Entra k ověření serverové aplikace, je využití DefaultAzureCredential, ale v produkčním prostředí je doporučeno použít jinou metodu, včetně konkrétního TokenCredential nebo zjednodušeného ChainedTokenCredential. Pro zjednodušení popisuje tato část ověřování pomocí DefaultAzureCredential a tajný klíč klienta. Další informace o výhodách a nevýhodách použití naleznete v pokynech k použití DefaultAzureCredentialpro DefaultAzureCredential.

DefaultAzureCredential podporuje různé mechanismy ověřování a určuje odpovídající typ přihlašovacích údajů na základě prostředí, ve které se provádí. Pokusí se použít více typů přihlašovacích údajů v pořadí, dokud nenajde funkční přihlašovací údaje.

Microsoft Entra vyžaduje tyto balíčky NuGet a odpovídající using příkazy:

  • Azure.Core
  • Azure.Identity
using Azure.Core;
using Azure.Identity;

V tomto příkladu se do proměnných prostředí přidají tajný klíč klienta, klientské ID a ID tenanta pro registraci aplikace Microsoft Entra. Tyto proměnné prostředí DefaultAzureCredential používá k ověření aplikace. Výsledkem úspěšného ověřování Microsoft Entra je zabezpečený tokenový přihlašovací údaj, který je předán do metody připojení IoT Hubu.

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

Výsledný tokenCredential se pak dá předat metodě připojení ke službě IoT Hub pro libovolného klienta sady SDK, který přijímá přihlašovací údaje Microsoft Entra:

V tomto příkladu je TokenCredential předán do ServiceClient.Create pro vytvoření objektu připojení ServiceClient.

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

V tomto příkladu je TokenCredential předán do RegistryManager.Create, aby se vytvořil objekt RegistryManager.

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);
Ukázka kódu

Pro ukázku ověřování služby Microsoft Entra se podívejte na ukázku ověřování na základě rolí.

Naplánujte úlohu přímé metody

Pomocí ScheduleDeviceMethodAsync naplánujte úlohu, která spustí přímou metodu na jednom nebo několika zařízeních.

Pomocí CloudToDeviceMethod objektu zadejte název přímé metody a hodnoty časového limitu připojení zařízení.

Příklad:

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

Tento příklad naplánuje úlohu pro přímou metodu s názvem LockDoor na jednom zařízení s názvem Device-1. Zařízení zahrnutá v naplánované úloze obsahují druhý parametr jako podmínku dotazu. Další informace o podmínkách dotazu najdete v dotazovacím jazyce služby IoT Hub pro dvojčata zařízení a modulů, úlohy a směrování zpráv.

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

Naplánování úlohy aktualizace dvojčete zařízení

Pomocí ScheduleTwinUpdateAsync naplánujte nové požadované vlastnosti dvojčete zařízení a úlohu aktualizace značek, která se spustí na jednom nebo více zařízeních.

Nejprve vytvořte a naplňte objekt Twin zařízení pro aktualizaci. Příklad:

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;

V dalším kroku zavolejte ScheduleTwinUpdateAsync. Zadejte zařízení, která se mají aktualizovat jako dotaz v druhém parametru. Další informace o podmínkách dotazu najdete v dotazovacím jazyce služby IoT Hub pro dvojčata zařízení a modulů, úlohy a směrování zpráv.

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

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

Monitorovat úlohu

Ke sledování stavu úlohy pro konkrétní ID úlohy použijte GetJobAsync .

Tento příklad pravidelně kontroluje stav úlohy podle ID úlohy, dokud se stav úlohy nedokončí nebo se nezdaří. Příklad:

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

Příklady úloh plánu sady SDK

Sada Azure IoT SDK pro .NET poskytuje funkční ukázky aplikací služeb, které zpracovávají úlohy plánování úloh. Další informace naleznete v tématu:

  • Vyžaduje Java SE Development Kit 8. Ujistěte se, že jste v části Dlouhodobá podpora vybrali Javu 8 a přejděte ke stažení sady JDK 8.

Přehled

Tento článek popisuje, jak pomocí sady Azure IoT SDK pro Javu vytvořit kód aplikace back-endové služby k naplánování úlohy pro vyvolání přímé metody nebo provedení aktualizace dvojčete zařízení na jednom nebo více zařízeních.

Příkazy importu služby

Třída JobClient obsahuje metody, které mohou služby použít k plánování úloh.

Pro přístup k sadě Azure IoT SDK pro Javu použijte následující příkazy importu služby.

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;

Připojení ke službě IoT Hub

Back-endovou službu můžete ke službě IoT Hub připojit pomocí následujících metod:

  • Zásady sdíleného přístupu
  • Microsoft Entra

Důležité

Tento článek obsahuje postup připojení ke službě pomocí sdíleného přístupového podpisu. Tato metoda ověřování je vhodná pro testování a vyhodnocení, ale ověřování ve službě pomocí MICROSOFT Entra ID nebo spravovaných identit je bezpečnější přístup. Další informace najdete v tématu Osvědčené postupy zabezpečení zabezpečení řešení > IoT v cloudu.

Připojení pomocí zásad sdíleného přístupu

K vytvoření připojení ke službě IoT Hub použijte konstruktor JobClient . Objekt JobClient zpracovává komunikaci s centrem IoT.

Tento článek popisuje back-endový kód, který může naplánovat úlohu pro vyvolání přímé metody, naplánování úlohy pro aktualizaci dvojčete zařízení a monitorování průběhu úlohy pro jedno nebo více zařízení. K provedení těchto operací potřebuje vaše služba oprávnění ke čtení registru a zápisu do registru. Ve výchozím nastavení se každé centrum IoT vytvoří se zásadami sdíleného přístupu nazvanými registryReadWrite, které udělí tato oprávnění.

Další informace o zásadách sdíleného přístupu najdete v tématu Řízení přístupu ke službě IoT Hub pomocí sdílených přístupových podpisů.

Příklad:

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

Připojení pomocí Microsoft Entra

Back-endová aplikace, která používá Microsoft Entra, se musí před připojením ke službě IoT Hub úspěšně ověřit a získat přihlašovací údaje tokenu zabezpečení. Tento token se předá metodě připojení IoT Hubu. Obecné informace o nastavení a používání Microsoft Entra pro IoT Hub naleznete v tématu Řízení přístupu ke službě IoT Hub pomocí Microsoft Entra ID.

Pro přehled ověřování pro Java SDK, podívejte se na Ověřování Azure s Java a Azure Identity.

Pro zjednodušení se tato část zaměřuje na popis ověřování pomocí tajného klíče klienta.

Konfigurace aplikace Microsoft Entra

Musíte nastavit aplikaci Microsoft Entra, která je nakonfigurovaná pro vaše upřednostňované přihlašovací údaje ověřování. Aplikace obsahuje parametry, jako je tajný klíč klienta, který používá back-endová aplikace k ověření. Dostupné konfigurace ověřování aplikací:

  • Klientské tajemství
  • Certifikát
  • Pověření federované identity

Aplikace Microsoft Entra mohou v závislosti na provedených operacích vyžadovat určitá oprávnění role. K povolení přístupu ke čtení a zápisu k dvojicím zařízení a modulů IoT Hub je například potřeba Přispěvatel dvojčete IoT Hub. Pro více informací si přečtěte Správa přístupu ke službě IoT Hub pomocí přiřazení rolí Azure RBAC.

Další informace o nastavení aplikace Microsoft Entra najdete v tématu Rychlý start: Registrace aplikace na platformě Microsoft Identity Platform.

Ověřování pomocí DefaultAzureCredential

Nejjednodušší způsob, jak použít Microsoft Entra k ověření serverové aplikace, je využití DefaultAzureCredential, ale v produkčním prostředí je doporučeno použít jinou metodu, včetně konkrétního TokenCredential nebo zjednodušeného ChainedTokenCredential. Další informace o výhodách a nevýhodách použití DefaultAzureCredentialnajdete v řetězcích přihlašovacích údajů v klientské knihovně Azure Identity pro Javu.

DefaultAzureCredential podporuje různé mechanismy ověřování a určuje odpovídající typ přihlašovacích údajů na základě prostředí, ve které se provádí. Pokusí se použít více typů přihlašovacích údajů v pořadí, dokud nenajde funkční přihlašovací údaje.

Přihlašovací údaje aplikace Microsoft Entra můžete ověřit pomocí defaultAzureCredentialBuilder. Uložte parametry připojení, jako jsou tenantID, tajný klíč klienta, ID klienta a hodnoty tajných kódů klienta, jako proměnné prostředí. Jakmile je TokenCredential vytvořen, předejte ho jako parametr 'credential' do ServiceClient nebo jiného konstruktoru.

V tomto příkladu DefaultAzureCredentialBuilder se pokusí ověřit připojení ze seznamu popsaného v části DefaultAzureCredential. Výsledkem úspěšného ověření Microsoft Entra je token zabezpečení, který je předán konstruktoru, jako ServiceClient.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();
Ověřování pomocí ClientSecretCredentialBuilder

Pomocí ClientSecretCredentialBuilder můžete vytvořit přihlašovací údaje pomocí tajných informací klienta. Pokud je tato metoda úspěšná, vrátí tokenCredential , který lze předat ServiceClient nebo jinému tvůrci jako parametr credential.

V tomto příkladu byly do proměnných prostředí přidány hodnoty tajného klíče klienta, ID klienta a ID tenanta pro registraci aplikace Microsoft Entra. Tyto proměnné prostředí jsou používány ClientSecretCredentialBuilder ke generování přihlašovacích údajů.

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();
Jiné třídy ověřování

Sada Java SDK také obsahuje tyto třídy, které ověřují back-endovou aplikaci pomocí Microsoft Entra:

Ukázky kódu

Pracovní ukázky ověřování služby Microsoft Entra najdete v ukázce ověřování na základě rolí.

Naplánování úlohy aktualizace přímé metody

Pomocí scheduleDeviceMethod spusťte přímou metodu na jednom nebo několika zařízeních.

Tato ukázková metoda naplánuje úlohu pro přímou metodu s názvem lockDoor na zařízení s názvem 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());
}

Naplánujte úlohu aktualizace dvojčete zařízení

Pomocí scheduleUpdateTwin naplánujte úlohu, která spustí aktualizaci dvojčete zařízení na jednom nebo několika zařízeních.

Nejprve si připravte záznam DeviceTwinDevice na aktualizaci zařízení dvojče. Příklad:

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

Pak zavolejte scheduleUpdateTwin a naplánujte úlohu aktualizace. Příklad:

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

Monitorovat úlohu

Pomocí funkce getJob můžete načíst informace o úloze na základě konkrétního ID úlohy. getJob vrátí JobResult objekt, který obsahuje metody a vlastnosti, které můžete použít ke kontrole informací o úloze včetně stavu spuštění.

Příklad:

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

Zjistit stav úlohy

K dotazování stavu úlohy pro jednu nebo více úloh použijte queryDeviceJob .

Příklad:

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říklad úlohy plánování sady SDK

Sada Azure IoT SDK pro Javu poskytuje funkční ukázku aplikace služby, která zpracovává úlohy plánování úloh. Další informace naleznete v části Ukázkový klient úloh.

  • Python SDK – Doporučuje se Python verze 3.7 nebo novější . Ujistěte se, že používáte 32bitovou, nebo 64bitovou instalaci podle požadavků vašeho nastavení. Při vyzvání během instalace nezapomeňte přidat Python do proměnné prostředí specifické pro vaši platformu.

Přehled

Tento článek popisuje, jak pomocí sady Azure IoT SDK pro Python vytvořit kód aplikace back-endové služby pro naplánování úlohy, která spustí přímou metodu nebo provede aktualizaci požadovaných vlastností dvojčete zařízení na jednom či více zařízeních.

Instalace balíčku

Aby bylo možné vytvářet aplikace back-endové služby, musí být nainstalovaná knihovna azure-iot-hub .

pip install azure-iot-hub

Příkazy importu

Třída IoTHubJobManager zveřejňuje všechny metody potřebné k vytvoření back-endové aplikace pro plánování úloh ze služby.

Přidejte následující prohlášení import.

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

Připojení ke službě IoT Hub

Back-endovou službu můžete ke službě IoT Hub připojit pomocí následujících metod:

  • Zásady sdíleného přístupu
  • Microsoft Entra

Důležité

Tento článek obsahuje postup připojení ke službě pomocí sdíleného přístupového podpisu. Tato metoda ověřování je vhodná pro testování a vyhodnocení, ale ověřování ve službě pomocí MICROSOFT Entra ID nebo spravovaných identit je bezpečnější přístup. Další informace najdete v tématu Osvědčené postupy zabezpečení zabezpečení řešení > IoT v cloudu.

Připojení pomocí zásad sdíleného přístupu

Připojte se ke službě IoT Hub pomocí from_connection_string.

Tento článek popisuje back-endový kód, který může naplánovat úlohu pro vyvolání přímé metody, naplánování úlohy pro aktualizaci dvojčete zařízení a monitorování průběhu úlohy pro jedno nebo více zařízení. K provedení těchto operací potřebuje vaše služba oprávnění ke čtení registru a zápisu do registru. Ve výchozím nastavení se každé centrum IoT vytvoří se zásadami sdíleného přístupu nazvanými registryReadWrite, které udělí tato oprávnění.

Další informace o zásadách sdíleného přístupu najdete v tématu Řízení přístupu ke službě IoT Hub pomocí sdílených přístupových podpisů.

Příklad:

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

Připojení pomocí Microsoft Entra

Back-endová aplikace, která používá Microsoft Entra, se musí před připojením ke službě IoT Hub úspěšně ověřit a získat přihlašovací údaje tokenu zabezpečení. Tento token se předá metodě připojení IoT Hubu. Obecné informace o nastavení a používání Microsoft Entra pro IoT Hub naleznete v tématu Řízení přístupu ke službě IoT Hub pomocí Microsoft Entra ID.

Konfigurace aplikace Microsoft Entra

Musíte nastavit aplikaci Microsoft Entra, která je nakonfigurovaná pro vaše upřednostňované přihlašovací údaje ověřování. Aplikace obsahuje parametry, jako je tajný klíč klienta, který používá back-endová aplikace k ověření. Dostupné konfigurace ověřování aplikací:

  • Klientské tajemství
  • Certifikát
  • Pověření federované identity

Aplikace Microsoft Entra mohou v závislosti na provedených operacích vyžadovat určitá oprávnění role. K povolení přístupu ke čtení a zápisu k dvojicím zařízení a modulů IoT Hub je například potřeba Přispěvatel dvojčete IoT Hub. Pro více informací si přečtěte Správa přístupu ke službě IoT Hub pomocí přiřazení rolí Azure RBAC.

Další informace o nastavení aplikace Microsoft Entra najdete v tématu Rychlý start: Registrace aplikace na platformě Microsoft Identity Platform.

Ověřování pomocí DefaultAzureCredential

Nejjednodušší způsob, jak použít Microsoft Entra k ověření serverové aplikace, je využití DefaultAzureCredential, ale v produkčním prostředí je doporučeno použít jinou metodu, včetně konkrétního TokenCredential nebo zjednodušeného ChainedTokenCredential. Pro zjednodušení popisuje tato část ověřování pomocí DefaultAzureCredential a tajný klíč klienta. Další informace o výhodách a nevýhodách použití naleznete v pokynech k použití DefaultAzureCredentialpro DefaultAzureCredential.

DefaultAzureCredential podporuje různé mechanismy ověřování a určuje odpovídající typ přihlašovacích údajů na základě prostředí, ve které se provádí. Pokusí se použít více typů přihlašovacích údajů v pořadí, dokud nenajde funkční přihlašovací údaje.

Microsoft Entra vyžaduje tyto balíčky NuGet a odpovídající using příkazy:

  • Azure.Core
  • Azure.Identity
using Azure.Core;
using Azure.Identity;

V tomto příkladu se do proměnných prostředí přidá tajný klíč klienta registrace aplikace Microsoft Entra, ID klienta a ID tenanta. Tyto proměnné prostředí DefaultAzureCredential používá k ověření aplikace. Výsledkem úspěšného ověřování Microsoft Entra je zabezpečený tokenový přihlašovací údaj, který je předán do metody připojení IoT Hubu.

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

Výsledný tokenCredential se pak dá předat metodě připojení ke službě IoT Hub pro libovolného klienta sady SDK, který přijímá přihlašovací údaje Microsoft Entra:

V tomto příkladu je TokenCredential předán do ServiceClient.Create pro vytvoření objektu připojení ServiceClient.

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

V tomto příkladu je TokenCredential předán do RegistryManager.Create, aby se vytvořil objekt RegistryManager.

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);
Ukázka kódu

Pro ukázku ověřování služby Microsoft Entra se podívejte na ukázku ověřování na základě rolí.

Naplánujte úlohu přímé metody

Pomocí create_scheduled_job naplánujte novou přímou metodu pro spuštění přímé metody na jednom nebo několika zařízeních:

create_scheduled_job poznámky k parametru:

  • job_id musí být jedinečné.
  • Nastavte type na hodnotu scheduleDeviceMethod.
  • Pomocí cloud_to_device_method nastavte název přímé metody a datovou část.
  • Slouží max_execution_time_in_seconds k určení doby provádění v sekundách.
  • Slouží query_condition k určení zařízení, která mají být zahrnuta pro volání přímé metody. Další informace o podmínkách dotazu najdete v dotazovacím jazyce služby IoT Hub pro dvojčata zařízení a modulů, úlohy a směrování zpráv.

Příklad:

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)

Naplánování úlohy aktualizace dvojčete zařízení

Pomocí create_scheduled_job vytvořte novou úlohu pro spuštění aktualizace požadovaných vlastností dvojčete zařízení na jednom nebo několika zařízeních.

create_scheduled_job poznámky k parametru:

  • job_id musí být jedinečné.
  • Nastavte type na hodnotu scheduleUpdateTwin.
  • Pomocí update_twin nastavte název přímé metody a datovou část.
  • Slouží max_execution_time_in_seconds k určení doby provádění v sekundách.
  • Slouží query_condition k určení podmínky pro jedno nebo více zařízení, která mají přímé volání metody. Další informace o podmínkách dotazu najdete v dotazovacím jazyce služby IoT Hub pro dvojčata zařízení a modulů, úlohy a směrování zpráv.

Příklad:

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)

Monitorovat úlohu

Pomocí get_scheduled_job načtěte podrobnosti o konkrétní úloze ve službě IoT Hub.

Tento příklad zkontroluje stav úlohy pro konkrétní ID úlohy každých pět sekund, dokud úloha nebude dokončena.

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)

Příklady úloh plánu sady SDK

Sada Azure IoT SDK pro Python poskytuje funkční ukázky aplikací služeb, které zpracovávají úlohy plánování úloh. Další informace naleznete v tématu:

  • Vyžaduje Node.js verze 10.0.x nebo novější.

Přehled

Tento článek popisuje, jak pomocí sady Azure IoT SDK pro Node.js vytvořit aplikační kód pro backendovou službu ke spuštění úlohy za účelem inicializace přímé metody nebo provedení aktualizace dvojčete zařízení na jednom či více zařízeních.

Nainstalujte balíček SDK služby

Spuštěním tohoto příkazu nainstalujte azure-iothub na vývojový počítač:

npm install azure-iothub --save

Třída JobClient zveřejňuje všechny metody potřebné k interakci s plánováním úloh z back-endové aplikace.

Připojení ke službě IoT Hub

Back-endovou službu můžete ke službě IoT Hub připojit pomocí následujících metod:

  • Zásady sdíleného přístupu
  • Microsoft Entra

Důležité

Tento článek obsahuje postup připojení ke službě pomocí sdíleného přístupového podpisu. Tato metoda ověřování je vhodná pro testování a vyhodnocení, ale ověřování ve službě pomocí MICROSOFT Entra ID nebo spravovaných identit je bezpečnější přístup. Další informace najdete v tématu Osvědčené postupy zabezpečení zabezpečení řešení > IoT v cloudu.

Připojení pomocí zásad sdíleného přístupu

Použijte fromConnectionString pro připojení ke službě IoT Hub.

Tento článek popisuje back-endový kód, který může naplánovat úlohu pro vyvolání přímé metody, naplánování úlohy pro aktualizaci dvojčete zařízení a monitorování průběhu úlohy pro jedno nebo více zařízení. K provedení těchto operací potřebuje vaše služba oprávnění ke čtení registru a zápisu do registru. Ve výchozím nastavení se každé centrum IoT vytvoří se zásadami sdíleného přístupu nazvanými registryReadWrite, které udělí tato oprávnění.

Další informace o zásadách sdíleného přístupu najdete v tématu Řízení přístupu ke službě IoT Hub pomocí sdílených přístupových podpisů.

Příklad:

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

Připojení pomocí Microsoft Entra

Back-endová aplikace, která používá Microsoft Entra, se musí před připojením ke službě IoT Hub úspěšně ověřit a získat přihlašovací údaje tokenu zabezpečení. Tento token se předá metodě připojení IoT Hubu. Obecné informace o nastavení a používání Microsoft Entra pro IoT Hub naleznete v tématu Řízení přístupu ke službě IoT Hub pomocí Microsoft Entra ID.

Přehled ověřování Node.js SDK najdete v těchto tématech:

Konfigurace aplikace Microsoft Entra

Musíte nastavit aplikaci Microsoft Entra, která je nakonfigurovaná pro vaše upřednostňované přihlašovací údaje ověřování. Aplikace obsahuje parametry, jako je tajný klíč klienta, který používá back-endová aplikace k ověření. Dostupné konfigurace ověřování aplikací:

  • Klientské tajemství
  • Certifikát
  • Pověření federované identity

Aplikace Microsoft Entra mohou v závislosti na provedených operacích vyžadovat určitá oprávnění role. K povolení přístupu ke čtení a zápisu k dvojicím zařízení a modulů IoT Hub je například potřeba Přispěvatel dvojčete IoT Hub. Pro více informací si přečtěte Správa přístupu ke službě IoT Hub pomocí přiřazení rolí Azure RBAC.

Další informace o nastavení aplikace Microsoft Entra najdete v tématu Rychlý start: Registrace aplikace na platformě Microsoft Identity Platform.

Ověřování pomocí DefaultAzureCredential

Nejjednodušší způsob, jak použít Microsoft Entra k ověření serverové aplikace, je využití DefaultAzureCredential, ale v produkčním prostředí je doporučeno použít jinou metodu, včetně konkrétního TokenCredential nebo zjednodušeného ChainedTokenCredential. Pro zjednodušení popisuje tato část ověřování pomocí DefaultAzureCredential a tajný klíč klienta. Další informace o výhodách a nevýhodách použití DefaultAzureCredentialnajdete v řetězcích přihlašovacích údajů v klientské knihovně Azure Identity pro JavaScript.

DefaultAzureCredential podporuje různé mechanismy ověřování a určuje odpovídající typ přihlašovacích údajů na základě prostředí, ve které se provádí. Pokusí se použít více typů přihlašovacích údajů v pořadí, dokud nenajde funkční přihlašovací údaje.

Microsoft Entra vyžaduje tento balíček:

npm install --save @azure/identity

V tomto příkladu byly do proměnných prostředí přidány tajný klíč registrace aplikace Microsoft Entra, ID klienta a ID tenanta. Tyto proměnné prostředí DefaultAzureCredential používá k ověření aplikace. Výsledkem úspěšného ověřování Microsoft Entra je zabezpečený tokenový přihlašovací údaj, který je předán do metody připojení IoT Hubu.

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

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

Výsledný token přihlašovacích údajů lze následně předat do fromTokenCredential, aby se připojil ke službě IoT Hub pro kterékoli klienty sady SDK, které podporují přihlašovací údaje Microsoft Entra.

fromTokenCredential vyžaduje dva parametry:

  • Adresa URL služby Azure – Adresa URL služby Azure by měla být ve formátu {Your Entra domain URL}.azure-devices.net bez předpony https:// . Například MyAzureDomain.azure-devices.net.
  • Token přihlašovacích údajů Azure

V tomto příkladu se přihlašovací údaje Azure získávají pomocí DefaultAzureCredential. Adresa URL domény Azure a přihlašovací údaje se pak zadají do Registry.fromTokenCredential pro vytvoření připojení ke službě 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);
Ukázky kódu

Pracovní ukázky ověřování služby Microsoft Entra najdete v příkladech identit Azure.

Vytvořte úlohu přímé metody

Pomocí scheduleDeviceMethod naplánujte úlohu tak, aby spustila přímou metodu na jednom nebo několika zařízeních.

Nejprve vytvořte proměnnou aktualizace přímé metody s názvem metody, datovou částí a informacemi o vypršení časového limitu odpovědi. Příklad:

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

Pak voláním scheduleDeviceMethod naplánujte úlohu volání přímé metody:

  • Každá úloha musí mít jedinečné ID úlohy. Toto ID úlohy můžete použít k monitorování úlohy, jak je popsáno v části Monitorování úlohy tohoto článku.
  • queryCondition Zadejte parametr pro vyhodnocení zařízení, na kterých se má úloha spouštět. Další informace o podmínkách dotazu najdete v dotazovacím jazyce služby IoT Hub pro dvojčata zařízení a modulů, úlohy a směrování zpráv.
  • jobResult Zkontrolujte zpětné volání pro výsledek plánu úlohy. Pokud byla úloha úspěšně naplánovaná, můžete monitorovat stav úlohy, jak je znázorněno v části Monitorování úlohy tohoto článku.

Příklad:

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

Naplánování úlohy aktualizace dvojčete zařízení

Pomocí scheduleTwinUpdate vytvořte novou úlohu pro spuštění aktualizace dvojčete zařízení na jednom nebo několika zařízeních.

Nejprve vytvořte proměnnou pro aktualizaci požadované vlastnosti digitálního dvojčete zařízení.

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

Potom voláním scheduleTwinUpdate naplánujte úlohu aktualizace požadované vlastnosti dvojčete zařízení:

  • Každá úloha musí mít jedinečné ID úlohy. Toto ID úlohy můžete použít k monitorování úlohy, jak je popsáno v části Monitorování úlohy tohoto článku.
  • queryCondition Zadejte parametr pro vyhodnocení zařízení, na kterých se má úloha spouštět. Další informace o podmínkách dotazu najdete v dotazovacím jazyce služby IoT Hub pro dvojčata zařízení a modulů, úlohy a směrování zpráv.
  • Zkontrolujte jobResult callback pro výsledek plánovaného úkolu. Pokud byla úloha úspěšně naplánovaná, můžete monitorovat stav úlohy, jak je znázorněno v části Monitorování úlohy tohoto článku.

Příklad:

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

Monitorovat úlohu

Pomocí funkce getJob můžete monitorovat stav úlohy pro konkrétní ID úlohy.

Tato ukázková funkce pravidelně kontroluje stav úlohy pro konkrétní ID úlohy, dokud se úloha nedokoní nebo se nezdaří.

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říklad úlohy plánování sady SDK

Sada Azure IoT SDK pro Node.js poskytuje funkční ukázku aplikace služby, která zpracovává úlohy plánování úloh. Další informace naleznete v tématu E2E test klienta práce.

  • Last updated on