Aan de slag met apparaatdubbels (.NET)

Artikel
01/29/2024

Apparaatdubbels zijn JSON-documenten waarin statusinformatie van een apparaat zijn opgeslagen, zoals metagegevens, configuraties en voorwaarden. IoT Hub houdt een apparaatdubbel vast voor elk apparaat dat er verbinding mee maakt.

Notitie

De functies die in dit artikel worden beschreven, zijn alleen beschikbaar in de standaardlaag van de IoT Hub. Zie De juiste IoT Hub-laag voor uw oplossing kiezen voor meer informatie over de Basic- en Standard-/gratis IoT Hub-lagen.

Apparaatdubbels gebruiken om:

Sla metagegevens van apparaten op vanuit de back-end van uw oplossing.
Rapporteer actuele statusinformatie, zoals beschikbare mogelijkheden en voorwaarden, bijvoorbeeld de gebruikte connectiviteitsmethode vanuit uw apparaat-app.
Synchroniseer de status van langlopende werkstromen, zoals firmware- en configuratie-updates, tussen een apparaat-app en een back-end-app.
Voer een query uit op de metagegevens, configuratie of status van uw apparaat.

Apparaatdubbels zijn ontworpen voor synchronisatie en voor het opvragen van apparaatconfiguraties en -voorwaarden. Zie Apparaatdubbels begrijpen voor meer informatie over apparaatdubbels, inclusief wanneer u apparaatdubbels gebruikt.

IoT Hubs slaan apparaatdubbels op, die de volgende elementen bevatten:

Tags. Metagegevens van apparaten die alleen toegankelijk zijn voor de back-end van de oplossing.
Gewenste eigenschappen. JSON-objecten kunnen worden gewijzigd door de back-end van de oplossing en waarneembaar door de apparaat-app.
Gerapporteerde eigenschappen. JSON-objecten kunnen worden gewijzigd door de apparaat-app en kunnen worden gelezen door de back-end van de oplossing.

Tags en eigenschappen kunnen geen matrices bevatten, maar kunnen geneste objecten bevatten.

In de volgende afbeelding ziet u de organisatie van apparaatdubbels:

Schermopname van een conceptdiagram van een apparaatdubbel.

Daarnaast kan de back-end van de oplossing een query uitvoeren op apparaatdubbels op basis van alle bovenstaande gegevens. Zie Apparaatdubbels begrijpen voor meer informatie over apparaatdubbels. Zie de Querytaal van IoT Hub voor meer informatie over het uitvoeren van query's.

Dit artikel laat het volgende zien:

Gebruik een gesimuleerde apparaat-app om het connectiviteitskanaal te rapporteren als een gerapporteerde eigenschap op de apparaatdubbel.
Query's uitvoeren op apparaten vanuit uw back-end-app met behulp van filters op de tags en eigenschappen die u eerder hebt gemaakt.

In dit artikel maakt u twee .NET-console-apps:

AddTagsAndQuery: een back-end-app waarmee tags en query's op apparaatdubbels worden toegevoegd.
Rapport Verbinding maken iviteit: een gesimuleerde apparaat-app die verbinding maakt met uw IoT-hub en de connectiviteitsvoorwaarde rapporteert.

Notitie

Zie Azure IoT SDK's voor meer informatie over de SDK-hulpprogramma's die beschikbaar zijn voor het bouwen van zowel apparaat- als back-end-apps.

Vereisten

Visual Studio.
Een IoT-hub. Maak er een met de CLI of Azure Portal.
Een geregistreerd apparaat. Registreer er een in Azure Portal.
Zorg ervoor dat de poort 8883 is geopend in uw firewall. Het apparaatvoorbeeld in dit artikel maakt gebruik van het MQTT-protocol, dat via poort 8883 communiceert. Deze poort is in sommige netwerkomgevingen van bedrijven en onderwijsinstellingen mogelijk geblokkeerd. Zie Verbinding maken met IoT Hub (MQTT) voor meer informatie en manieren om dit probleem te omzeilen.

De IoT Hub-verbindingsreeks ophalen

In dit artikel maakt u een back-endservice die gewenste eigenschappen toevoegt aan een apparaatdubbel en vervolgens het identiteitsregister opvraagt om alle apparaten met gerapporteerde eigenschappen te vinden dienovereenkomstig zijn bijgewerkt. Uw service heeft de serviceverbindingsmachtiging nodig om de gewenste eigenschappen van een apparaatdubbel te wijzigen en heeft de leesmachtiging voor het register nodig om een query uit te voeren op het identiteitsregister. Er is geen standaardbeleid voor gedeelde toegang dat alleen deze twee machtigingen bevat, dus u moet er een maken.

Voer de volgende stappen uit om een gedeeld toegangsbeleid te maken dat serviceverbindings- en registertoegangsmachtigingen verleent en een verbindingsreeks voor dit beleid op te halen:

Selecteer resourcegroepen in de Azure-portal. Selecteer de resourcegroep waar uw hub zich bevindt en selecteer vervolgens uw hub in de lijst met resources.
Selecteer in het linkerdeelvenster van uw hub beleid voor gedeelde toegang.
Selecteer in het bovenste menu boven de lijst met beleidsregels de optie Beleid voor gedeelde beleidsregels toevoegen.
Voer in het deelvenster Gedeeld toegangsbeleid aan de rechterkant een beschrijvende naam in voor uw beleid, zoals serviceAndRegistryRead. Selecteer onder Machtigingen de optie Lezen en Verbinding maken register en Service en selecteer vervolgens Toevoegen.
Selecteer uw nieuwe beleid in de lijst met beleidsregels.
Selecteer het kopieerpictogram voor de primaire verbindingsreeks en sla de waarde op.

Zie Toegangsbeheer en machtigingen voor meer informatie over beleid en machtigingen voor gedeelde toegang van IoT Hub.

Een apparaat-app maken waarmee gerapporteerde eigenschappen worden bijgewerkt

In deze sectie maakt u een .NET-console-app die verbinding maakt met uw hub als myDeviceId en werkt u vervolgens de gerapporteerde eigenschappen bij om te bevestigen dat deze is verbonden met een mobiel netwerk.

Open Visual Studio en selecteer Nieuw project maken.
Kies Console-app (.NET Framework) en selecteer vervolgens Volgende.
Geef in Het nieuwe project configureren de naam van het projectrapport Verbinding maken iviteit en selecteer vervolgens Volgende.
Klik in Solution Explorer met de rechtermuisknop op het project Rapport Verbinding maken iviteit en selecteer NuGet-pakketten beheren.
Behoud de standaard .NET Framework en selecteer Vervolgens Maken om het project te maken.
Selecteer Bladeren en zoeken naar En kies Microsoft.Azure.Devices.Client. Selecteer Installeren.

Met deze stap downloadt, installeert en voegt u een verwijzing toe naar het NuGet-pakket van de Azure IoT-apparaat-SDK en de bijbehorende afhankelijkheden.

Voeg aan het begin van het bestand Program.cs de volgende using-instructies toe:

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

Voeg de volgende velden toe aan de klasse Program: Vervang {device connection string} door het apparaat verbindingsreeks u hebt gezien toen u een apparaat hebt geregistreerd in de IoT Hub:

static string DeviceConnectionString = "HostName=<yourIotHubName>.azure-devices.net;DeviceId=<yourIotDeviceName>;SharedAccessKey=<yourIotDeviceAccessKey>";
static DeviceClient Client = null;

Voeg de volgende methode toe aan de klasse Program:

public static async void InitClient()
{
    try
    {
        Console.WriteLine("Connecting to hub");
        Client = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
          TransportType.Mqtt);
        Console.WriteLine("Retrieving twin");
        await Client.GetTwinAsync();
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }
}

Het clientobject bevat alle methoden die u nodig hebt om te communiceren met apparaatdubbels vanaf het apparaat. De bovenstaande code initialiseert het clientobject en haalt vervolgens de apparaatdubbel op voor myDeviceId.

Voeg de volgende methode toe aan de klasse Program:

public static async void ReportConnectivity()
{
    try
    {
        Console.WriteLine("Sending connectivity data as reported property");

        TwinCollection reportedProperties, connectivity;
        reportedProperties = new TwinCollection();
        connectivity = new TwinCollection();
        connectivity["type"] = "cellular";
        reportedProperties["connectivity"] = connectivity;
        await Client.UpdateReportedPropertiesAsync(reportedProperties);
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }
}

De bovenstaande code werkt de gerapporteerde eigenschap van myDeviceId bij met de connectiviteitsgegevens.

Voeg tot slot de volgende regels toe aan de methode Main:

try
{
    InitClient();
    ReportConnectivity();
}
catch (Exception ex)
{
    Console.WriteLine();
    Console.WriteLine("Error in sample: {0}", ex.Message);
}
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

Klik in Solution Explorer met de rechtermuisknop op uw oplossing en selecteer Opstartprojecten instellen.
Selecteer in Common Properties>Startup Project meerdere opstartprojecten. Voor rapport Verbinding maken iviteit selecteert u Starten als actie. Selecteer OK om uw wijzigingen op te slaan.
Voer deze app uit door met de rechtermuisknop op het project Rapport Verbinding maken iviteit te klikken en Fouten opsporen te selecteren en vervolgens een nieuw exemplaar starten. Als het goed is, ziet u dat de app de dubbele gegevens ophaalt en vervolgens connectiviteit verzendt als een gerapporteerde eigenschap.

Nadat het apparaat de connectiviteitsgegevens heeft gerapporteerd, moet het in beide query's worden weergegeven.
Klik met de rechtermuisknop op het project AddTagsAndQuery en selecteer Debug>Start new instance om de query's opnieuw uit te voeren. Deze keer moet myDeviceId worden weergegeven in beide queryresultaten.

Een service-app maken waarmee de gewenste eigenschappen worden bijgewerkt en query's worden uitgevoerd op dubbels

In deze sectie maakt u een .NET-console-app met behulp van C#, waarmee locatiemetagegevens worden toegevoegd aan de apparaatdubbel die is gekoppeld aan myDeviceId. De app vraagt IoT Hub op voor apparaten die zich in de VS bevinden en vraagt vervolgens apparaten op die een mobiele netwerkverbinding rapporteren.

Selecteer bestand > nieuw > project in Visual Studio. Selecteer in Een nieuw project maken console-app (.NET Framework) en selecteer vervolgens Volgende.
Geef in Uw nieuwe project de naam AddTagsAndQuery van het project en selecteer Volgende.
Accepteer de standaardversie van .NET Framework en selecteer vervolgens Maken om het project te maken.
Klik in Solution Explorer met de rechtermuisknop op het project AddTagsAndQuery en selecteer NuGet-pakketten beheren.
Selecteer Bladeren en zoeken naar Microsoft.Azure.Devices. Selecteer Installeren.

Met deze stap downloadt, installeert en voegt u een verwijzing toe naar het NuGet-pakket van de Azure IoT-service-SDK en de bijbehorende afhankelijkheden.
Voeg aan het begin van het bestand Program.cs de volgende using-instructies toe:
```
using Microsoft.Azure.Devices;
```
Voeg de volgende velden toe aan de klasse Program: Vervang {iot hub connection string} door de IoT Hub-verbindingsreeks die u hebt gekopieerd in De IoT-hub ophalen verbindingsreeks.
```
static RegistryManager registryManager;
static string connectionString = "{iot hub connection string}";
```

Voeg de volgende methode toe aan de klasse Program:

public static async Task AddTagsAndQuery()
{
    var twin = await registryManager.GetTwinAsync("myDeviceId");
    var patch =
        @"{
            tags: {
                location: {
                    region: 'US',
                    plant: 'Redmond43'
                }
            }
        }";
    await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);

    var query = registryManager.CreateQuery(
      "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
    var twinsInRedmond43 = await query.GetNextAsTwinAsync();
    Console.WriteLine("Devices in Redmond43: {0}", 
      string.Join(", ", twinsInRedmond43.Select(t => t.DeviceId)));

    query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
    var twinsInRedmond43UsingCellular = await query.GetNextAsTwinAsync();
    Console.WriteLine("Devices in Redmond43 using cellular network: {0}", 
      string.Join(", ", twinsInRedmond43UsingCellular.Select(t => t.DeviceId)));
}

De Klasse RegistryManager bevat alle methoden die nodig zijn om te communiceren met apparaatdubbels van de service. De vorige code initialiseert eerst het registryManager-object , haalt vervolgens de apparaatdubbel voor myDeviceId op en werkt ten slotte de tags bij met de gewenste locatiegegevens.

Na het bijwerken worden twee query's uitgevoerd: de eerste selecteert alleen de apparaatdubbels van apparaten die zich in de Redmond43-fabriek bevinden en de tweede verfijnt de query om alleen de apparaten te selecteren die ook zijn verbonden via een mobiel netwerk.

De vorige code, wanneer het queryobject wordt gemaakt, geeft een maximum aantal geretourneerde documenten op. Het queryobject bevat een Booleaanse eigenschap HasMoreResults die u kunt gebruiken om de GetNextAsTwinAsync-methoden meerdere keren aan te roepen om alle resultaten op te halen. Er is een methode met de naam GetNextAsJson beschikbaar voor resultaten die geen apparaatdubbels zijn, bijvoorbeeld resultaten van aggregatiequery's.

Voeg tot slot de volgende regels toe aan de methode Main:

registryManager = RegistryManager.CreateFromConnectionString(connectionString);
AddTagsAndQuery().Wait();
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

Voer deze toepassing uit door met de rechtermuisknop op het project AddTagsAndQuery te klikken en de foutopsporing te selecteren, gevolgd door Het nieuwe exemplaar starten. U ziet één apparaat in de resultaten voor de query waarin wordt gevraagd naar alle apparaten die zich in Redmond43 bevinden en geen voor de query die de resultaten beperkt tot apparaten die gebruikmaken van een mobiel netwerk.

In dit artikel leert u het volgende:

Metagegevens van apparaten toegevoegd als tags uit een back-end-app
Gerapporteerde apparaatverbindingsgegevens in de apparaatdubbel
Query's uitgevoerd op de gegevens van de apparaatdubbel, met sql-achtige IoT Hub-querytaal

Volgende stappen

Zie voor meer informatie over:

Telemetrie verzenden vanaf apparaten, zie quickstart: Telemetrie verzenden van een IoT-Plug en Play-apparaat naar Azure IoT Hub.
Configureer apparaten met behulp van de gewenste eigenschappen van de apparaatdubbel. Zie Zelfstudie: Uw apparaten configureren vanuit een back-endservice.
Apparaten interactief beheren, zoals het inschakelen van een ventilator vanuit een door de gebruiker beheerde app, raadpleegt u quickstart: Een apparaat beheren dat is verbonden met een IoT-hub.

Aan de slag met apparaatdubbels (.NET)

Vereisten

De IoT Hub-verbindingsreeks ophalen

Een apparaat-app maken waarmee gerapporteerde eigenschappen worden bijgewerkt

Een service-app maken waarmee de gewenste eigenschappen worden bijgewerkt en query's worden uitgevoerd op dubbels

Volgende stappen

Aanvullende resources