Ismerkedés az ikereszközökkel (.NET)

Cikk
01/29/2024

Az ikereszközök JSON-dokumentumok, amelyek az eszközök állapotinformációit, például a metaadatokat, konfigurációkat és állapotokat tárolják. Az IoT Hub minden olyan eszközhöz megőrzi az ikereszközt, amely csatlakozik hozzá.

Feljegyzés

A cikkben ismertetett funkciók csak az IoT Hub standard szintjén érhetők el. Az alapszintű és standard/ingyenes IoT Hub-szintekről további információt a megoldáshoz megfelelő IoT Hub-szint kiválasztása című témakörben talál.

Az ikereszközök használata:

Tárolja az eszköz metaadatait a megoldás háttérrendszeréből.
Jelentse az aktuális állapotinformációkat, például az elérhető képességeket és feltételeket, például a használt kapcsolati módszert az eszközalkalmazásból.
Szinkronizálja a hosszan futó munkafolyamatok állapotát, például a belső vezérlőprogramot és a konfigurációs frissítéseket egy eszközalkalmazás és egy háttéralkalmazás között.
Az eszköz metaadatainak, konfigurációjának vagy állapotának lekérdezése.

Az ikereszközök szinkronizálásra, valamint eszközkonfigurációk és feltételek lekérdezésére lettek tervezve. Az ikereszközökkel kapcsolatos további információkért, beleértve az ikereszközök használatát is, olvassa el az ikereszközök ismertetése című témakört.

Az IoT Hubs az ikereszközöket tárolja, amelyek a következő elemeket tartalmazzák:

Címkék. Az eszköz metaadatait csak a megoldás háttérrendszere érheti el.
Kívánt tulajdonságok. A megoldás háttérrendszere által módosítható és az eszközalkalmazás által megfigyelhető JSON-objektumok.
Jelentett tulajdonságok. Az eszközalkalmazás által módosítható és a megoldás háttérrendszere által olvasható JSON-objektumok.

A címkék és tulajdonságok nem tartalmazhatnak tömböket, de beágyazott objektumokat is tartalmazhatnak.

Az alábbi ábra az ikereszközök szervezetét mutatja be:

Képernyőkép egy ikereszköz-koncepciódiagramról.

Emellett a megoldás háttérrendszere az összes fenti adat alapján lekérdezheti az ikereszközöket. Az ikereszközökkel kapcsolatos további információkért tekintse meg az ikereszközökkel kapcsolatos tudnivalókat. A lekérdezéssel kapcsolatos további információkért lásd az IoT Hub lekérdezési nyelvét.

Ez a cikk bemutatja, hogyan:

Szimulált eszközalkalmazás használatával jelentse a kapcsolati csatornáját az ikereszköz jelentett tulajdonságaként.
Lekérdezheti az eszközöket a háttéralkalmazásból a korábban létrehozott címkék és tulajdonságok szűrőinek használatával.

Ebben a cikkben két .NET-konzolalkalmazást hoz létre:

AddTagsAndQuery: egy háttéralkalmazás, amely címkéket ad hozzá, és lekérdezi az ikereszközöket.
Jelentés Csatlakozás tivitás: szimulált eszközalkalmazás, amely csatlakozik az IoT Hubhoz, és jelenti a kapcsolati állapotát.

Feljegyzés

Az eszköz- és háttéralkalmazások készítéséhez elérhető SDK-eszközökről további információt az Azure IoT SDK-kban talál.

Előfeltételek

A Visual Studióval.
Egy IoT Hub. Hozzon létre egyet a parancssori felülettel vagy az Azure Portallal.
Regisztrált eszköz. Regisztráljon egyet az Azure Portalon.
Győződjön meg arról, hogy a 8883-as port nyitva van a tűzfalon. A cikkben szereplő eszközminta MQTT protokollt használ, amely a 8883-es porton keresztül kommunikál. Ez a port néhány vállalati és oktatási hálózati környezetben blokkolható. További információkért és a probléma megoldásának módjaiért tekintse meg az IoT Hubra (MQTT) való Csatlakozás.

Az IoT Hub kapcsolati sztring lekérése

Ebben a cikkben egy háttérszolgáltatást hoz létre, amely hozzáadja a kívánt tulajdonságokat egy ikereszközhöz, majd lekérdezi az identitásjegyzéket, hogy megtalálja az összes, ennek megfelelően frissített jelentett tulajdonságokkal rendelkező eszközt. A szolgáltatásnak szüksége van a szolgáltatás csatlakoztatási engedélyére az ikereszköz kívánt tulajdonságainak módosításához, és a beállításjegyzék olvasási engedélyére van szüksége az identitásjegyzék lekérdezéséhez. Nincs olyan alapértelmezett megosztott hozzáférési szabályzat, amely csak ezt a két engedélyt tartalmazza, ezért létre kell hoznia egyet.

Ha olyan megosztott hozzáférési szabályzatot szeretne létrehozni, amely szolgáltatás-kapcsolódási és beállításjegyzék-olvasási engedélyeket biztosít, és kapcsolati sztring szeretne kapni ehhez a szabályzathoz, kövesse az alábbi lépéseket:

Az Azure Portalon válassza ki az Erőforráscsoportokat. Válassza ki azt az erőforráscsoportot, ahol a központ található, majd válassza ki a központot az erőforrások listájából.
A központ bal oldali ablaktábláján válassza a Megosztott hozzáférési szabályzatok lehetőséget.
A szabályzatok listája feletti felső menüben válassza a Megosztott házirend hozzáférési szabályzat hozzáadása lehetőséget.
A jobb oldali Megosztott hozzáférési szabályzat hozzáadása panelen adjon meg egy leíró nevet a szabályzatnak, például serviceAndRegistryRead. Az Engedélyek területen válassza a Beállításjegyzék olvasása és szolgáltatás Csatlakozás, majd a Hozzáadás lehetőséget.
Válassza ki az új szabályzatot a szabályzatok listájából.
Válassza az Elsődleges kapcsolati sztring másolás ikont, és mentse az értéket.

További információ az IoT Hub megosztott hozzáférési szabályzatairól és engedélyeiről: Hozzáférés-vezérlés és engedélyek.

Jelentett tulajdonságokat frissíteni kívánó eszközalkalmazás létrehozása

Ebben a szakaszban egy .NET-konzolalkalmazást hoz létre, amely myDeviceId azonosítóként csatlakozik a központhoz, majd frissíti annak jelentett tulajdonságait, hogy meggyőződjön arról, hogy mobilhálózattal csatlakozik.

Nyissa meg a Visual Studiót, és válassza az Új projekt létrehozása lehetőséget.
Válassza a Konzolalkalmazás (.NET-keretrendszer) lehetőséget, majd válassza a Tovább gombot.
Az új projekt konfigurálásához nevezze el a projektjelentést Csatlakozás ivity, majd válassza a Tovább lehetőséget.
A Megoldáskezelő kattintson a jobb gombbal a Jelentés Csatlakozás ivity projektre, majd válassza a NuGet-csomagok kezelése lehetőséget.
Tartsa meg az alapértelmezett .NET-keretrendszer, majd válassza a Létrehozás lehetőséget a projekt létrehozásához.
Válassza a Tallózás és keresés lehetőséget, majd válassza a Microsoft.Azure.Devices.Client lehetőséget. Válassza a Telepítés lehetőséget.

Ez a lépés letölti, telepíti és hozzáadja az Azure IoT-eszköz SDK NuGet-csomagjára és függőségeire mutató hivatkozást.

Adja hozzá a következő usingutasításokat a Program.cs fájl elejéhez:

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

Adja hozzá a Program osztályhoz a következő mezőket: Cserélje le {device connection string} azt az eszközt, kapcsolati sztring, amikor regisztrált egy eszközt az IoT Hubon:

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

Adja hozzá a Program osztályhoz a következő módszert:

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

Az ügyfélobjektum az eszköz ikereszközeivel való interakcióhoz szükséges összes metódust elérhetővé teszi az eszközről. A fent látható kód inicializálja az ügyfélobjektumot, majd lekéri az ikereszközt a myDeviceId azonosítóhoz.

Adja hozzá a Program osztályhoz a következő módszert:

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

A fenti kód frissíti a myDeviceId jelentett tulajdonságát a kapcsolati adatokkal.

Végül adja a következő sorokat a Main metódushoz:

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

A Megoldáskezelő kattintson a jobb gombbal a megoldásra, és válassza az Indítási projektek beállítása lehetőséget.
A Common Properties>Startup Projectben válassza a Több indítási projekt lehetőséget. Jelentés Csatlakozás ivitás esetén válassza a Start elemet műveletként. A módosítások mentéséhez kattintson az OK gombra .
Az alkalmazás futtatásához kattintson a jobb gombbal a Jelentés Csatlakozás ivity projektre, és válassza a Hibakeresés lehetőséget, majd indítsa el az új példányt. Látnia kell, hogy az alkalmazás lekérte az ikeradatokat, majd jelentett tulajdonságként küldi el a kapcsolatot.

Miután az eszköz jelentette a kapcsolati adatait, mindkét lekérdezésben meg kell jelennie.
Kattintson a jobb gombbal az AddTagsAndQuery projektre, és válassza az Új példány hibakeresése>lehetőséget a lekérdezések ismételt futtatásához. Ezúttal a myDeviceId-nek mindkét lekérdezési eredményben meg kell jelennie.

Szolgáltatásalkalmazás létrehozása, amely frissíti a kívánt tulajdonságokat és lekérdezi az ikerpéldányokat

Ebben a szakaszban egy .NET-konzolalkalmazást hoz létre C# használatával, amely helyadatokat ad hozzá a myDeviceId azonosítóhoz társított ikereszközhöz. Az alkalmazás lekérdezi az IoT Hubot az USA-ban található eszközökhöz, majd lekérdezi a mobilhálózati kapcsolatot jelentéssel rendelkező eszközöket.

A Visual Studióban válassza az Új > projekt fájlja > lehetőséget. Az Új projekt létrehozása területen válassza a Konzolalkalmazás (.NET-keretrendszer) lehetőséget, majd a Tovább gombot.
Az új projekt konfigurálásához nevezze el az AddTagsAndQuery projektet a Tovább gombra kattintva.
Fogadja el a .NET-keretrendszer alapértelmezett verzióját, majd válassza a Létrehozás lehetőséget a projekt létrehozásához.
A Megoldáskezelő kattintson a jobb gombbal az AddTagsAndQuery projektre, majd válassza a NuGet-csomagok kezelése lehetőséget.
Válassza a Tallózás és keresés lehetőséget, majd válassza a Microsoft.Azure.Devices lehetőséget. Válassza a Telepítés lehetőséget.

Ez a lépés letölti, telepíti és hozzáadja az Azure IoT szolgáltatás SDK NuGet-csomagjára és függőségeire mutató hivatkozást.
Adja hozzá a következő usingutasításokat a Program.cs fájl elejéhez:
```
using Microsoft.Azure.Devices;
```
Adja hozzá a Program osztályhoz a következő mezőket: Cserélje le {iot hub connection string} az IoT Hub kapcsolati sztring, amelyet az IoT Hub lekérése kapcsolati sztring másolt.
```
static RegistryManager registryManager;
static string connectionString = "{iot hub connection string}";
```
Adja hozzá a Program osztályhoz a következő módszert:
```
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)));
}
```
A RegistryManager osztály a szolgáltatás ikereszközeivel való interakcióhoz szükséges összes metódust elérhetővé teszi. Az előző kód először inicializálja a registryManager objektumot, majd lekéri az ikereszközt a myDeviceId azonosítóhoz, és végül frissíti a címkéket a kívánt helyadatokkal.

A frissítés után két lekérdezést hajt végre: az első csak a Redmond43-üzemben található eszközök ikereszközeit választja ki, a második pedig pontosítja a lekérdezést, hogy csak azokat az eszközöket válassza ki, amelyek szintén mobilhálózaton keresztül csatlakoznak.

Az előző kód, amikor létrehozza a lekérdezési objektumot, megadja a visszaadott dokumentumok maximális számát. A lekérdezési objektum egy HasMoreResults logikai tulajdonságot tartalmaz, amellyel többször is meghívhatja a GetNextAsTwinAsync metódusokat az összes eredmény lekéréséhez. A GetNextAsJson nevű metódus olyan eredményekhez érhető el, amelyek nem ikereszközök, például összesítő lekérdezések eredményei.

Végül adja a következő sorokat a Main metódushoz:

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

Az alkalmazás futtatásához kattintson a jobb gombbal az AddTagsAndQuery projektre, és válassza a Hibakeresés lehetőséget, majd indítsa el az új példányt. A lekérdezés eredményében egy eszköznek kell megjelennie, amely a Redmond43-ban található összes eszközt kéri le, a lekérdezéshez pedig egyet sem, amely az eredményeket mobilhálózatot használó eszközökre korlátozza.

Ebben a cikkben:

Eszköz metaadatai hozzáadva címkékként egy háttéralkalmazásból
Jelentett eszközkapcsolati információk az ikereszközben
Az ikereszköz adatainak lekérdezése SQL-szerű IoT Hub-lekérdezési nyelv használatával

Következő lépések

A következő tudnivalókat ismerheti meg:

Telemetriai adatok küldése az eszközökről: Rövid útmutató: Telemetriai adatok küldése IoT Plug and Play-eszközről az Azure IoT Hubba.
Eszközök konfigurálása az ikereszköz kívánt tulajdonságaival, lásd : Oktatóanyag: Eszközök konfigurálása háttérszolgáltatásból.
Az eszközök interaktív vezérlése, például egy felhasználó által vezérelt alkalmazás ventilátorának bekapcsolása, lásd : Rövid útmutató: IoT Hubhoz csatlakoztatott eszközök vezérlése.