Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
In diesem Artikel erfahren Sie, wie Sie Back-End-App-Code erstellen, um Aufträge zu planen und zu übertragen.
Verwenden Sie Azure IoT Hub, um Aufträge zu planen und zu verfolgen, die bis zu Millionen von Geräten für diese Vorgänge aktualisieren:
- Aufrufen direkter Methoden
- Gerätezwillinge aktualisiert
Ein Auftrag umschließt eine dieser Aktionen und verfolgt die Ausführung für eine Gruppe von Geräten nach, die anhand einer Gerätezwillingsabfrage definiert wird. Eine Back-End-App kann z.B. einen Auftrag verwenden, um eine direkte Methode auf 10.000 Geräten aufzurufen, die die Geräte neu startet. Sie geben die Gruppe von Geräten mit einer Gerätezwillingsabfrage ein und planen die Ausführung des Auftrags zu einem späteren Zeitpunkt. Der Auftrag überwacht den Fortschritt nach, während jedes der Geräte die direkte Methode zum Neustart empfängt und ausführt.
Weitere Informationen zu diesen Funktionen finden Sie unter:
- Gerätezwilling und Eigenschaften: Erste Schritte mit Gerätezwillingen und Verstehen und Verwenden von Gerätezwillingen in IoT Hub
- Direkte Methoden:IoT Hub-Entwicklerleitfaden – direkte Methoden
Hinweis
Die in diesem Artikel beschriebenen Features stehen nur im Standard-Tarif von IoT Hub zur Verfügung. Weitere Informationen zu den grundlegenden und standardmäßigen/kostenlosen IoT Hub-Ebenen finden Sie unter Auswählen der richtigen IoT Hub-Ebene und -Größe für Ihre Lösung.
Hinweis
Dieser Artikel soll die Beispiele der Azure IoT-SDKs ergänzen, auf die in diesem Artikel verwiesen wird. Sie können SDK Tools verwenden, um Geräte- und Back-End-Anwendungen zu erstellen.
Voraussetzungen
Ein IoT-Hub
Ein registriertes Gerät
Wenn Ihre Anwendung das MQTT-Protokoll verwendet, stellen Sie sicher, dass der Port 8883 in Ihrer Firewall geöffnet ist. Das MQTT-Protokoll kommuniziert über den Port 8883. In einigen Netzwerkumgebungen von Unternehmen oder Bildungseinrichtungen ist dieser Port unter Umständen blockiert. Weitere Informationen und Problemumgehungen finden Sie unter Herstellen einer Verbindung mit IoT Hub (MQTT).
- Erfordert Visual Studio
Übersicht
In diesem Artikel wird beschrieben, wie Sie das Azure IoT SDK für .NET verwenden, um Back-End-Dienstanwendungscode für einen Zeitplanauftrag zu erstellen, um eine direkte Methode aufzurufen oder ein Gerätezwillingsupdate auf einem oder mehreren Geräten durchzuführen.
NuGet-Servicepaket hinzufügen
Back-End-Dienstanwendungen erfordern das NuGet-Paket Microsoft.Azure.Devices.
Verwenden von Anweisungen
Fügen Sie die folgenden using-Anweisungen hinzu.
using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Shared;
using System.Threading;
using System.Threading.Tasks;
Herstellen einer Verbindung mit dem IoT-Hub
Sie können einen Back-End-Dienst mit IoT Hub mithilfe der folgenden Methoden verbinden:
- Richtlinie für gemeinsamen Zugriff
- Microsoft Entra
Wichtig
Dieser Artikel enthält Schritte zum Herstellen einer Verbindung mit einem Dienst mithilfe einer Shared Access Signature. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung bei einem Dienst mit Microsoft Entra ID oder verwalteten Identitäten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen > Cloud-Sicherheit.
Herstellen einer Verbindung mithilfe einer SAS-Richtlinie
Verbinden Sie eine Back-End-Anwendung mit einem Gerät mithilfe von CreateFromConnectionString.
In diesem Artikel wird Back-End-Code beschrieben, mit dem Sie einen Auftrag zum Aufrufen einer direkten Methode planen können, einen Auftrag zum Aktualisieren eines Gerätezwillings planen können und den Fortschritt eines Auftrags für ein oder mehrere Geräte überwachen können. Für diese Vorgänge benötigt Ihr Dienst die Berechtigungen Lesevorgänge in Registrierung und Schreibvorgänge in Registrierung. Standardmäßig wird jeder IoT-Hub mit einer SAS-Richtlinie namens registryReadWrite erstellt, die diese Berechtigungen erteilt.
Weitere Informationen zu Richtlinien für den gemeinsamen Zugriff finden Sie unter Steuern des Zugriffs auf IoT Hub mithilfe von Shared Access Signatures.
static JobClient jobClient;
static string connectionString = "{Shared access policy connection string}";
jobClient = JobClient.CreateFromConnectionString(connString);
Verbinden mit Microsoft Entra
Eine Backend-App, die Microsoft Entra verwendet, muss sich erfolgreich authentifizieren und eine Sicherheitstoken-Referenz erhalten, bevor sie eine Verbindung mit dem IoT Hub herstellt. Dieses Token wird an eine IoT Hub-Verbindungsmethode übergeben. Allgemeine Informationen zum Einrichten und Verwenden von Microsoft Entra für IoT Hub finden Sie unter Steuern des Zugriffs auf IoT Hub mithilfe von Microsoft Entra ID.
Konfigurieren der Microsoft Entra-App
Sie müssen eine Microsoft Entra-App einrichten, die für Ihre bevorzugten Authentifizierungsanmeldeinformationen konfiguriert ist. Die App enthält Parameter wie den geheimen Clientschlüssel, der von der Back-End-Anwendung zur Authentifizierung verwendet wird. Die verfügbaren Konfigurationen für die App-Authentifizierung sind:
- Geheimer Clientschlüssel
- Zertifikat
- Anmeldeinformationen für Verbundidentitäten
Microsoft Entra-Apps erfordern je nach ausgeführten Vorgängen möglicherweise bestimmte Rollenberechtigungen. Beispielsweise ist IoT Hub Twin Contributor erforderlich, um Lese- und Schreibzugriff auf ein IoT Hub-Gerät und Modulzwilling zu ermöglichen. Weitere Informationen finden Sie unter Verwalten des Zugriffs auf IoT Hub mithilfe der Azure RBAC-Rollenzuweisung.
Weitere Informationen zum Einrichten einer Microsoft Entra-App finden Sie in der Schnellstartanleitung: Registrieren einer Anwendung bei der Microsoft Identitäts-Plattform.
Authentifizieren mithilfe von DefaultAzureCredential
Die einfachste Möglichkeit, Microsoft Entra zum Authentifizieren einer Back-End-Anwendung zu verwenden, besteht darin, DefaultAzureCredential zu verwenden. In einer Produktionsumgebung wird jedoch empfohlen, eine andere Methode zu verwenden, einschließlich eines bestimmten TokenCredential
oder eines abgespeckten ChainedTokenCredential
. Der Einfachheit halber beschreibt dieser Abschnitt die Authentifizierung mit DefaultAzureCredential
und den geheimen Clientschlüssel. Weitere Informationen zu den Vor- und Nachteilen der Verwendung von DefaultAzureCredential
finden Sie unter Verwendungsleitfaden für DefaultAzureCredential.
DefaultAzureCredential
unterstützt verschiedene Authentifizierungsmechanismen und bestimmt den entsprechenden Anmeldeinformationstyp basierend auf der Umgebung, in der er ausgeführt wird. Es versucht, mehrere Anmeldeinformationstypen in einer Reihenfolge zu verwenden, bis sie eine funktionierende Anmeldeinformation findet.
Microsoft Entra erfordert diese NuGet-Pakete und entsprechende using
Anweisungen:
- Azure.Core
- Azure.Identity
using Azure.Core;
using Azure.Identity;
In diesem Beispiel werden der Clientschlüssel, die Client-ID und die Mandanten-ID der Microsoft Entra-App-Registrierung zu Umgebungsvariablen hinzugefügt. Diese Umgebungsvariablen werden von DefaultAzureCredential
verwendet, um die Anwendung zu authentifizieren. Das Ergebnis einer erfolgreichen Microsoft Entra-Authentifizierung ist eine Sicherheitstoken-Anmeldeinformation, die an eine IoT Hub-Verbindungsmethode übergeben wird.
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();
Das resultierende TokenCredential kann dann an eine Verbindung mit der IoT Hub-Methode für jeden SDK-Client übergeben werden, der Microsoft Entra-Anmeldeinformationen akzeptiert:
In diesem Beispiel wird TokenCredential
an ServiceClient.Create
übergeben, um ein ServiceClient-Verbindungsobjekt zu erstellen.
string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);
In diesem Beispiel wird TokenCredential
an RegistryManager.Create
übergeben, um ein RegistryManager-Objekt zu erstellen.
string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);
Codebeispiel
Ein funktionierendes Beispiel für die Microsoft Entra-Dienstauthentifizierung finden Sie im Beispiel für die rollenbasierte Authentifizierung.
Planen eines „direkte Methode“-Auftrags
Verwenden Sie ScheduleDeviceMethodAsync, um einen Auftrag zur Ausführung einer direkten Methode auf einem oder mehreren Geräten zu planen.
Verwenden Sie das CloudToDeviceMethod-Objekt, um den Namen der direkten Methode und die Timeout-Werte für die Geräteverbindung anzugeben.
Zum Beispiel:
// The CloudToDeviceMethod record specifies the direct method name and device connection time-out
CloudToDeviceMethod directMethod =
new CloudToDeviceMethod("LockDoor", TimeSpan.FromSeconds(5),
TimeSpan.FromSeconds(5));
In diesem Beispiel wird ein Auftrag für eine direkte Methode mit dem Namen „LockDoor“ auf einem Gerät namens „Device-1“ geplant. Die in dem geplanten Auftrag enthaltenen Geräte sind als zweiter Parameter in einer Abfragebedingung enthalten. Weitere Informationen zu Abfragebedingungen finden Sie unter IoT Hub-Abfragesprache für Geräte- und Modulzwillinge, Aufträge und Nachrichtenweiterleitung.
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);
Planen eines Auftrags zur Aktualisierung eines Gerätezwillings
Verwenden Sie ScheduleTwinUpdateAsync, um einen Auftrag zur Aktualisierung eines neuen Gerätezwillings mit den gewünschten Eigenschaften und Tags auf einem oder mehreren Geräten zu planen.
Erstellen Sie für das Gerät zunächst ein Twin-Objekt für die Aktualisierung und fügen Sie Informationen ein. Zum Beispiel:
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;
Rufen Sie als Nächstes ScheduleTwinUpdateAsync
auf. Geben Sie die zu aktualisierenden Geräte als Abfrage im zweiten Parameter an. Weitere Informationen zu Abfragebedingungen finden Sie unter IoT Hub-Abfragesprache für Geräte- und Modulzwillinge, Aufträge und Nachrichtenweiterleitung.
string twinJobId = Guid.NewGuid().ToString();
JobResponse createJobResponse = jobClient.ScheduleTwinUpdateAsync(
twinJobId,
$"DeviceId IN ['{deviceId}']",
twin,
DateTime.UtcNow,
(long)TimeSpan.FromMinutes(2).TotalSeconds).Result;
Überwachen eines Auftrags
Verwenden Sie GetJobAsync, um den Auftragsstatus für eine bestimmte Auftrags-ID zu überwachen.
In diesem Beispiel wird der Auftragsstatus für eine Job-ID regelmäßig überprüft, bis der Jobstatus abgeschlossen oder fehlgeschlagen ist. Zum Beispiel:
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));
Beispiele für einen SDK-Zeitplanauftrag
Das Azure IoT SDK für .NET bietet Arbeitsbeispiele von Dienst-Apps, die Aufgabenplanungsaufgaben verarbeiten. Weitere Informationen finden Sie unter:
- Erfordert das Java SE Development Kit 8. Wählen Sie unter Langfristiger Support unbedingt Java 8 aus, um zu den Downloads für JDK 8 zu gelangen.
Übersicht
In diesem Artikel wird beschrieben, wie Sie mit dem Azure IoT SDK für Java Back-End-Dienstanwendungscode erstellen, um einen Job zum Aufrufen einer direkten Methode oder zur Durchführung eines Gerätezwillings-Updates auf einem oder mehreren Geräten zu planen.
Dienst-Importanweisungen
Die Klasse JobClient enthält Methoden, mit denen Dienste Aufträge planen können.
Verwenden Sie die folgenden Dienst-Importanweisungen, um auf das Azure IoT SDK für Java zuzugreifen.
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;
Herstellen der Verbindung mit dem IoT Hub
Sie können einen Back-End-Dienst mit IoT Hub mithilfe der folgenden Methoden verbinden:
- Richtlinie für geteilten Zugriff
- Microsoft Entra
Wichtig
Dieser Artikel enthält Schritte zum Herstellen einer Verbindung mit einem Dienst mithilfe einer Shared Access Signature. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung bei einem Dienst mit Microsoft Entra ID oder verwalteten Identitäten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter "Bewährte Methoden für die Sicherheit von IoT-Lösungen > für Cloud-Sicherheit".
Verbindung herstellen mithilfe einer gemeinsamen Zugriffsrichtlinie
Verwenden Sie einen JobClient-Konstruktor, um die Verbindung mit IoT Hub herzustellen. Das JobClient
-Objekt führt die Kommunikation mit Ihrem IoT Hub durch.
In diesem Artikel wird Back-End-Code beschrieben, mit dem Sie einen Auftrag zum Aufrufen einer direkten Methode planen können, einen Auftrag zum Aktualisieren eines Gerätezwillings planen können und den Fortschritt eines Auftrags für ein oder mehrere Geräte überwachen können. Für diese Vorgänge benötigt Ihr Dienst die Berechtigungen Lesevorgänge in Registrierung und Schreibvorgänge in Registrierung. Standardmäßig wird jeder IoT-Hub mit einer gemeinsamen Zugriffsrichtlinie namens registryReadWrite erstellt, die diese Berechtigungen erteilt.
Weitere Informationen zu SAS-Richtlinien finden Sie unter Steuern des Zugriffs auf IoT Hub mithilfe von Shared Access Signatures.
Zum Beispiel:
public static final String iotHubConnectionString = "{Shared access policy connection string}";
JobClient jobClient = new JobClient(iotHubConnectionString);
Verbinden mit Microsoft Entra
Eine Back-End-App, die Microsoft Entra verwendet, muss erfolgreich authentifiziert werden und Anmeldeinformationen für Sicherheitstoken erhalten, bevor Sie eine Verbindung mit IoT Hub herstellen. Dieses Token wird an eine IoT Hub-Verbindungsmethode übergeben. Allgemeine Informationen zum Einrichten und Verwenden von Microsoft Entra für IoT Hub finden Sie unter Steuern des Zugriffs auf IoT Hub mithilfe von Microsoft Entra ID.
Eine Übersicht über die Java SDK-Authentifizierung finden Sie unter Azure-Authentifizierung mit Java und Azure Identität.
Der Einfachheit halber konzentriert sich dieser Abschnitt auf die Beschreibung der Authentifizierung mithilfe des geheimen Clientschlüssels.
Konfigurieren der Microsoft Entra-App
Sie müssen eine Microsoft Entra-App einrichten, die für Ihre bevorzugten Authentifizierungsanmeldeinformationen konfiguriert ist. Die App enthält Parameter wie den geheimen Clientschlüssel, der von der Back-End-Anwendung zur Authentifizierung verwendet wird. Die verfügbaren Konfigurationen für die App-Authentifizierung sind:
- Geheimer Clientschlüssel
- Zertifikat
- Anmeldeinformationen für Verbundidentitäten
Microsoft Entra-Apps erfordern je nach ausgeführten Vorgängen möglicherweise bestimmte Rollenberechtigungen. Beispielsweise ist IoT Hub Twin Contributor erforderlich, um Lese- und Schreibzugriff auf ein IoT Hub-Gerät und Modulzwilling zu ermöglichen. Weitere Informationen finden Sie unter Verwalten des Zugriffs auf IoT Hub mithilfe der Azure RBAC-Rollenzuweisung.
Weitere Informationen zum Einrichten einer Microsoft Entra-App finden Sie in der Schnellstartanleitung: Registrieren einer Anwendung bei der Microsoft Identitäts-Plattform.
Authentifizieren mithilfe von DefaultAzureCredential
Die einfachste Möglichkeit, Microsoft Entra zum Authentifizieren einer Back-End-Anwendung zu verwenden, besteht darin, DefaultAzureCredential zu nutzen. Für Produktionsumgebungen wird jedoch empfohlen, eine andere Methode zu verwenden, einschließlich einer spezifischen TokenCredential
oder einer abgespeckten ChainedTokenCredential
.
Weitere Informationen zu den Vor- und Nachteilen der Verwendung DefaultAzureCredential
finden Sie unter Anmeldeinformationsketten in der Azure Identity-Clientbibliothek für Java.
DefaultAzureCredential unterstützt verschiedene Authentifizierungsmechanismen und bestimmt den entsprechenden Anmeldeinformationstyp basierend auf der Umgebung, in der er ausgeführt wird. Es versucht, mehrere Anmeldeinformationstypen in einer Reihenfolge zu verwenden, bis sie eine funktionierende Anmeldeinformation findet.
Sie können Microsoft Entra-App-Anmeldeinformationen mithilfe von DefaultAzureCredentialBuilderauthentifizieren. Speichern Sie Verbindungsparameter wie geheime Clientschlüssel-Mandanten-ID, Client-ID und geheime Clientschlüsselwerte als Umgebungsvariablen. Nachdem TokenCredential
erstellt wurde, geben Sie sie an ServiceClient oder einen anderen Generator als Parameter „Anmeldeinformationen“ weiter.
In diesem Beispiel versucht DefaultAzureCredentialBuilder
eine Verbindung aus der in DefaultAzureCredential beschriebenen Liste zu authentifizieren. Das Ergebnis einer erfolgreichen Microsoft Entra-Authentifizierung ist eine Sicherheitstokenanmeldeinformation, die an einen Konstruktor wie ServiceClientübergeben wird.
TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();
Authentifizieren mit ClientSecretCredentialBuilder
Sie können ClientSecretCredentialBuilder verwenden, um Anmeldeinformationen mithilfe von geheimen Clientinformationen zu erstellen. Bei erfolgreicher Ausführung gibt diese Methode eine TokenCredential zurück, die als Parameter "Credential" an ServiceClient oder einen anderen Builder übergeben werden kann.
In diesem Beispiel wurden Clientschlüssel, Client-ID und Mandanten-ID-Werte der Microsoft Entra-App zu Umgebungsvariablen hinzugefügt. Diese Umgebungsvariablen werden von ClientSecretCredentialBuilder
verwendet, um die Anmeldeinformationen zu erstellen.
string clientSecretValue = System.getenv("AZURE_CLIENT_SECRET");
string clientID = System.getenv("AZURE_CLIENT_ID");
string tenantID = System.getenv("AZURE_TENANT_ID");
TokenCredential credential =
new ClientSecretCredentialBuilder()
.tenantId(tenantID)
.clientId(clientID)
.clientSecret(clientSecretValue)
.build();
Andere Authentifizierungsklassen
Das Java SDK enthält auch diese Klassen, die eine Back-End-App mit Microsoft Entra authentifizieren:
- AuthorizationCodeCredential
- AzureCliCredential
- AzureDeveloperCliCredential
- AzurePipelinesCredential
- ChainedTokenCredential
- ClientAssertionCredential
- ClientCertificateCredential
- DeviceCodeCredential
- EnvironmentCredential
- InteractiveBrowserCredential
- ManagedIdentityCredential
- OnBehalfOfCredential
Codebeispiele
Arbeitsbeispiele für die Microsoft Entra-Dienstauthentifizierung finden Sie im Beispielfür die rollenbasierte Authentifizierung.
Planen eines „direkte Methode“-Aktualisierungsauftrags
Verwenden Sie scheduleDeviceMethod, um eine direkte Methode auf einem oder mehreren Geräten auszuführen.
In dieser Beispielmethode wird ein Auftrag für eine direkte Methode mit dem Namen „lockDoor“ auf einem Gerät namens „Device-1“ geplant.
// 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());
}
Planen eines Auftrags zur Aktualisierung eines Gerätezwillings
Verwenden Sie scheduleUpdateTwin, um einen Auftrag zur Durchführung eines Gerätezwillings-Updates auf einem oder mehreren Geräten zu planen.
Bereiten Sie zunächst einen DeviceTwinDevice-Datensatz für das Zwillingsupdate des Geräts vor. Zum Beispiel:
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("*");
Rufen Sie dann scheduleUpdateTwin
auf, um den Updateauftrag zu planen. Zum Beispiel:
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());
}
Überwachen eines Auftrags
Verwenden Sie getJob, um Auftragsinformationen basierend auf einer bestimmten Auftrags-ID abzurufen. getJob
gibt ein JobResult-Objekt zurück, das Methoden und Eigenschaften enthält, mit denen Sie Auftragsinformationen einschließlich des Ausführungsstatus überprüfen können.
Zum Beispiel:
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;
}
Abfragen eines Auftragsstatus
Verwenden Sie queryDeviceJob, um den Auftragsstatus für einen oder mehrere Aufträge abzufragen.
Zum Beispiel:
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));
}
}
Beispiel für einen SDK-Zeitplanauftrag
Das Azure IoT SDK für Java bietet ein praktisches Beispiel für eine Dienst-App, die Auftragsplanungsaufgaben verarbeitet. Weitere Informationen finden Sie unter Job Client Beispiel.
- Python SDK – Python-Version 3.7 oder höher wird empfohlen. Stellen Sie je nach Einrichtung sicher, dass die 32-Bit- bzw. die 64-Bit-Installation verwendet wird. Fügen Sie Python Ihrer plattformspezifischen Umgebungsvariablen hinzu, wenn Sie während der Installation dazu aufgefordert werden.
Übersicht
In diesem Artikel wird beschrieben, wie Sie mit dem Azure IoT SDK für Python Back-End-Dienstanwendungscode erstellen, um einen Auftrag zu planen, der eine direkte Methode aufruft oder eine gewünschte Eigenschaftsaktualisierung eines Gerätezwillings auf einem oder mehreren Geräten durchführt.
Install-Package
Die Azure-iot-hub-Bibliothek muss installiert werden, um Back-End-Dienstanwendungen zu erstellen.
pip install azure-iot-hub
Importanweisungen
Die Klasse IoTHubJobManager macht alle Methoden verfügbar, die für die Erstellung einer Back-End-Anwendung zur Planung von Aufträgen aus dem Dienst erforderlich sind.
Fügen Sie die folgenden import
-Anweisungen hinzu.
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
Herstellen einer Verbindung mit dem IoT-Hub
Sie können einen Back-End-Dienst mit IoT Hub mithilfe der folgenden Methoden verbinden:
- Richtlinie für geteilten Zugriff
- Microsoft Entra
Wichtig
Dieser Artikel enthält Schritte zum Herstellen einer Verbindung mit einem Dienst mithilfe einer Shared Access Signature. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung bei einem Dienst mit Microsoft Entra ID oder verwalteten Identitäten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter "Bewährte Methoden für die Sicherheit von IoT-Lösungen" und "Cloud-Sicherheit">.
Herstellen einer Verbindung mithilfe einer SAS-Richtlinie
Stellen Sie mithilfe von from_connection_string eine Verbindung mit dem IoT-Hub her.
In diesem Artikel wird Back-End-Code beschrieben, mit dem Sie einen Auftrag zum Aufrufen einer direkten Methode planen können, einen Auftrag zum Aktualisieren eines Gerätezwillings planen können und den Fortschritt eines Auftrags für ein oder mehrere Geräte überwachen können. Für diese Vorgänge benötigt Ihr Dienst die Berechtigungen Leseberechtigungen in der Registrierung und Schreibberechtigungen in der Registrierung. Standardmäßig wird jeder IoT-Hub mit einer gemeinsamen Zugriffsrichtlinie namens registryReadWrite erstellt, die diese Berechtigungen erteilt.
Weitere Informationen zu SAS-Richtlinien finden Sie unter Steuer des Zugriffs auf IoT Hub mithilfe von Shared Access Signatures.
Zum Beispiel:
IoTHubConnectionString = "{Shared access policy connection string}"
iothub_job_manager = IoTHubJobManager.from_connection_string(IoTHubConnectionString)
Verbinden mit Microsoft Entra
Eine Back-End-App, die Microsoft Entra verwendet, muss sich erfolgreich authentifizieren und Sicherheitstoken-Zugangsdaten erhalten, bevor sie eine Verbindung mit dem IoT Hub herstellt. Dieses Token wird an eine IoT Hub-Verbindungsmethode übergeben. Allgemeine Informationen zum Einrichten und Verwenden von Microsoft Entra für IoT Hub finden Sie unter Steuern des Zugriffs auf IoT Hub mithilfe von Microsoft Entra ID.
Konfigurieren der Microsoft Entra-App
Sie müssen eine Microsoft Entra-App einrichten, die für Ihre bevorzugten Authentifizierungsanmeldeinformationen konfiguriert ist. Die App enthält Parameter wie den geheimen Clientschlüssel, der von der Back-End-Anwendung zur Authentifizierung verwendet wird. Die verfügbaren Konfigurationen für die App-Authentifizierung sind:
- Geheimer Clientschlüssel
- Zertifikat
- Anmeldeinformationen für Verbundidentitäten
Microsoft Entra-Apps erfordern je nach ausgeführten Vorgängen möglicherweise bestimmte Rollenberechtigungen. Beispielsweise ist IoT Hub Twin Contributor erforderlich, um Lese- und Schreibzugriff auf ein IoT Hub-Gerät und Modulzwilling zu ermöglichen. Weitere Informationen finden Sie unter Verwalten des Zugriffs auf IoT Hub mithilfe der Azure RBAC-Rollenzuweisung.
Weitere Informationen zum Einrichten einer Microsoft Entra-App finden Sie in der Schnellstartanleitung: Registrieren einer Anwendung bei der Microsoft Identitäts-Plattform.
Authentifizieren mithilfe von DefaultAzureCredential
Die einfachste Möglichkeit, Microsoft Entra zum Authentifizieren einer Back-End-Anwendung zu verwenden, besteht darin, DefaultAzureCredential zu nutzen. Es wird jedoch empfohlen, in einer Produktionsumgebung eine andere Methode zu wählen, einschließlich einer spezifischen TokenCredential
oder einer vereinfachten ChainedTokenCredential
. Der Einfachheit halber beschreibt dieser Abschnitt die Authentifizierung mit DefaultAzureCredential
und den geheimen Clientschlüssel. Weitere Informationen zu den Vor- und Nachteilen der Verwendung von DefaultAzureCredential
finden Sie unter Verwendungsleitfaden für DefaultAzureCredential.
DefaultAzureCredential
unterstützt verschiedene Authentifizierungsmechanismen und bestimmt den entsprechenden Anmeldeinformationstyp basierend auf der Umgebung, in der er ausgeführt wird. Es versucht, mehrere Anmeldeinformationstypen in einer Reihenfolge zu verwenden, bis sie eine funktionierende Anmeldeinformation findet.
Microsoft Entra erfordert diese NuGet-Pakete und entsprechende using
Anweisungen:
- Azure.Core
- Azure.Identity
using Azure.Core;
using Azure.Identity;
In diesem Beispiel werden der Clientschlüssel, die Client-ID und die Mandanten-ID der Microsoft Entra-App-Registrierung zu Umgebungsvariablen hinzugefügt. Diese Umgebungsvariablen werden von DefaultAzureCredential
verwendet, um die Anwendung zu authentifizieren. Das Ergebnis einer erfolgreichen Microsoft Entra-Authentifizierung ist eine Sicherheitstoken-Anmeldeinformation, die an eine IoT Hub-Verbindungsmethode übergeben wird.
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();
Das resultierende TokenCredential kann dann an eine Verbindung mit der IoT Hub-Methode für jeden SDK-Client übergeben werden, der Microsoft Entra-Anmeldeinformationen akzeptiert:
In diesem Beispiel wird TokenCredential
an ServiceClient.Create
übergeben, um ein ServiceClient-Verbindungsobjekt zu erstellen.
string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);
In diesem Beispiel wird TokenCredential
an RegistryManager.Create
übergeben, um ein RegistryManager-Objekt zu erstellen.
string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);
Codebeispiel
Ein funktionierendes Beispiel für die Microsoft Entra-Dienstauthentifizierung finden Sie im Beispiel für die rollenbasierte Authentifizierung.
Planen eines „direkte Methode“-Auftrags
Verwenden Sie create_scheduled_job, um eine neue direkte Methode für die Ausführung einer direkten Methode auf einem oder mehreren Geräten zu planen:
create_scheduled_job
Parameterhinweise:
job_id
muss eindeutig sein.- Legen Sie
type
aufscheduleDeviceMethod
fest. - Verwenden von
cloud_to_device_method
zum Festlegen des Namens und der Nutzdaten der direkten Methode - Verwenden von
max_execution_time_in_seconds
zum Angeben der Ausführungszeit in Sekunden - Verwenden Sie
query_condition
, um die Geräte anzugeben, die im Aufruf der direkten Methode eingeschlossen werden sollen. Weitere Informationen zu Abfragebedingungen finden Sie unter IoT Hub-Abfragesprache für Geräte- und Modulzwillinge, Aufträge und Nachrichtenweiterleitung.
Zum Beispiel:
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)
Planen eines Auftrags zur Aktualisierung eines Gerätezwillings
Verwenden Sie create_scheduled_job, um einen neuen Auftrag zu erstellen, mit dem die gewünschten Eigenschaften eines Gerätezwillings auf einem oder mehreren Geräten aktualisiert werden.
create_scheduled_job
Parameterhinweise:
job_id
muss eindeutig sein.- Legen Sie
type
aufscheduleUpdateTwin
fest. - Verwenden von
update_twin
zum Festlegen des Namens und der Nutzdaten der direkten Methode - Verwenden von
max_execution_time_in_seconds
zum Angeben der Ausführungszeit in Sekunden - Verwenden Sie
query_condition
, um eine Bedingung für ein oder mehrere Geräte anzugeben, für die direkte Methoden aufgerufen werden können. Weitere Informationen zu Abfragebedingungen finden Sie unter IoT Hub-Abfragesprache für Geräte- und Modulzwillinge, Aufträge und Nachrichtenweiterleitung.
Zum Beispiel:
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)
Überwachen eines Auftrags
Verwenden Sie get_scheduled_job, um die Details eines bestimmten Auftrags auf einem IoT Hub abzurufen.
In diesem Beispiel wird der Auftragsstatus für eine bestimmte Auftrags-ID alle fünf Sekunden überprüft, bis der Auftrag abgeschlossen ist.
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)
Beispiele für einen SDK-Zeitplanauftrag
Das Azure IoT SDK für Python bietet funktionierende Beispiele von Dienstanwendungen, die Aufgaben der Jobplanung bearbeiten. Weitere Informationen finden Sie unter:
- Erfordert die Node.js-Version 10.0.x oder höher
Übersicht
In diesem Artikel wird beschrieben, wie Sie mit dem Azure IoT SDK für Node.js Back-End-Dienstanwendungscode erstellen, um einen Job zum Aufrufen einer direkten Methode oder zur Durchführung eines Gerätezwillings-Updates auf einem oder mehreren Geräten zu planen.
Dienst-SDK-Paket installieren
Führen Sie diesen Befehl aus, um azure-iothub auf Ihrem Computer zu installieren:
npm install azure-iothub --save
Die Klasse JobClient macht alle Methoden verfügbar, die für die Interaktion mit der Auftragsplanung aus einer Back-End-Anwendung erforderlich sind.
Herstellen einer Verbindung mit dem IoT-Hub
Sie können einen Back-End-Dienst mit IoT Hub mithilfe der folgenden Methoden verbinden:
- Richtlinie für gemeinsamen Zugriff
- Microsoft Entra
Wichtig
Dieser Artikel enthält Schritte zum Herstellen einer Verbindung mit einem Dienst mithilfe einer Shared Access Signature. Diese Authentifizierungsmethode eignet sich für Tests und Auswertungen, aber die Authentifizierung bei einem Dienst mit Microsoft Entra ID oder verwalteten Identitäten ist ein sichererer Ansatz. Weitere Informationen finden Sie unter Bewährte Methoden für die Sicherheit von IoT-Lösungen in der Cloud-Sicherheit>.
Herstellen einer Verbindung mithilfe einer SAS-Richtlinie
Verwenden Sie fromConnectionString, um eine Verbindung mit dem IoT-Hub herzustellen.
In diesem Artikel wird Back-End-Code beschrieben, mit dem Sie einen Auftrag zum Aufrufen einer direkten Methode planen können, einen Auftrag zum Aktualisieren eines Gerätezwillings planen können und den Fortschritt eines Auftrags für ein oder mehrere Geräte überwachen können. Für diese Vorgänge benötigt Ihr Dienst die Berechtigungen Registrierungsleserechte und Registrierungschreibrechte. Standardmäßig wird jeder IoT-Hub mit einer freigegebenen Zugriffsrichtlinie namens registryReadWrite erstellt, die diese Berechtigungen erteilt.
Weitere Informationen zu SAS-Richtlinien finden Sie unter Steuern des Zugriffs auf IoT Hub mithilfe von Shared Access Signatures.
Zum Beispiel:
'use strict';
var JobClient = require('azure-iothub').JobClient;
var connectionString = '{Shared access policy connection string}';
var jobClient = JobClient.fromConnectionString(connectionString);
Verbinden mit Microsoft Entra
Eine Backend-App, die Microsoft Entra verwendet, muss sich erfolgreich authentifizieren und Sicherheitstoken-Anmeldedaten erhalten können, bevor sie eine Verbindung mit dem IoT Hub herstellen kann. Dieses Token wird an eine IoT Hub-Verbindungsmethode übergeben. Allgemeine Informationen zum Einrichten und Verwenden von Microsoft Entra für IoT Hub finden Sie unter Steuern des Zugriffs auf IoT Hub mithilfe von Microsoft Entra ID.
Eine Übersicht über Node.js SDK-Authentifizierung finden Sie unter:
- Erste Schritte mit der Benutzerauthentifizierung in Azure
- Azure Identity-Clientbibliothek für JavaScript
Konfigurieren der Microsoft Entra-App
Sie müssen eine Microsoft Entra-App einrichten, die für Ihre bevorzugten Authentifizierungsanmeldeinformationen konfiguriert ist. Die App enthält Parameter wie den geheimen Clientschlüssel, der von der Back-End-Anwendung zur Authentifizierung verwendet wird. Die verfügbaren Konfigurationen für die App-Authentifizierung sind:
- Geheimer Clientschlüssel
- Zertifikat
- Verbundidentitätsnachweis
Microsoft Entra-Apps erfordern je nach ausgeführten Vorgängen möglicherweise bestimmte Rollenberechtigungen. Beispielsweise ist Mitwirkender an IoT Hub-Zwillingen erforderlich, um Lese- und Schreibzugriff auf ein IoT Hub-Gerät und Modulzwillinge zu ermöglichen. Weitere Informationen finden Sie unter Verwalten des Zugriffs auf IoT Hub mithilfe der Azure RBAC-Rollenzuweisung.
Weitere Informationen zum Einrichten einer Microsoft Entra-App finden Sie in der Schnellstartanleitung: Registrieren einer Anwendung bei der Microsoft Identitäts-Plattform.
Authentifizieren mithilfe von DefaultAzureCredential
Die einfachste Möglichkeit, Microsoft Entra zur Authentifizierung einer Back-End-Anwendung zu verwenden, ist die Nutzung von DefaultAzureCredential. Für Produktionsumgebungen wird jedoch empfohlen, eine andere Methode zu wählen, einschließlich einer spezifischen TokenCredential
oder einer reduzierten ChainedTokenCredential
. Der Einfachheit halber beschreibt dieser Abschnitt die Authentifizierung mit DefaultAzureCredential
und den geheimen Clientschlüssel.
Weitere Informationen zu den Vor- und Nachteilen der Verwendung von DefaultAzureCredential
finden Sie unter Anmeldeinformationsketten in der Azure Identity-Clientbibliothek für JavaScript
DefaultAzureCredential unterstützt verschiedene Authentifizierungsmechanismen und bestimmt den entsprechenden Anmeldeinformationstyp basierend auf der Umgebung, in der er ausgeführt wird. Es versucht, mehrere Anmeldeinformationstypen in einer Reihenfolge zu verwenden, bis sie eine funktionierende Anmeldeinformation findet.
Microsoft Entra erfordert dieses Paket:
npm install --save @azure/identity
In diesem Beispiel wurden der Clientschlüssel, die Client-ID und die Mandanten-ID der Microsoft Entra-App-Registrierung zu den Umgebungsvariablen hinzugefügt. Diese Umgebungsvariablen werden von DefaultAzureCredential
verwendet, um die Anwendung zu authentifizieren. Das Ergebnis einer erfolgreichen Microsoft Entra-Authentifizierung ist eine Sicherheitstoken-Anmeldeinformation, die an eine IoT Hub-Verbindungsmethode übergeben wird.
import { DefaultAzureCredential } from "@azure/identity";
// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();
Das resultierende Anmeldeinformationstoken kann dann an fromTokenCredential übergeben werden, um eine Verbindung mit IoT Hub für jeden SDK-Client herzustellen, der Microsoft Entra-Anmeldeinformationen akzeptiert:
fromTokenCredential
erfordert zwei Parameter:
- Die Azure-Dienst-URL – Die Azure-Dienst-URL sollte im Format
{Your Entra ___domain URL}.azure-devices.net
ohne einhttps://
-Präfix vorliegen. Beispiel:MyAzureDomain.azure-devices.net
. - Das Azure-Anmeldeinformationstoken
In diesem Beispiel werden die Azure-Anmeldeinformationen mithilfe von DefaultAzureCredential
erlangt. Die Azure-Domänen-URL und Anmeldeinformationen werden dann an Registry.fromTokenCredential
bereitgestellt, um die Verbindung mit IoT Hub zu erstellen.
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);
Codebeispiele
Arbeitsbeispiele für die Microsoft Entra-Dienstauthentifizierung finden Sie in Azure-Identitätsbeispielen.
Erstellen eines Auftrags mit direkter Methode
Verwenden Sie scheduleDeviceMethod, um einen Auftrag zur Ausführung einer direkten Methode auf einem oder mehreren Geräten zu planen.
Erstellen Sie zunächst eine Variable für das Update einer direkten Methode mit dem Namen der Methode, der Nutzdaten und den Informationen zum Timeout der Antwort. Zum Beispiel:
var methodParams = {
methodName: 'lockDoor',
payload: null,
responseTimeoutInSeconds: 15 // Time-out after 15 seconds if device is unable to process method
};
Rufen Sie dann scheduleDeviceMethod
auf, um den Auftrag für den Aufruf der direkten Methode zu planen:
- Jeder Auftrag muss über eine eindeutige Auftrags-ID verfügen. Sie können diese Auftrags-ID verwenden, um einen Auftrag zu überwachen, wie im Abschnitt Überwachen eines Auftrags in diesem Artikel beschrieben.
- Geben Sie einen
queryCondition
-Parameter an, um zu ermitteln, auf welchen Geräten der Auftrag ausgeführt werden soll. Weitere Informationen zu Abfragebedingungen finden Sie unter IoT Hub-Abfragesprache für Geräte- und Modulzwillinge, Aufträge und Nachrichtenweiterleitung. - Überprüfen Sie den
jobResult
-Rückruf auf das Ergebnis des Auftragsplans. Wenn der Auftrag erfolgreich geplant wurde, können Sie den Auftragsstatus überwachen, wie im Abschnitt Überwachen eines Auftrags in diesem Artikel beschrieben.
Zum Beispiel:
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));
}
});
}
});
Planen eines Auftrags zur Aktualisierung eines Gerätezwillings
Verwenden Sie scheduleTwinUpdate, um einen neuen Auftrag zu erstellen, mit dem ein Geräte-Zwilling-Update auf einem oder mehreren Geräten durchgeführt wird.
Erstellen Sie zunächst eine Variable zur Aktualisierung der gewünschten Eigenschaft des Gerätezwillings.
var twinPatch = {
etag: '*',
properties: {
desired: {
building: '43',
floor: 3
}
}
};
Rufen Sie dann scheduleTwinUpdate
auf, um den Auftrag zur Aktualisierung der Eigenschaften des Gerätezwillings zu planen:
- Jeder Auftrag muss über eine eindeutige Auftrags-ID verfügen. Sie können diese Auftrags-ID verwenden, um einen Auftrag zu überwachen, wie im Abschnitt Überwachen eines Auftrags in diesem Artikel beschrieben.
- Geben Sie einen
queryCondition
-Parameter an, um zu ermitteln, auf welchen Geräten der Auftrag ausgeführt werden soll. Weitere Informationen zu Abfragebedingungen finden Sie unter IoT Hub-Abfragesprache für Geräte- und Modulzwillinge, Aufträge und Nachrichtenweiterleitung. - Überprüfen Sie den
jobResult
-Rückruf auf das Ergebnis des Auftragsplans. Wenn der Auftrag erfolgreich geplant wurde, können Sie den Auftragsstatus überwachen, wie im Abschnitt Überwachen eines Auftrags in diesem Artikel beschrieben.
Zum Beispiel:
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));
}
});
}
});
Überwachen eines Auftrags
Verwenden Sie getJob, um den Auftragsstatus für eine bestimmte Auftrags-ID zu überwachen.
Diese Beispielfunktion prüft den Auftragsstatus für eine bestimmte Auftrags-ID in regelmäßigen Abständen, bis der Auftrag abgeschlossen oder fehlgeschlagen ist.
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);
}
Beispiel für einen SDK-Zeitplanauftrag
Das Azure IoT SDK für Node.js bietet ein funktionierendes Beispiel für eine Dienst-App, die Aufgaben zur Zeitplanung verwaltet. Weitere Informationen siehe Job-Client E2E-Test.