Freigeben über

Tutorial: Verwenden von benutzerdefinierten Zuweisungsrichtlinien bei Device Provisioning Service (DPS)

  • Artikel

Mithilfe benutzerdefinierter Zuweisungsrichtlinien können Sie genauer steuern, wie Geräte Ihren IoT-Hubs zugewiesen werden. Sie können benutzerdefinierte Zuweisungsrichtlinien definieren, wenn die von Azure IoT Hub Device Provisioning Service (DPS) bereitgestellten Richtlinien nicht den Anforderungen Ihres Szenarios entsprechen. Eine benutzerdefinierte Zuweisungsrichtlinie wird in einem in Azure Functions gehosteten Webhook implementiert und in einer oder mehreren Einzelregistrierungen und/oder Registrierungsgruppen konfiguriert. Wenn ein Gerät mit einem konfigurierten Registrierungseintrag bei DPS registriert wird, ruft DPS den Webhook auf, um herauszufinden, bei welchem IoT-Hub das Gerät registriert werden soll, und um optional seinen Anfangszustand zu ermitteln. Weitere Informationen finden Sie unter Grundlegendes zu benutzerdefinierten Zuweisungsrichtlinien.

In diesem Tutorial wird eine benutzerdefinierte Zuweisungsrichtlinie anhand einer in C# geschriebenen Azure-Funktion veranschaulicht. Geräte werden einem von zwei IoT-Hubs zugewiesen, die die Contoso-Abteilungen Toaster und Wärmepumpen darstellen. Für Geräte, deren Bereitstellung angefordert wird, ist eine Registrierungs-ID mit einem der folgenden Suffixe erforderlich, damit die Bereitstellung möglich ist:

  • -contoso-tstrsd-007 für die Contoso-Abteilung „Toaster“
  • -contoso-hpsd-088 für die Contoso-Abteilung „Wärmepumpen“

Die Geräte sind durch ein Bereitstellungsbeispiel simuliert, das im Azure IoT C SDK enthalten ist.

In diesem Tutorial führen Sie Folgendes aus:

  • Verwenden der Azure CLI zum Erstellen einer DPS-Instanz und zum Erstellen und Verknüpfen der beiden IoT-Hubs für die Contoso-Abteilungen (Contoso-Abteilung „Toaster“ und Contoso-Abteilung „Wärmepumpen“).
  • Erstellen einer Azure-Funktion, die die benutzerdefinierte Zuweisungsrichtlinie implementiert.
  • Erstellen einer neuen Registrierungsgruppe zur Verwendung der Azure-Funktion für die benutzerdefinierte Zuweisungsrichtlinie.
  • Erstellen symmetrischer Geräteschlüssel für zwei simulierte Geräte.
  • Einrichten der Entwicklungsumgebung für das Azure IoT C SDK.
  • Simulieren der Geräte, um zu überprüfen, ob sie gemäß dem Beispielcode der benutzerdefinierten Zuweisungsrichtlinie bereitgestellt sind.

Wenn Sie kein Azure-Abonnement haben, erstellen Sie ein kostenloses Azure-Konto, bevor Sie beginnen.

Voraussetzungen

Die folgenden Voraussetzungen gelten für eine Windows-Entwicklungsumgebung. Informationen zu Linux oder macOS finden Sie in der SDK-Dokumentation im entsprechenden Abschnitt unter Vorbereiten Ihrer Entwicklungsumgebung.

Erstellen des Bereitstellungsdiensts und von zwei IoT-Hubs

In diesem Abschnitt verwenden Sie Azure Cloud Shell zum Erstellen eines Bereitstellungsdiensts und von zwei IoT-Hubs, die die Contoso-Abteilung „Toaster“ und die Contoso-Abteilung „Wärmepumpen“ darstellen.

  1. Legen Sie zunächst Umgebungsvariablen in Ihrem Arbeitsbereich fest, um die Befehle in diesem Lernprogramm zu vereinfachen.

    Die DPS- und IoT Hub-Namen müssen global eindeutig sein. Ersetzen Sie den Platzhalter SUFFIX durch Ihren eigenen Wert.

    Außerdem sucht der Azure-Funktionscode, den Sie später in diesem Lernprogramm erstellen, nach IoT-Hubs, die entweder -toasters- oder -heatpumps- in ihren Namen enthalten sind. Wenn Sie die vorgeschlagenen Werte ändern, stellen Sie sicher, dass Namen verwendet werden, die die erforderlichen Teilzeichenfolgen enthalten.

    #!/bin/bash
export RESOURCE_GROUP="contoso-us-resource-group"
export LOCATION="westus"
export DPS="contoso-provisioning-service-SUFFIX"
export TOASTER_HUB="contoso-toasters-hub-SUFFIX"
export HEATPUMP_HUB="contoso-heatpumps-hub-SUFFIX"

    # PowerShell
$env:RESOURCE_GROUP = "contoso-us-resource-group"
$env:LOCATION = "westus"
$env:DPS = "contoso-provisioning-service-SUFFIX"
$env:TOASTER_HUB = "contoso-toasters-hub-SUFFIX"
$env:HEATPUMP_HUB = "contoso-heatpumps-hub-SUFFIX"

    Tipp

    Die in diesem Lernprogramm verwendeten Befehle erstellen standardmäßig Ressourcen am US-Amerikanischen Standort "Westen". Es wird empfohlen, die Ressourcen in der nächstgelegenen Region zu erstellen, die den Device Provisioning-Dienst unterstützt. Sie können eine Liste mit den verfügbaren Standorten anzeigen. Navigieren Sie zur Seite Azure-Status, und suchen Sie nach „Device Provisioning-Dienst“. In Befehlen können Standorte entweder als einzelnes Wort oder mit mehreren Wörtern (beispielsweise „westus“, „West US“, „WEST US“ usw.) angegeben werden. Die Groß-/Kleinschreibung spielt hierbei keine Rolle.

  2. Benutzen Sie den Befehl az group create zum Erstellen einer Azure-Ressourcengruppe. Eine Azure-Ressourcengruppe ist ein logischer Container, in dem Azure-Ressourcen bereitgestellt und verwaltet werden.

    Im folgenden Beispiel wird eine Ressourcengruppe erstellt. Wir empfehlen, dass Sie eine einzelne Gruppe für alle in diesem Tutorial erstellten Ressourcen verwenden. Dies erleichtert das Bereinigen, nachdem Sie die Schritte in diesem Artikel ausgeführt haben.

    az group create --name $RESOURCE_GROUP --location $LOCATION

  3. Verwenden Sie den Befehl "az iot dps create ", um eine Instanz des Gerätebereitstellungsservice (DPS) zu erstellen. Der Bereitstellungsdienst wird zu contoso-us-resource-group hinzugefügt.

    az iot dps create --name $DPS --resource-group $RESOURCE_GROUP --location $LOCATION

    Die Ausführung dieses Befehls kann einige Minuten dauern.

  4. Verwenden Sie den Befehl "az iot hub create", um den IoT-Hub Contoso Toasters Division zu erstellen. Der IoT-Hub wird zu contoso-us-resource-group hinzugefügt.

    az iot hub create --name $TOASTER_HUB --resource-group $RESOURCE_GROUP --location $LOCATION --sku S1

    Die Ausführung dieses Befehls kann einige Minuten dauern.

  5. Verwenden Sie den Befehl "az iot hub create " zum Erstellen des IoT-Hubs der Contoso-Wärmepumpenabteilung. Dieser IoT-Hub wird auch der "contoso-us-resource-group" hinzugefügt.

    az iot hub create --name $HEATPUMP_HUB --resource-group $RESOURCE_GROUP --location $LOCATION --sku S1

    Die Ausführung dieses Befehls kann einige Minuten dauern.

  6. Führen Sie die zwei folgenden Befehle aus, um die Verbindungszeichenfolgen für Ihre erstellten Hubs abzurufen.

    az iot hub connection-string show --hub-name $TOASTER_HUB --key primary --query connectionString -o tsv
az iot hub connection-string show --hub-name $HEATPUMP_HUB --key primary --query connectionString -o tsv

  7. Führen Sie die folgenden Befehle aus, um die Hubs mit der DPS-Ressource zu verknüpfen. Ersetzen Sie die Platzhalter durch die Hubverbindungszeichenfolgen aus dem vorherigen Schritt.

    az iot dps linked-hub create --dps-name $DPS --resource-group $RESOURCE_GROUP --location $LOCATION --connection-string <toaster_hub_connection_string>
az iot dps linked-hub create --dps-name $DPS --resource-group $RESOURCE_GROUP --location $LOCATION --connection-string <heatpump_hub_connection_string>

Erstellen der benutzerdefinierten Zuordnungsfunktion

In diesem Abschnitt erstellen Sie eine Azure-Funktion, die Ihre benutzerdefinierte Zuordnungsrichtlinie implementiert. Diese Funktion legt fest, bei welchem Abteilungs-IoT-Hub ein Gerät registriert werden soll, abhängig davon, ob die Registrierungs-ID die Zeichenfolge -contoso-tstrsd-007 oder -contoso-hpsd-088 enthält. Außerdem wird der Anfangszustand des Gerätezwillings festgelegt, je nachdem, ob es sich bei dem Gerät um einen Toaster oder eine Wärmepumpe handelt.

  1. Melden Sie sich beim Azure-Portal an.

  2. Suchen Sie im Suchfeld nach der Funktions-App, und wählen Sie sie aus.

  3. Wählen Sie " Funktions-App erstellen " oder "Funktions-Apperstellen" aus.

  4. Geben Sie auf der Erstellungsseite für die Funktions-App auf der Registerkarte Grundeinstellungen die folgenden Einstellungen für die neue Funktions-App ein, und wählen Sie Überprüfen und erstellen aus:

    Parameter Wert
    Abonnement Stellen Sie sicher, dass das Abonnement, in dem Sie die Ressourcen für dieses Lernprogramm erstellt haben, ausgewählt ist.
    Ressourcengruppe Wählen Sie die Ressourcengruppe aus, die Sie im vorherigen Abschnitt erstellt haben. Die im vorherigen Abschnitt bereitgestellte Standardeinstellung ist "contoso-us-resource-group".
    Name der Funktions-App Geben Sie einen Namen für Ihre Funktions-App ein.
    Möchten Sie Code oder ein Containerimage bereitstellen? Code
    Laufzeitstapel .NET
    Version Wählen Sie eine beliebige In-Prozess-Modellversion aus.
    Region Wählen Sie eine Region in Ihrer Nähe aus.

    Hinweis

    Application Insights ist standardmäßig aktiviert. Application Insights ist für dieses Tutorial nicht erforderlich, kann jedoch hilfreich sein, um Probleme zu verstehen und zu untersuchen, die bei der benutzerdefinierten Zuweisung auftreten. Wenn Sie möchten, können Sie Application Insights deaktivieren, indem Sie die Registerkarte Überwachung auswählen und dann für Application Insights aktivieren die Option Nein wählen.

    Screenshot des Formulars

  5. Wählen Sie auf der Registerkarte „Überprüfen und Erstellen“ die Option Erstellen aus, um die Funktions-App zu erstellen.

  6. Die Bereitstellung kann mehrere Minuten dauern. Wenn der Vorgang abgeschlossen ist, wählen Sie Zu Ressource wechseln aus.

  7. Wählen Sie im linken Bereich der Seite Übersicht der Funktions-App die Option Funktion erstellen aus.

    Screenshot der Auswahl der Option zum Erstellen der Funktion im Azure-Portal.

  8. Wählen Sie auf der Seite "Funktion erstellen" die VORLAGE "HTTP-Trigger " und dann " Weiter"aus.

  9. Wählen Sie auf der Registerkarte Vorlagendetails die Option Anonymals Autorisierungsstufe und dann Erstellen aus.

    Screenshot, der zeigt, wie die Autorisierungsstufe als anonym festgelegt wird.

    Tipp

    Wenn Sie die Autorisierungsstufe als Funktionbeibehalten, müssen Sie Ihre DPS-Registrierungen mit dem Funktions-API-Schlüssel konfigurieren. Weitere Informationen finden Sie unter HTTP-Trigger in Azure Functions.

  10. Wenn die Funktion HttpTrigger1 geöffnet wird, wählen Sie im linken Bereich Programmieren und testen aus. Dadurch können Sie den Code für die Funktion bearbeiten. Die Codedatei run.csx sollte zur Bearbeitung geöffnet werden.

  11. Verweisen Sie auf die erforderlichen NuGet-Pakete. Zum Erstellen des anfänglichen Gerätezwillings verwendet die benutzerdefinierte Zuordnungsfunktion Klassen, die in zwei NuGet-Paketen definiert sind, die in die Hostumgebung geladen werden müssen. In Azure Functions wird auf NuGet-Pakete über die function.proj verwiesen. In diesem Schritt speichern Sie die Datei function.proj für die benötigten Assemblys und laden sie hoch. Weitere Informationen finden Sie unter Verwenden von NuGet-Paketen mit Azure Functions.

    1. Kopieren Sie die folgenden Zeilen in Ihren bevorzugten Editor, und speichern Sie die Datei unter dem Namen function.proj auf Ihrem Computer.

      <Project Sdk="Microsoft.NET.Sdk">  
    <PropertyGroup>  
        <TargetFramework>netstandard2.0</TargetFramework>  
    </PropertyGroup>  
    <ItemGroup>  
        <PackageReference Include="Microsoft.Azure.Devices.Provisioning.Service" Version="1.18.1" />
        <PackageReference Include="Microsoft.Azure.Devices.Shared" Version="1.30.1" />
    </ItemGroup>  
</Project>

    2. Wählen Sie über dem Code-Editor die Schaltfläche Hochladen aus, um Ihre Datei function.proj hochzuladen. Wählen Sie nach dem Hochladen die Datei im Code-Editor über das Dropdownfeld aus, um den Inhalt zu überprüfen.

    3. Wählen Sie die Datei function.proj im Code-Editor aus, und überprüfen Sie den Inhalt. Wenn die Datei function.proj leer ist, kopieren Sie die obigen Zeilen in die Datei, und speichern Sie sie. (Manchmal erstellt der Upload die Datei, ohne den Inhalt hochzuladen.)

  12. Stellen Sie sicher, dass im Code-Editor run.csx für HttpTrigger1 ausgewählt ist. Ersetzen Sie den Code für die HttpTrigger1-Funktion durch den folgenden Code, und wählen Sie Speichern aus:

    #r "Newtonsoft.Json"

using System.Net;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Primitives;
using Newtonsoft.Json;

using Microsoft.Azure.Devices.Shared;               // For TwinCollection
using Microsoft.Azure.Devices.Provisioning.Service; // For TwinState

public static async Task<IActionResult> Run(HttpRequest req, ILogger log)
{
    log.LogInformation("C# HTTP trigger function processed a request.");

    // Get request body
    string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
    dynamic data = JsonConvert.DeserializeObject(requestBody);

    log.LogInformation("Request.Body:...");
    log.LogInformation(requestBody);

    // Get registration ID of the device
    string regId = data?.deviceRuntimeContext?.registrationId;

    string message = "Uncaught error";
    bool fail = false;
    ResponseObj obj = new ResponseObj();

    if (regId == null)
    {
        message = "Registration ID not provided for the device.";
        log.LogInformation("Registration ID : NULL");
        fail = true;
    }
    else
    {
        string[] hubs = data?.linkedHubs?.ToObject<string[]>();

        // Must have hubs selected on the enrollment
        if (hubs == null)
        {
            message = "No hub group defined for the enrollment.";
            log.LogInformation("linkedHubs : NULL");
            fail = true;
        }
        else
        {
            // This is a Contoso Toaster Model 007
            if (regId.Contains("-contoso-tstrsd-007"))
            {
                //Find the "-toasters-" IoT hub configured on the enrollment
                foreach(string hubString in hubs)
                {
                    if (hubString.Contains("-toasters-"))
                        obj.iotHubHostName = hubString;
                }

                if (obj.iotHubHostName == null)
                {
                    message = "No toasters hub found for the enrollment.";
                    log.LogInformation(message);
                    fail = true;
                }
                else
                {
                    // Specify the initial tags for the device.
                    TwinCollection tags = new TwinCollection();
                    tags["deviceType"] = "toaster";

                    // Specify the initial desired properties for the device.
                    TwinCollection properties = new TwinCollection();
                    properties["state"] = "ready";
                    properties["darknessSetting"] = "medium";

                    // Add the initial twin state to the response.
                    TwinState twinState = new TwinState(tags, properties);
                    obj.initialTwin = twinState;
                }
            }
            // This is a Contoso Heat pump Model 008
            else if (regId.Contains("-contoso-hpsd-088"))
            {
                //Find the "-heatpumps-" IoT hub configured on the enrollment
                foreach(string hubString in hubs)
                {
                    if (hubString.Contains("-heatpumps-"))
                        obj.iotHubHostName = hubString;
                }

                if (obj.iotHubHostName == null)
                {
                    message = "No heat pumps hub found for the enrollment.";
                    log.LogInformation(message);
                    fail = true;
                }
                else
                {
                    // Specify the initial tags for the device.
                    TwinCollection tags = new TwinCollection();
                    tags["deviceType"] = "heatpump";

                    // Specify the initial desired properties for the device.
                    TwinCollection properties = new TwinCollection();
                    properties["state"] = "on";
                    properties["temperatureSetting"] = "65";

                    // Add the initial twin state to the response.
                    TwinState twinState = new TwinState(tags, properties);
                    obj.initialTwin = twinState;
                }
            }
            // Unrecognized device.
            else
            {
                fail = true;
                message = "Unrecognized device registration.";
                log.LogInformation("Unknown device registration");
            }
        }
    }

    log.LogInformation("\nResponse");
    log.LogInformation((obj.iotHubHostName != null) ? JsonConvert.SerializeObject(obj) : message);

    return (fail)
        ? new BadRequestObjectResult(message) 
        : (ActionResult)new OkObjectResult(obj);
}

public class ResponseObj
{
    public string iotHubHostName {get; set;}
    public TwinState initialTwin {get; set;}
}

Erstellen der Registrierung

In diesem Abschnitt erstellen Sie eine neue Registrierungsgruppe, die die benutzerdefinierte Zuweisungsrichtlinie verwendet. Der Einfachheit halber wird in diesem Tutorial ein Nachweis des symmetrischen Schlüssels bei der Registrierung verwendet. Für eine Lösung mit höherer Sicherheit empfiehlt sich die Verwendung eines X.509-Zertifikatnachweises mit einer Kette von Vertrauensstellungen.

  1. Melden Sie sich beim Azure-Portal an, und navigieren Sie zur Dienstinstanz für die Gerätebereitstellung.

  2. Wählen Sie im Navigationsmenü im Abschnitt Einstellungen die Option Registrierungen verwalten aus.

  3. Wählen Sie Registrierungsgruppe hinzufügen aus.

  4. Geben Sie auf der Registerkarte Registrierung + Bereitstellung der Seite Registrierungsgruppe hinzufügen die folgenden Informationen an, um die Details der Registrierungsgruppe zu konfigurieren:

    Feld Beschreibung
    Nachweis Wählen Sie Symmetrischer Schlüssel als Nachweismechanismus aus.
    Einstellungen für symmetrische Schlüssel Aktivieren Sie das Kontrollkästchen Symmetrische Schlüssel automatisch generieren.
    Gruppenname Geben Sie contoso-custom-allocated-devices als Gruppenname ein.
    Bereitstellungsstatus Aktivieren Sie das Kontrollkästchen Diese Registrierung aktivieren.

  5. Wählen Sie Weiter: IoT-Hubs aus.

  6. Geben Sie auf der Registerkarte IoT-Hubs der Seite Registrierungsgruppe hinzufügen die folgenden Informationen an, um zu bestimmen, für welche IoT-Hubs die Registrierungsgruppe Geräte bereitstellen kann:

    Feld Beschreibung
    Ziel-IoT-Hubs Wählen Sie einen oder mehrere Ihrer verknüpften IoT-Hubs aus, oder fügen Sie einem IoT-Hub einen neuen Link hinzu.
    Zuordnungsrichtlinie Wählen Sie Benutzerdefiniert (Azure-Funktion verwenden) aus. Wählen Sie Azure-Funktion auswählen aus, und folgen Sie dann den Anweisungen, um die Funktion auszuwählen, die Sie für dieses Tutorial erstellt haben.

  7. Klicken Sie auf Überprüfen + erstellen.

  8. Überprüfen Sie auf der Registerkarte Überprüfen + erstellen all Ihre Werte, und wählen Sie dann Erstellen aus.

Öffnen Sie die Registrierungsgruppe nach dem Speichern erneut, und notieren Sie sich den Primärschlüssel. Sie müssen die Registrierung speichern, damit die Schlüssel generiert werden. Dieser Schlüssel wird verwendet, um eindeutige Geräteschlüssel für simulierte Geräte im nächsten Abschnitt zu generieren.

Ableiten eindeutiger Geräteschlüssel

Geräte verwenden den primären symmetrischen Schlüssel der Registrierungsgruppe nicht direkt. Stattdessen verwenden Sie den primären Schlüssel zum Ableiten eines Geräteschlüssels für die einzelnen Geräte. In diesem Abschnitt erstellen Sie zwei eindeutige Geräteschlüssel. Ein Schlüssel wird für einen simulierten Toaster verwendet. Der andere Schlüssel wird für eine simulierte Wärmepumpe verwendet.

Zum Ableiten des Geräteschlüssels verwenden Sie den Primärschlüssel der Registrierungsgruppe, den Sie sich zuvor notiert haben, um die HMAC-SHA256-Verschlüsselung der Geräteregistrierungs-ID für die einzelnen Geräte zu berechnen und das Ergebnis in das Base64-Format zu konvertieren. Weitere Informationen zum Erstellen von abgeleiteten Geräteschlüsseln mit Registrierungsgruppen finden Sie im Abschnitt Gruppenregistrierungen unter Nachweis des symmetrischen Schlüssels.

Verwenden Sie für das Beispiel in diesem Tutorial die folgenden beiden Geräteregistrierungs-IDs, und berechnen Sie einen Geräteschlüssel für beide Geräte. Beide Registrierungs-IDs haben ein gültiges Suffix für den Beispielcode der benutzerdefinierten Zuweisungsrichtlinie:

  • breakroom499-contoso-tstrsd-007
  • mainbuilding167-contoso-hpsd-088

Die IoT-Erweiterung für die Azure CLI stellt den Befehl iot dps enrollment-group compute-device-key zum Generieren abgeleiteter Geräteschlüssel bereit. Dieser Befehl kann auf Windows- oder Linux-Systemen, über PowerShell oder eine Bash-Shell verwendet werden.

Ersetzen Sie den Wert des --key-Arguments durch den Primärschlüssel aus Ihrer Registrierungsgruppe.

az iot dps enrollment-group compute-device-key --key <ENROLLMENT_GROUP_KEY> --registration-id breakroom499-contoso-tstrsd-007

az iot dps enrollment-group compute-device-key --key <ENROLLMENT_GROUP_KEY> --registration-id mainbuilding167-contoso-hpsd-088

Hinweis

Sie können auch die Registrierungsgruppen-ID anstelle des symmetrischen Schlüssels für den Befehl iot dps enrollment-group compute-device-key angeben. Zum Beispiel:

az iot dps enrollment-group compute-device-key -g contoso-us-resource-group --dps-name contoso-provisioning-service-1098 --enrollment-id contoso-custom-allocated-devices --registration-id breakroom499-contoso-tstrsd-007

Die simulierten Geräte benutzen die abgeleiteten Geräteschlüssel mit der jeweiligen Registrierungs-ID für den Nachweis des symmetrischen Schlüssels.

Vorbereiten einer Azure IoT C SDK-Entwicklungsumgebung

In diesem Abschnitt bereiten Sie die Entwicklungsumgebung vor, die zum Erstellen des Azure IoT C SDK verwendet wird. Das SDK enthält den Beispielcode für das simulierte Gerät. Dieses simulierte Gerät versucht, die Bereitstellung während seiner Startsequenz auszuführen.

In diesem Abschnitt wird eine Windows-Arbeitsstation vorausgesetzt. Ein Beispiel für Linux finden Sie in der Beschreibung der VM-Einrichtung im Tutorial: Bereitstellen für Geolatenz.

  1. Laden Sie das CMake-Buildsystem herunter.

    Wichtig: Die Voraussetzungen für Visual Studio (Visual Studio und die Workload „Desktopentwicklung mit C++“) müssen vor Beginn der Installation von CMake auf dem Computer installiert sein. Sobald die Voraussetzungen erfüllt sind und der Download überprüft wurde, installieren Sie das CMake-Buildsystem.

  2. Suchen Sie den Tagnamen für das aktuelle Release des SDK.

  3. Öffnen Sie eine Eingabeaufforderung oder die Git Bash-Shell. Führen Sie die folgenden Befehle aus, um das aktuelle Release des GitHub-Repositorys für das Azure IoT Device SDK für C zu klonen. Verwenden Sie das im vorherigen Schritt gefundene Tag als Wert für den Parameter -b, z. B. lts_01_2023.

    git clone -b <release-tag> https://github.com/Azure/azure-iot-sdk-c.git
cd azure-iot-sdk-c
git submodule update --init

    Sie sollten damit rechnen, dass die Ausführung dieses Vorgangs mehrere Minuten in Anspruch nimmt.

  4. Erstellen Sie ein cmake-Unterverzeichnis im Stammverzeichnis des Git-Repositorys, und navigieren Sie zu diesem Ordner. Führen Sie die folgenden Befehle im azure-iot-sdk-c-Verzeichnis aus:

    mkdir cmake
cd cmake

  5. Erstellen Sie mithilfe des folgenden Befehls eine spezifische SDK-Version für Ihre Entwicklungsclientplattform: Im cmake-Verzeichnis wird eine Visual Studio-Projektmappe für das simulierte Gerät generiert.

    cmake -Dhsm_type_symm_key:BOOL=ON -Duse_prov_client:BOOL=ON  ..

    Wenn cmake Ihren C++-Compiler nicht findet, treten beim Ausführen des Befehls unter Umständen Buildfehler auf. Führen Sie den Befehl in diesem Fall an der Visual Studio-Eingabeaufforderung aus.

    Nach erfolgreicher Erstellung ähneln die letzten Ausgabezeilen der folgenden Ausgabe:

    $ cmake -Dhsm_type_symm_key:BOOL=ON -Duse_prov_client:BOOL=ON  ..
-- Building for: Visual Studio 15 2017
-- Selecting Windows SDK version 10.0.16299.0 to target Windows 10.0.17134.
-- The C compiler identification is MSVC 19.12.25835.0
-- The CXX compiler identification is MSVC 19.12.25835.0

...

-- Configuring done
-- Generating done
-- Build files have been written to: E:/IoT Testing/azure-iot-sdk-c/cmake

Simulieren der Geräte

In diesem Abschnitt aktualisieren Sie ein Bereitstellungsbeispiel namens prov_dev_client_sample im Azure IoT C SDK, das Sie zuvor eingerichtet haben.

Dieser Beispielcode simuliert eine Gerätestartsequenz, von der die Bereitstellungsanforderung an die Instanz des Device Provisioning Service gesendet wird. Die Startsequenz bewirkt, dass der Toaster erkannt und mithilfe der benutzerdefinierten Zuweisungsrichtlinie dem IoT-Hub zugewiesen wird.

  1. Navigieren Sie im Azure-Portal zur Registerkarte Übersicht für Ihre Device Provisioning Service-Instanz, und notieren Sie sich den Wert unter ID-Bereich.

    Extrahieren von Informationen zum Device Provisioning Service-Endpunkt aus dem Portalblatt

  2. Öffnen Sie in Visual Studio die Projektmappendatei azure_iot_sdks.sln, die zuvor durch das Ausführen von CMake generiert wurde. Die Projektmappendatei befindet sich am folgenden Speicherort: azure-iot-sdk-c\cmake\azure_iot_sdks.sln.

  3. Navigieren Sie im Visual Studio-Fenster Projektmappen-Explorer zum Ordner Provision_Samples. Erweitern Sie das Beispielprojekt prov_dev_client_sample. Erweitern Sie Quelldateien, und öffnen Sie prov_dev_client_sample.c.

  4. Suchen Sie die Konstante id_scope, und ersetzen Sie den Wert durch Ihren ID-Bereich-Wert, den Sie zuvor kopiert haben.

    static const char* id_scope = "0ne00002193";

  5. Suchen Sie die Definition für die Funktion main() in der gleichen Datei. Stellen Sie sicher, dass die Variable hsm_type wie unten dargestellt auf SECURE_DEVICE_TYPE_SYMMETRIC_KEY festgelegt ist:

    SECURE_DEVICE_TYPE hsm_type;
//hsm_type = SECURE_DEVICE_TYPE_TPM;
//hsm_type = SECURE_DEVICE_TYPE_X509;
hsm_type = SECURE_DEVICE_TYPE_SYMMETRIC_KEY;

  6. Suchen Sie in der Funktion main() den Aufruf von Prov_Device_Register_Device(). Fügen Sie direkt vor diesem Aufruf die folgenden Codezeilen hinzu, die Prov_Device_Set_Provisioning_Payload() verwenden, um während der Bereitstellung eine benutzerdefinierte JSON-Nutzlast zu übergeben. Damit können weitere Informationen für Ihre benutzerdefinierten Zuordnungsfunktionen bereitgestellt werden. Darüber hinaus kann damit der Gerätetyp übergeben werden, anstatt die Registrierungs-ID zu überprüfen. Weitere Informationen zum Senden und Empfangen von benutzerdefinierten Datennutzlasten mit DPS finden Sie unter Übertragen einer Nutzlast zwischen Gerät und DPS.

    // An example custom payload
const char* custom_json_payload = "{\"MyDeviceFirmwareVersion\":\"12.0.2.5\",\"MyDeviceProvisioningVersion\":\"1.0.0.0\"}";

prov_device_result = Prov_Device_Set_Provisioning_Payload(prov_device_handle, custom_json_payload);
if (prov_device_result != PROV_DEVICE_RESULT_OK)
{
    (void)printf("\r\nFailure setting provisioning payload: %s\r\n", MU_ENUM_TO_STRING(PROV_DEVICE_RESULT, prov_device_result));
}

  7. Klicken Sie mit der rechten Maustaste auf das Projekt prov_dev_client_sample, und wählen Sie Als Startprojekt festlegen aus.

Simulieren des Contoso-Toasters

  1. Suchen Sie zum Simulieren des Toasters nach dem Aufruf von prov_dev_set_symmetric_key_info() in prov_dev_client_sample.c. Der Aufruf ist auskommentiert.

    // Set the symmetric key if using they auth type
//prov_dev_set_symmetric_key_info("<symm_registration_id>", "<symmetric_Key>");

    Heben Sie die Auskommentierung für den Funktionsaufruf auf, und ersetzen Sie die Platzhalterwerte (einschließlich der spitzen Klammern) durch die Registrierungs-ID für den Toaster und den von Ihnen zuvor generierten abgeleiteten Geräteschlüssel. Der unten angegebene Schlüsselwert JC8F96eayuQwwz+PkE7IzjH2lIAjCUnAa61tDigBnSs= dient nur als Beispiel.

    // Set the symmetric key if using they auth type
prov_dev_set_symmetric_key_info("breakroom499-contoso-tstrsd-007", "JC8F96eayuQwwz+PkE7IzjH2lIAjCUnAa61tDigBnSs=");

    Speichern Sie die Datei .

  2. Wählen Sie im Visual Studio-Menü die Option Debuggen>Starten ohne Debugging aus, um die Projektmappe auszuführen. Wählen Sie in der Aufforderung zum erneuten Erstellen des Projekts Ja aus, um das Projekt vor der Ausführung neu zu erstellen.

    Die folgende Ausgabe ist ein Beispiel für einen erfolgreichen Start des Toasters und das Herstellen der Verbindung mit der Instanz des Bereitstellungsdiensts, die durch die benutzerdefinierte Zuweisungsrichtlinie dem IoT-Hub für den Toaster zugewiesen werden soll:

    Provisioning API Version: 1.8.0

Registering Device

Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING

Registration Information received from service: contoso-toasters-hub-1098.azure-devices.net, deviceId: breakroom499-contoso-tstrsd-007

Press enter key to exit:

    Die nachstehende Ausgabe ist eine Beispielprotokollierungsausgabe aus dem Code der benutzerdefinierten Zuweisungsfunktion für den Toaster. Beachten Sie, dass ein Hub für einen Toaster erfolgreich ausgewählt wurde. Beachten Sie auch die Eigenschaft payload, die den benutzerdefinierten JSON-Inhalt enthält, den Sie dem Code hinzugefügt haben. Dieser steht dem Code zur Verwendung in deviceRuntimeContext zur Verfügung.

    Diese Protokollierung steht zur Verfügung, wenn Sie unter dem Funktionscode im Portal auf Protokolle klicken:

    2022-08-03T20:34:41.178 [Information] Executing 'Functions.HttpTrigger1' (Reason='This function was programmatically called via the host APIs.', Id=12950752-6d75-4f41-844b-c253a6653d4f)
2022-08-03T20:34:41.340 [Information] C# HTTP trigger function processed a request.
2022-08-03T20:34:41.341 [Information] Request.Body:...
2022-08-03T20:34:41.341 [Information] {"enrollmentGroup":{"enrollmentGroupId":"contoso-custom-allocated-devices","attestation":{"type":"symmetricKey"},"capabilities":{"iotEdge":false},"etag":"\"0000f176-0000-0700-0000-62eaad1e0000\"","provisioningStatus":"enabled","reprovisionPolicy":{"updateHubAssignment":true,"migrateDeviceData":true},"createdDateTimeUtc":"2022-08-03T17:15:10.8464255Z","lastUpdatedDateTimeUtc":"2022-08-03T17:15:10.8464255Z","allocationPolicy":"custom","iotHubs":["contoso-toasters-hub-1098.azure-devices.net","contoso-heatpumps-hub-1098.azure-devices.net"],"customAllocationDefinition":{"webhookUrl":"https://contoso-function-app-1098.azurewebsites.net/api/HttpTrigger1?****","apiVersion":"2021-10-01"}},"deviceRuntimeContext":{"registrationId":"breakroom499-contoso-tstrsd-007","currentIotHubHostName":"contoso-toasters-hub-1098.azure-devices.net","currentDeviceId":"breakroom499-contoso-tstrsd-007","symmetricKey":{},"payload":{"MyDeviceFirmwareVersion":"12.0.2.5","MyDeviceProvisioningVersion":"1.0.0.0"}},"linkedHubs":["contoso-toasters-hub-1098.azure-devices.net","contoso-heatpumps-hub-1098.azure-devices.net"]}
2022-08-03T20:34:41.382 [Information] Response
2022-08-03T20:34:41.398 [Information] {"iotHubHostName":"contoso-toasters-hub-1098.azure-devices.net","initialTwin":{"properties":{"desired":{"state":"ready","darknessSetting":"medium"}},"tags":{"deviceType":"toaster"}}}
2022-08-03T20:34:41.399 [Information] Executed 'Functions.HttpTrigger1' (Succeeded, Id=12950752-6d75-4f41-844b-c253a6653d4f, Duration=227ms)

Simulieren der Contoso-Wärmepumpe

  1. Aktualisieren Sie zum Simulieren der Wärmepumpe den Aufruf von prov_dev_set_symmetric_key_info() in prov_dev_client_sample.c erneut mit der Registrierungs-ID der Wärmepumpe und dem von Ihnen zuvor generierten abgeleiteten Geräteschlüssel. Der unten angegebene Schlüsselwert 6uejA9PfkQgmYylj8Zerp3kcbeVrGZ172YLa7VSnJzg= dient ebenfalls nur als Beispiel.

    // Set the symmetric key if using they auth type
prov_dev_set_symmetric_key_info("mainbuilding167-contoso-hpsd-088", "6uejA9PfkQgmYylj8Zerp3kcbeVrGZ172YLa7VSnJzg=");

    Speichern Sie die Datei .

  2. Wählen Sie im Visual Studio-Menü die Option Debuggen>Starten ohne Debugging aus, um die Projektmappe auszuführen. Wählen Sie in der Eingabeaufforderung zum Neuerstellen des Projekts Ja, um das Projekt vor der Ausführung neu zu erstellen.

    Die folgende Ausgabe ist ein Beispiel für einen erfolgreichen Start der Wärmepumpe und das Herstellen der Verbindung mit der Instanz des Bereitstellungsdiensts, die durch die benutzerdefinierte Zuweisungsrichtlinie dem IoT-Hub für die Contoso-Wärmepumpe zugewiesen werden soll:

    Provisioning API Version: 1.8.0

Registering Device

Provisioning Status: PROV_DEVICE_REG_STATUS_CONNECTED
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING
Provisioning Status: PROV_DEVICE_REG_STATUS_ASSIGNING

Registration Information received from service: contoso-heatpumps-hub-1098.azure-devices.net, deviceId: mainbuilding167-contoso-hpsd-088

Press enter key to exit:

Behandlung von Problemen bei benutzerdefinierten Zuweisungsrichtlinien

Die folgende Tabelle enthält die erwarteten Szenarien und die resultierenden Fehlercodes, die Sie möglicherweise empfangen. Greifen Sie auf diese Tabelle zurück, um Fehler bei benutzerdefinierten Zuweisungsrichtlinien mit Azure Functions zu beheben.

Szenario Registrierungsergebnis des Provisioning Service Ergebnisse des Bereitstellungs-SDK
Der Webhook gibt „200 OK“ zurück, und „iotHubHostName“ ist auf einen gültigen IoT-Hub-Hostnamen festgelegt. Ergebnisstatus: Zugewiesen Das SDK gibt „PROV_DEVICE_RESULT_OK“ zusammen mit Hubinformationen zurück.
Der Webhook gibt „200 OK“ zurück, und „iotHubHostName“ ist in der Antwort vorhanden, jedoch auf eine leere Zeichenfolge oder NULL festgelegt. Ergebnisstatus: Fehler

Fehlercode: CustomAllocationIotHubNotSpecified (400208)		 Das SDK gibt „PROV_DEVICE_RESULT_HUB_NOT_SPECIFIED“ zurück.
Der Webhook gibt „401 – Nicht autorisiert“ zurück. Ergebnisstatus: Fehler

Fehlercode: CustomAllocationUnauthorizedAccess (400209)		 Das SDK gibt „PROV_DEVICE_RESULT_UNAUTHORIZED“ zurück.
Es wurde eine individuelle Registrierung erstellt, um das Gerät zu deaktivieren. Ergebnisstatus: Disabled Das SDK gibt „PROV_DEVICE_RESULT_DISABLED“ zurück.
Der Webhook gibt einen Fehlercode >= 429 zurück. Die Orchestrierung des DPS wird mehrmals wiederholt. Die Wiederholungsrichtlinie lautet derzeit:

  – Wiederholungsanzahl: 10
  – Anfängliches Intervall: 1 s
  – Inkrement: 9 s		 Das SDK ignoriert den Fehler und übermittelt im angegebenen Zeitraum eine weitere Statusabrufmeldung.
Der Webhook gibt einen anderen Statuscode zurück. Ergebnisstatus: Fehler

Fehlercode: CustomAllocationFailed (400207)		 Das SDK gibt „PROV_DEVICE_RESULT_DEV_AUTH_ERROR“ zurück.

Bereinigen von Ressourcen

Wenn Sie die in diesem Tutorial erstellten Ressourcen weiterverwenden möchten, können Sie sie beibehalten. Wenn Sie nicht beabsichtigen, die Ressourcen weiterzuverwenden, führen Sie die folgenden Schritte aus, um alle in diesem Tutorial erstellten Ressourcen zu löschen und unnötige Kosten zu vermeiden.

Diese Schritte setzen voraus, dass Sie alle Ressourcen in diesem Tutorial wie beschrieben in derselben Ressourcengruppe mit dem Namen contoso-us-resource-group erstellt haben.

Wichtig

Das Löschen einer Ressourcengruppe kann nicht rückgängig gemacht werden. Die Ressourcengruppe und alle darin enthaltenen Ressourcen werden unwiderruflich gelöscht. Achten Sie daher darauf, dass Sie nicht versehentlich die falsche Ressourcengruppe oder die falschen Ressourcen löschen. Wenn Sie die IoT Hub-Ressource in einer bereits vorhandenen Ressourcengruppe erstellt haben, die Ressourcen enthält, die Sie behalten möchten, löschen Sie nicht die Ressourcengruppe, sondern nur die IoT Hub-Ressource.

Löschen Sie die Ressourcengruppen wie folgt nach Namen:

  1. Melden Sie sich beim Azure-Portal an, und klicken Sie auf Ressourcengruppen.

  2. Geben Sie im Textfeld Nach Name filtern... den Namen der Ressourcengruppe ein, die Ihre Ressourcen enthält: contoso-us-resource-group.

  3. Wählen Sie in der Ergebnisliste rechts neben Ihrer Ressourcengruppe ... und dann Ressourcengruppe löschen aus.

  4. Sie werden aufgefordert, das Löschen der Ressourcengruppe zu bestätigen. Geben Sie den Namen Ihrer Ressourcengruppe zur Bestätigung erneut ein, und wählen Sie Löschen aus. Daraufhin werden die Ressourcengruppe und alle darin enthaltenen Ressourcen gelöscht.

Nächste Schritte

Weitere Informationen zu benutzerdefinierten Zuweisungsrichtlinien finden Sie unter

Grundlegendes zu benutzerdefinierten Zuweisungsrichtlinien