Dela via

Komma igång med enhetshantering

  • Artikel

Serverdelsappar kan använda Azure IoT Hub-primitiver, till exempel enhetstvillingar och direktmetoder, för att fjärrstarta och övervaka enhetshanteringsåtgärder på enheter.

Använd en direktmetod från ett serverdelsprogram för att initiera åtgärder för enhetshantering, till exempel omstart, fabriksåterställning och uppdatering av inbyggd programvara.

Enheten ansvarar för:

  • Hantera begäran om direktmetod som skickas från IoT Hub
  • Initiera motsvarande enhetsspecifika åtgärd på enheten
  • Tillhandahålla statusuppdateringar via rapporterade egenskaper till IoT Hub

Den här artikeln visar hur en serverdelsapp och en enhetsapp kan arbeta tillsammans för att initiera och övervaka en fjärrenhetsåtgärd med hjälp av en direktmetod.

  • En tjänstapp anropar en direktmetod för att starta om i en enhetsapp via en IoT-hubb.
  • En enhetsapp hanterar en direktmetod för att starta om en enhet.

Kommentar

De funktioner som beskrivs i den här artikeln är endast tillgängliga på standardnivån för IoT Hub. Mer information om de grundläggande och standard-/kostnadsfria IoT Hub-nivåerna finns i Välj rätt IoT Hub-nivå för din lösning.

Kommentar

Den här artikeln är avsedd att komplettera Azure IoT SDK-exempel som refereras inifrån den här artikeln. Du kan använda SDK-verktyg för att skapa både enhets- och serverdelsprogram.

Förutsättningar

  • En IoT Hub

  • En registrerad enhet

  • Om ditt program använder MQTT-protokollet kontrollerar du att port 8883 är öppen i brandväggen. MQTT-protokollet kommunicerar via port 8883. Den här porten kan blockeras i vissa företags- och utbildningsnätverksmiljöer. Mer information och sätt att kringgå det här problemet finns i Ansluta till IoT Hub (MQTT).

  • Kräver Visual Studio

Översikt

Den här artikeln beskriver hur du använder Azure IoT SDK för .NET för att skapa programkod för enhet och serverdelstjänst för enhetsdirigeringsmeddelanden.

Skapa ett enhetsprogram

I det här avsnittet beskrivs hur du använder programkod för enheter för att skapa en lyssnare för direkt metodåteranrop.

Viktigt!

Den här artikeln innehåller steg för att ansluta en enhet med en signatur för delad åtkomst, även kallad symmetrisk nyckelautentisering. Den här autentiseringsmetoden är praktisk för testning och utvärdering, men att autentisera en enhet med X.509-certifikat är en säkrare metod. Mer information finns i Metodtips > för säkerhet Anslutningssäkerhet.

Obligatoriskt NuGet-paket för enhet

Enhetsklientprogram som skrivits i C# kräver NuGet-paketet Microsoft.Azure.Devices.Client .

Lägg till dessa using instruktioner för att använda enhetsbiblioteket.

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

Ansluta till en enhet

Klassen DeviceClient visar alla metoder som krävs för att interagera med enhetsmeddelanden från enheten.

Anslut till enheten med metoden CreateFromConnectionString tillsammans med anslutningssträng och anslutningstransportprotokollet.

TransportType-transportprotokollparametern CreateFromConnectionString stöder följande transportprotokoll:

  • Mqtt
  • Mqtt_WebSocket_Only
  • Mqtt_Tcp_Only
  • Amqp
  • Amqp_WebSocket_Only
  • Amqp_Tcp_Only
  • Http1

Det här exemplet ansluter till en enhet med hjälp av transportprotokollet Mqtt .

static string DeviceConnectionString = "{IoT hub device connection string}";
static deviceClient = null;
deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
   TransportType.Mqtt);

Skapa en direkt metod för återanropslyssnare

Använd SetMethodHandlerAsync för att initiera en lyssnare för direkt metodåteranrop. Lyssnaren är associerad med ett nyckelord för metodnamn, till exempel "reboot". Metodnamnet kan användas i en IoT Hub- eller serverdelsapp för att utlösa återanropsmetoden på enheten.

I det här exemplet konfigureras en uppringningslyssnare med namnet onReboot som utlöses när namnet på den "starta om" direktmetoden anropas.

try
{
      // setup callback for "reboot" method
      deviceClient.SetMethodHandlerAsync("reboot", onReboot, null).Wait();
      Console.WriteLine("Waiting for reboot method\n Press enter to exit.");
      Console.ReadLine();

      Console.WriteLine("Exiting...");

      // as a good practice, remove the "reboot" handler
      deviceClient.SetMethodHandlerAsync("reboot", null, null).Wait();
      deviceClient.CloseAsync().Wait();
}
catch (Exception ex)
{
      Console.WriteLine();
      Console.WriteLine("Error in sample: {0}", ex.Message);
}

Om du fortsätter med exemplet onReboot implementerar motringningsmetoden direktmetoden på enheten.

Hanteringsfunktionen anropar MethodResponse för att skicka en svarsbekräftelse till det anropande programmet.

static Task<MethodResponse> onReboot(MethodRequest methodRequest, object userContext)
{
      // In a production device, you would trigger a reboot 
      // scheduled to start after this method returns.
      // For this sample, we simulate the reboot by writing to the console
      // and updating the reported properties.
      try
      {
         Console.WriteLine("Rebooting!");
      }
      catch (Exception ex)
      {
         Console.WriteLine();
         Console.WriteLine("Error in sample: {0}", ex.Message);
      }

      string result = @"{""result"":""Reboot started.""}";
      return Task.FromResult(new MethodResponse(Encoding.UTF8.GetBytes(result), 200));
}

Kommentar

För att hålla det enkelt implementerar den här artikeln inte någon återförsöksprincip. I produktionskod bör du implementera återförsöksprinciper (till exempel en exponentiell backoff), som föreslås i Tillfälliga felhantering.

SDK-enhetsexempel

Azure IoT SDK för .NET innehåller arbetsexempel på enhetsappar som hanterar direkta metoduppgifter. Mer information finns i:

Skapa ett serverdelsprogram

I det här avsnittet beskrivs hur du utlöser en direkt metod på en enhet.

Klassen ServiceClient exponerar alla metoder som krävs för att skapa ett serverdelsprogram för att skicka direktmetodanrop till enheter.

Obligatoriskt NuGet-tjänstpaket

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

Lägg till dessa using instruktioner för att använda tjänstbiblioteket.

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

Ansluta till IoT Hub

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

  • Princip för delad åtkomst
  • Microsoft Entra

Viktigt!

Den här artikeln innehåller steg för att ansluta till en tjänst med hjälp av en signatur för delad åtkomst. Den här autentiseringsmetoden är praktisk för testning och utvärdering, men autentisering till en tjänst med Microsoft Entra-ID eller hanterade identiteter är en säkrare metod. Mer information finns i Metodtips för > säkerhet Molnsäkerhet.

Ansluta med en princip för delad åtkomst

Anslut ett serverdelsprogram med CreateFromConnectionString.

Om du vill anropa en direktmetod på en enhet via IoT Hub behöver din tjänst behörighet för tjänstanslutning . Som standard skapas varje IoT Hub med en princip för delad åtkomst med namnet service som ger den här behörigheten.

Som en parameter till CreateFromConnectionStringanger du principen för delad åtkomst för tjänsten . Mer information om principer för delad åtkomst finns i Kontrollera åtkomst till IoT Hub med signaturer för delad åtkomst.

ServiceClient serviceClient;
string connectionString = "{IoT hub service shared access policy connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

Ansluta med Microsoft Entra

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

Konfigurera Microsoft Entra-app

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

  • Klienthemlighet
  • Certifikat
  • Federerade identitetsautentiseringsuppgifter

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

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

Autentisera med defaultAzureCredential

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

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

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

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

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

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

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

TokenCredential tokenCredential = new DefaultAzureCredential();

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

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

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

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

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

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

Anropa en metod på en enhet

Så här anropar du en metod på en enhet:

  1. Skapa ett CloudToDeviceMethod-objekt . Skicka namnet på enhetsdirigeringsmetoden som en parameter.
  2. Anropa InvokeDeviceMethodAsync för att anropa metoden på enheten.

I det här exemplet anropas metoden "reboot" för att starta om enheten. Metoden "reboot" mappas till en lyssnare på enheten enligt beskrivningen i avsnittet Skapa en direkt metod för återanropslyssnare i den här artikeln.

string targetDevice = "myDeviceId";
CloudToDeviceMethod method = new CloudToDeviceMethod("reboot");
method.ResponseTimeout = TimeSpan.FromSeconds(30);

CloudToDeviceMethodResult response = await serviceClient.InvokeDeviceMethodAsync(targetDevice, method);

Console.WriteLine("Invoked firmware update on device.");

SDK-tjänstexempel

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

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

Översikt

Den här artikeln beskriver hur du använder Azure IoT SDK för Java för att skapa programkod för enhet och serverdelstjänst för enhetsdirigeringsmetoder.

Skapa ett enhetsprogram

I det här avsnittet beskrivs hur du använder programkod för enheter för att skapa en lyssnare för direkt metodåteranrop.

Viktigt!

Den här artikeln innehåller steg för att ansluta en enhet med en signatur för delad åtkomst, även kallad symmetrisk nyckelautentisering. Den här autentiseringsmetoden är praktisk för testning och utvärdering, men att autentisera en enhet med X.509-certifikat är en säkrare metod. Mer information finns i Metodtips > för säkerhet Anslutningssäkerhet.

Instruktion för enhetsimport

Använd följande enhetsimportinstruktioner för att få åtkomst till Azure IoT SDK för Java.

import com.microsoft.azure.sdk.iot.device.*;
import com.microsoft.azure.sdk.iot.device.exceptions.IotHubClientException;
import com.microsoft.azure.sdk.iot.device.twin.DirectMethodPayload;
import com.microsoft.azure.sdk.iot.device.twin.DirectMethodResponse;
import com.microsoft.azure.sdk.iot.device.twin.MethodCallback;
import com.microsoft.azure.sdk.iot.device.transport.IotHubConnectionStatus;
import com.microsoft.azure.sdk.iot.device.twin.SubscriptionAcknowledgedCallback;

Ansluta till en enhet

Klassen DeviceClient exponerar alla metoder som du behöver för att interagera med direkta metoder på enheten.

Så här ansluter du till en enhet:

  1. Använd IotHubClientProtocol för att välja ett transportprotokoll. Till exempel:

    IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;

  2. DeviceClient Använd konstruktorn för att lägga till enhetens primära anslutningssträng och protokoll.

    String connString = "{IoT hub device connection string}";
DeviceClient client = new DeviceClient(connString, protocol);

  3. Använd open för att ansluta enheten till IoT Hub. Om klienten redan är öppen gör metoden ingenting.

    client.open(true);

Skapa en direkt metod för återanropslyssnare

Använd subscribeToMethods för att initiera en lyssnare för direkt metodåteranrop. subscribeToMethods lyssnar efter inkommande direktmetoder tills anslutningen har avslutats. Metodnamnet och nyttolasten tas emot för varje direkt metodanrop.

Lyssnaren bör anropa DirectMethodResponse för att skicka en bekräftelse av metodsvaret till det anropande programmet.

Till exempel:

client.subscribeToMethods(
    (methodName, methodData, context) ->
    {
        System.out.println("Received a direct method invocation with name " + methodName + " and payload " + methodData.getPayloadAsJsonString());
        return new DirectMethodResponse(200, methodData);
    },
    null);
System.out.println("Successfully subscribed to direct methods");

Kommentar

För att hålla det enkelt implementerar den här artikeln inte någon återförsöksprincip. I produktionskod bör du implementera återförsöksprinciper (till exempel en exponentiell backoff), som föreslås i Tillfälliga felhantering.

SDK-enhetsexempel

Azure IoT SDK för Java innehåller ett arbetsexempel för att testa de enhetsappbegrepp som beskrivs i den här artikeln. Mer information finns i Exempel på direktmetod.

Skapa ett serverdelsprogram

I det här avsnittet beskrivs hur du initierar en fjärromstart på en enhet med hjälp av en direktmetod.

Klassen ServiceClient DeviceMethod innehåller metoder som tjänster kan använda för att komma åt enhetstvillingar.

Tjänstimportinstruktioner

Använd följande tjänstimportinstruktioner för att få åtkomst till Azure IoT SDK för Java.

import com.microsoft.azure.sdk.iot.service.methods.DirectMethodRequestOptions;
import com.microsoft.azure.sdk.iot.service.methods.DirectMethodsClient;
import com.microsoft.azure.sdk.iot.service.methods.DirectMethodResponse;

Ansluta till IoT Hub

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

  • Princip för delad åtkomst
  • Microsoft Entra

Viktigt!

Den här artikeln innehåller steg för att ansluta till en tjänst med hjälp av en signatur för delad åtkomst. Den här autentiseringsmetoden är praktisk för testning och utvärdering, men autentisering till en tjänst med Microsoft Entra-ID eller hanterade identiteter är en säkrare metod. Mer information finns i Metodtips för > säkerhet Molnsäkerhet.

Ansluta med en princip för delad åtkomst

Använd DeviceMethod-konstruktorn för att lägga till tjänstens primära anslutningssträng och ansluta till IoT Hub.

Om du vill anropa en direktmetod på en enhet via IoT Hub behöver din tjänst behörighet för tjänstanslutning . Som standard skapas varje IoT Hub med en princip för delad åtkomst med namnet service som ger den här behörigheten.

Som en parameter till DeviceMethod konstruktorn anger du principen för delad åtkomst för tjänsten . Mer information om principer för delad åtkomst finns i Kontrollera åtkomst till IoT Hub med signaturer för delad åtkomst.

Till exempel:

String iotHubConnectionString = "HostName=xxxxx.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey=xxxxxxxxxxxxxxxxxxxxxxxx";
DeviceMethod methodClient = new DeviceMethod(iotHubConnectionString);

Ansluta med Microsoft Entra

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

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

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

Konfigurera Microsoft Entra-app

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

  • Klienthemlighet
  • Certifikat
  • Federerade identitetsautentiseringsuppgifter

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

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

Autentisera med defaultAzureCredential

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

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

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

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

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();
Autentisera med ClientSecretCredentialBuilder

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

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

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

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

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

Kodexempel

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

Anropa en metod på en enhet

Anropa DeviceMethod.invoke för att anropa en metod på en enhet och returnera resultatstatusen.

Nyttolastparametern invoke är valfri. Använd null om det inte finns någon angiven nyttolast. Nyttolastparametern kan ha olika dataformer, inklusive sträng, bytematris och HashMap. Exempel finns i Direktmetodtester.

I det här exemplet anropas metoden "reboot" för att starta om enheten. Metoden "reboot" mappas till en lyssnare på enheten enligt beskrivningen i avsnittet Skapa en direkt metod för återanropslyssnare i den här artikeln.

Till exempel:

String deviceId = "myFirstDevice";
String methodName = "reboot";
String payload = "Test payload";
Long responseTimeout = TimeUnit.SECONDS.toSeconds(30);
Long connectTimeout = TimeUnit.SECONDS.toSeconds(5);

MethodResult result = methodClient.invoke(deviceId, methodName, responseTimeout, connectTimeout, payload);
if (result == null)
{
    throw new IOException("Method invoke returns null");
}
System.out.println("Status=" + result.getStatus());

SDK-tjänstexempel

Azure IoT SDK för Java innehåller ett fungerande exempel på tjänstappar som hanterar direkta metoduppgifter. Mer information finns i:

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

Översikt

Den här artikeln beskriver hur du använder Azure IoT SDK för Python för att skapa programkod för enhet och serverdelstjänst för enhetsdirigeringsmetoder.

Installera paket

Biblioteket azure-iot-device måste vara installerat för att skapa enhetsprogram.

pip install azure-iot-device

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

pip install azure-iot-hub

Skapa ett enhetsprogram

I det här avsnittet beskrivs hur du använder programkod för enheter för att skapa en lyssnare för direkt metodåteranrop.

Viktigt!

Den här artikeln innehåller steg för att ansluta en enhet med en signatur för delad åtkomst, även kallad symmetrisk nyckelautentisering. Den här autentiseringsmetoden är praktisk för testning och utvärdering, men att autentisera en enhet med X.509-certifikat är en säkrare metod. Mer information finns i Metodtips > för säkerhet Anslutningssäkerhet.

Enhetsimportinstruktioner

Lägg till den här import-instruktionen för åtkomst IoTHubDeviceClient och MethodResponse.

# import the device client library
from azure.iot.device import IoTHubDeviceClient, MethodResponse

Ansluta till en enhet

Klassen IoTHubDeviceClient innehåller metoder som kan användas för att arbeta med direkta metoder.

Använd create_from_connection_string för att ansluta ett program till en enhet med hjälp av en enhet anslutningssträng.

# substitute the device connection string in conn_str
# and add it to the IoTHubDeviceClient object
conn_str = "{IoT hub device connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)

Skapa ett direkt metodåteranrop

Använd on_method_request_received för att skapa en hanteringsfunktion eller coroutine som anropas när en direktmetod tas emot. Lyssnaren är associerad med ett nyckelord för metodnamn, till exempel "reboot". Metodnamnet kan användas i en IoT Hub- eller serverdelsapp för att utlösa återanropsmetoden på enheten.

Hanteringsfunktionen bör skapa en MethodResponse och skicka den till send_method_response för att skicka en bekräftelse av direktmetodsvar till det anropande programmet.

I det här exemplet konfigureras en direkt metodhanterare med namnet method_request_handler.

try:
    # Attach the handler to the client
    client.on_method_request_received = method_request_handler
except:
    # In the event of failure, clean up
    client.shutdown()

I det här exemplet method_request_handler implementerar motringningsmetoden direktmetoden på enheten. Koden körs när direktmetoden "rebootDevice" anropas från ett tjänstprogram. Metoden anropar send_method_response för att skicka en bekräftelse av direktmetodsvar till det anropande programmet.

# Define the handler for method requests
def method_request_handler(method_request):
    if method_request.name == "rebootDevice":
        # Act on the method by rebooting the device
        print("Rebooting device")
        time.sleep(20)
        print("Device rebooted")
        # Create a method response indicating the method request was resolved
        resp_status = 200
        resp_payload = {"Response": "This is the response from the device"}
        method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)
    else:
        # Create a method response indicating the method request was for an unknown method
        resp_status = 404
        resp_payload = {"Response": "Unknown method"}
        method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)

    # Send the method response
    client.send_method_response(method_response)

SDK-enhetsexempel

Azure IoT SDK för Python innehåller ett fungerande exempel på en enhetsapp som hanterar direkta metoduppgifter. Mer information finns i Ta emot direktmetod.

Skapa ett serverdelsprogram

I det här avsnittet beskrivs hur du använder ett serverdelstjänstprogram för att anropa en direktmetod på en enhet.

Klassen IoTHubRegistryManager visar alla metoder som krävs för att skapa ett serverdelsprogram för att skicka meddelanden till en enhet.

Tjänstimportinstruktioner

Lägg till dessa importinstruktioner för att ansluta till Iot Hub, skicka direktmetoder från moln till enhet och ta emot svar på enhetsdirigeringsmetoder.

from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import CloudToDeviceMethod, CloudToDeviceMethodResult

Ansluta till IoT Hub

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

  • Princip för delad åtkomst
  • Microsoft Entra

Viktigt!

Den här artikeln innehåller steg för att ansluta till en tjänst med hjälp av en signatur för delad åtkomst. Den här autentiseringsmetoden är praktisk för testning och utvärdering, men autentisering till en tjänst med Microsoft Entra-ID eller hanterade identiteter är en säkrare metod. Mer information finns i Metodtips för > säkerhet Molnsäkerhet.

Ansluta med en princip för delad åtkomst

Anslut till IoT Hub med hjälp av from_connection_string.

Om du vill anropa en direktmetod på en enhet via IoT Hub behöver din tjänst behörighet för tjänstanslutning . Som standard skapas varje IoT Hub med en princip för delad åtkomst med namnet service som ger den här behörigheten.

Som en parameter till from_connection_stringanger du principen för delad åtkomst för tjänsten . Mer information om principer för delad åtkomst finns i Kontrollera åtkomst till IoT Hub med signaturer för delad åtkomst.

Till exempel:

# Connect to IoT hub
IOTHUB_CONNECTION_STRING = "{IoT hub service connection string}"
iothub_registry_manager = IoTHubRegistryManager.from_connection_string(IOTHUB_CONNECTION_STRING)

Ansluta med Microsoft Entra

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

En översikt över Python SDK-autentisering finns i Autentisera Python-appar till Azure-tjänster med hjälp av Azure SDK för Python

Konfigurera Microsoft Entra-app

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

  • Klienthemlighet
  • Certifikat
  • Federerade identitetsautentiseringsuppgifter

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

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

Autentisera med defaultAzureCredential

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

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

Microsoft Entra kräver det här importpaketet och motsvarande import instruktion:

pip install azure-identity

from azure.identity import DefaultAzureCredential

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

from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()

Den resulterande AccessToken kan sedan skickas till from_token_credential för att ansluta till IoT Hub för alla SDK-klienter som accepterar Microsoft Entra-autentiseringsuppgifter:

from_token_credential kräver två parametrar:

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

I det här exemplet hämtas Azure-autentiseringsuppgifterna med hjälp av DefaultAzureCredential. Azure-tjänstens URL och autentiseringsuppgifter tillhandahålls sedan för att IoTHubRegistryManager.from_token_credential skapa anslutningen till IoT Hub.

import sys
import os

from azure.identity import DefaultAzureCredential
from azure.iot.hub import IoTHubRegistryManager

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

# Set environment variables
os.environ['AZURE_CLIENT_SECRET'] = clientSecretValue
os.environ['AZURE_CLIENT_ID'] = clientID
os.environ['AZURE_TENANT_ID'] = tenantID

# Acquire a credential object
credential = DefaultAzureCredential()

# Use Entra to authorize IoT Hub service
print("Connecting to IoTHubRegistryManager...")
iothub_registry_manager = IoTHubRegistryManager.from_token_credential(
url="MyAzureDomain.azure-devices.net",
token_credential=credential)
Kodexempel

Arbetsexempel för Microsoft Entra-tjänstautentisering finns i Microsoft Authentication Library (MSAL) för Python.

Anropa en metod på en enhet

Du kan anropa en direktmetod med namn på en enhet. Metodnamnet identifierar metoden. I följande och föregående enhetsexempel som visas i Skapa ett direkt metodåteranrop är namnet på direktmetoden "rebootDevice".

Så här anropar du en direktmetod på en enhet:

  1. Skapa ett CloudToDeviceMethod-objekt . Ange metodnamnet och nyttolasten som parametrar.
  2. Anropa invoke_device_method för att anropa en direktmetod på en enhet. Ange enhets-ID och CloudToDeviceMethod nyttolastobjekt som parametrar.

Det här exemplet anropar CloudToDeviceMethod för att anropa en direktmetod med namnet "rebootDevice" på en enhet. När direktmetoden har anropats visas nyttolasten för direktmetodens svar.

CONNECTION_STRING = "{IoTHubConnectionString}"
DEVICE_ID = "{deviceId}"

METHOD_NAME = "rebootDevice"
METHOD_PAYLOAD = "{\"method_number\":\"42\"}"
TIMEOUT = 60
WAIT_COUNT = 10

try:
    print ( "" )
    print ( "Invoking device to reboot..." )

    # Call the direct method.
    deviceMethod = CloudToDeviceMethod(method_name=METHOD_NAME, payload=METHOD_PAYLOAD)
    response = registry_manager.invoke_device_method(DEVICE_ID, deviceMethod)

    print ( "Successfully invoked the device to reboot." )

    print ( "The device has returned this payload:" )
    print ( response.payload )

except Exception as ex:
    print ( "" )
    print ( "Unexpected error {0}".format(ex) )
    return

SDK-tjänstexempel

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

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

Översikt

Den här artikeln beskriver hur du använder Azure IoT SDK för Node.js för att skapa programkod för enhet och serverdelstjänst för enhetsdirigeringsmetoder.

Skapa ett enhetsprogram

I det här avsnittet beskrivs hur du använder enhetsprogramkod för att skapa en direkt metodåteranrop.

Installera SDK-paket

Paketet azure-iot-device innehåller objekt som samverkar med IoT-enheter. Kör det här kommandot för att installera azure-iot-device SDK på utvecklingsdatorn:

npm install azure-iot-device --save

Välj ett transportprotokoll

Objektet Client stöder följande protokoll:

  • Amqp
  • Http – När du använder Httpsöker instansen Client efter meddelanden från IoT Hub sällan (minst var 25:e minut).
  • Mqtt
  • MqttWs
  • AmqpWs

Installera nödvändiga transportprotokoll på utvecklingsdatorn.

Det här kommandot installerar till exempel protokollet Amqp :

npm install azure-iot-device-amqp --save

Mer information om skillnaderna mellan MQTT-, AMQP- och HTTPS-stöd finns i Vägledning för kommunikation från moln till enhet och Välj ett kommunikationsprotokoll.

Skapa ett klientobjekt

Skapa ett Client objekt med det installerade paketet.

Till exempel:

const Client = require('azure-iot-device').Client;

Skapa ett protokollobjekt

Skapa ett Protocol objekt med ett installerat transportpaket.

I det här exemplet tilldelas AMQP-protokollet:

const Protocol = require('azure-iot-device-amqp').Amqp;

Lägg till anslutningssträng- och transportprotokollet för enheten

Anropa fromConnectionString för att ange parametrar för enhetsanslutning:

  • connStr – enheten anslutningssträng.
  • transportCtor – transportprotokollet.

I det här exemplet används transportprotokollet Amqp :

const deviceConnectionString = "{IoT hub device connection string}"
const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

Öppna anslutningen till IoT Hub

Använd den öppna metoden för att öppna anslutningen mellan en IoT-enhet och IoT Hub.

Till exempel:

client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
})

Skapa ett direkt metodåteranrop

Anropa onDeviceMethod för att skapa en hanteringsfunktion för motringning eller coroutine som anropas när en direktmetod tas emot. Lyssnaren är associerad med ett nyckelord för metodnamn, till exempel "reboot". Metodnamnet kan användas i en IoT Hub- eller serverdelsapp för att utlösa återanropsmetoden på enheten.

Funktionen för motringningshanterare bör anropa response.send för att skicka ett svarsbekräftelsemeddelande till det anropande programmet.

I det här exemplet konfigureras en direkt metodhanterare med namnet onReboot som anropas när namnet på den "starta om" direktmetoden används.

client.onDeviceMethod('reboot', onReboot);

I det här exemplet onReboot implementerar motringningsmetoden direktmetoden på enheten. Koden körs när direktmetoden "starta om" anropas från ett tjänstprogram. Funktionen anropar response.send för att skicka ett svarsbekräftelsemeddelande till det anropande programmet.

var onReboot = function(request, response) {

    // Respond the cloud app for the direct method
    response.send(200, 'Reboot started', function(err) {
        if (err) {
            console.error('An error occurred when sending a method response:\n' + err.toString());
        } else {
            console.log('Response to method \'' + request.methodName + '\' sent successfully.');
        }
    });

    // Add your device's reboot API for physical restart.
    console.log('Rebooting!');
};

SDK-enhetsexempel

Azure IoT SDK för Node.js innehåller arbetsexempel på enhetsappar som hanterar enhetshanteringsuppgifter. Mer information finns i:

Skapa ett serverdelsprogram

I det här avsnittet beskrivs hur du anropar en direktmetod på en enhet.

Installera tjänst-SDK-paketet

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

npm install azure-iothub --save

Ansluta till IoT Hub

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

  • Princip för delad åtkomst
  • Microsoft Entra

Viktigt!

Den här artikeln innehåller steg för att ansluta till en tjänst med hjälp av en signatur för delad åtkomst. Den här autentiseringsmetoden är praktisk för testning och utvärdering, men autentisering till en tjänst med Microsoft Entra-ID eller hanterade identiteter är en säkrare metod. Mer information finns i Metodtips för > säkerhet Molnsäkerhet.

Ansluta med en princip för delad åtkomst

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

Om du vill anropa en direktmetod på en enhet via IoT Hub behöver din tjänst behörighet för tjänstanslutning . Som standard skapas varje IoT Hub med en princip för delad åtkomst med namnet service som ger den här behörigheten.

Som en parameter till CreateFromConnectionStringanger du principen för delad åtkomst för tjänsten anslutningssträng. Mer information om principer för delad åtkomst finns i Kontrollera åtkomst till IoT Hub med signaturer för delad åtkomst.

var Client = require('azure-iothub').Client;
var connectionString = '{IoT hub shared access policy connection string}';
var client = Client.fromConnectionString(connectionString);

Ansluta med Microsoft Entra

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

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

Konfigurera Microsoft Entra-app

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

  • Klienthemlighet
  • Certifikat
  • Federerade identitetsautentiseringsuppgifter

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

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

Autentisera med defaultAzureCredential

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

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

Microsoft Entra kräver det här paketet:

npm install --save @azure/identity

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

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

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

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

fromTokenCredential kräver två parametrar:

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

I det här exemplet hämtas Azure-autentiseringsuppgifterna med hjälp av DefaultAzureCredential. Url:en och autentiseringsuppgifterna för Azure-domänen skickas sedan till för att Registry.fromTokenCredential skapa anslutningen till IoT Hub.

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

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

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

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

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

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

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

Anropa en metod på en enhet

Använd invokeDeviceMethod för att anropa en direkt metod efter namn på en enhet. Parametern för metodnamn identifierar direktmetoden.

I det här exemplet anropas metoden "reboot" för att starta om enheten. Metoden "reboot" mappas till en motringningshanterare på enheten enligt beskrivningen i avsnittet Skapa en direkt metod för återanrop i den här artikeln.

var startRebootDevice = function(deviceToReboot) {

    var methodName = "reboot";

    var methodParams = {
        methodName: methodName,
        payload: null,
        timeoutInSeconds: 30
    };

    client.invokeDeviceMethod(deviceToReboot, methodParams, function(err, result) {
        if (err) {
            console.error("Direct method error: "+err.message);
        } else {
            console.log("Successfully invoked the device to reboot.");  
        }
    });
};

SDK-tjänstexempel

Azure IoT SDK för Node.js innehåller arbetsexempel på tjänstappar som hanterar enhetshanteringsuppgifter. Mer information finns i: