Aan de slag met apparaatdubbels (Azure CLI)

• CLI
• .NET
• Python
• Node.js
• Java

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:

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 gesimuleerd apparaat om het connectiviteitskanaal te rapporteren als een gerapporteerde eigenschap op de apparaatdubbel.

• Query's uitvoeren op apparaten met behulp van filters op de tags en eigenschappen die eerder zijn gemaakt.

Zie de richtlijnen voor apparaat-naar-cloudcommunicatie voor meer informatie over het gebruik van gerapporteerde eigenschappen van apparaatdubbels.

In dit artikel leest u hoe u twee Azure CLI-sessies maakt:

• Een sessie waarmee een gesimuleerd apparaat wordt gemaakt. Het gesimuleerde apparaat rapporteert het connectiviteitskanaal als een gerapporteerde eigenschap op de bijbehorende apparaatdubbel van het apparaat wanneer het wordt geïnitialiseerd.

• Een sessie waarmee de tags van de apparaatdubbel voor het gesimuleerde apparaat worden bijgewerkt en vervolgens apparaten worden opgevraagd vanuit uw IoT-hub. De query's gebruiken filters op basis van de tags en eigenschappen die eerder in beide sessies zijn bijgewerkt.

Vereisten

• Azure CLI. U kunt de opdrachten in dit artikel ook uitvoeren met behulp van De Azure Cloud Shell, een interactieve CLI-shell die wordt uitgevoerd in uw browser of in een app zoals Windows Terminal. Als u de Cloud Shell gebruikt, hoeft u niets te installeren. Als u de CLI liever lokaal gebruikt, is voor dit artikel Versie 2.36 of hoger van Azure CLI vereist. Voer az --version uit om de versie te bekijken. Zie Azure CLI installeren of upgraden om Azure CLI lokaal te installeren of bij te werken.

• Een IoT-hub. Maak er een met de CLI of Azure Portal.

• Zorg ervoor dat de poort 8883 is geopend in uw firewall. In de voorbeelden in dit artikel wordt het MQTT-protocol gebruikt, dat via poort 8883 communiceert. Deze poort kan worden geblokkeerd in sommige bedrijfs- en onderwijsnetwerkomgevingen. Zie Verbinding maken met IoT Hub (MQTT) voor meer informatie en manieren om dit probleem te omzeilen.

Cloud Shell voorbereiden

Als u De Azure Cloud Shell wilt gebruiken, moet u deze eerst starten en configureren. Als u de CLI lokaal gebruikt, gaat u verder met de sectie Twee CLI-sessies voorbereiden.

1. Selecteer het Cloud Shell-pictogram in de paginakoptekst in Azure Portal.

   

   Notitie

   Als de Cloud Shell voor het eerst gebruikt, wordt u gevraagd opslag te maken. Dit is nodig om de Cloud Shell te gebruiken. Selecteer een abonnement om een opslagaccount en een Microsoft Azure Files-share te maken.

2. Gebruik de omgevingskiezer in de Cloud Shell-werkbalk om uw gewenste CLI-omgeving te selecteren. In dit artikel wordt de Bash-omgeving gebruikt. U kunt ook de PowerShell-omgeving gebruiken.

   Notitie

   Voor sommige opdrachten zijn verschillende syntaxis of opmaak vereist in de Bash- en PowerShell-omgevingen. Zie Tips voor het gebruik van de Azure CLI voor meer informatie.

   

Twee CLI-sessies voorbereiden

Vervolgens moet u twee Azure CLI-sessies voorbereiden. Als u Cloud Shell gebruikt, voert u deze sessies uit op afzonderlijke Cloud Shell-tabbladen. Als u een lokale CLI-client gebruikt, voert u afzonderlijke CLI-exemplaren uit. Gebruik de afzonderlijke CLI-sessies voor de volgende taken:

• De eerste sessie simuleert een IoT-apparaat dat communiceert met uw IoT-hub.
• De tweede sessie werkt uw gesimuleerde apparaat bij en voert een query uit op uw IoT-hub.

1. Als u Cloud Shell gebruikt, gaat u verder met de volgende stap. Voer anders de opdracht az login uit in de eerste CLI-sessie om u aan te melden bij uw Azure-account.

   Als u Cloud Shell gebruikt, wordt u automatisch aangemeld bij uw Azure-account. Alle communicatie tussen uw Azure CLI-sessie en uw IoT-hub wordt geverifieerd en versleuteld. Als gevolg hiervan heeft dit artikel geen extra verificatie nodig die u zou gebruiken met een echt apparaat, zoals een verbindingsreeks. Zie Aanmelden met Azure CLI voor meer informatie over aanmelden met Azure CLI.

   az login
   

2. Voer in de eerste CLI-sessie de opdracht az extension add uit . Met de opdracht wordt de Microsoft Azure IoT-extensie voor Azure CLI toegevoegd aan uw CLI-shell. Met de extensie worden specifieke opdrachten voor IoT Hub, IoT Edge en IoT Device Provisioning Service (DPS) toegevoegd aan Azure CLI. Nadat u de extensie hebt geïnstalleerd, hoeft u deze niet opnieuw te installeren in een Cloud Shell-sessie.

   az extension add --name azure-iot
   

   Notitie

   In dit artikel wordt gebruikgemaakt van de nieuwste versie van de Azure IoT-extensie, azure-iot. De verouderde versie heet azure-cli-iot-ext. Zorg ervoor dat er maar één versie is geïnstalleerd. U kunt de opdracht az extension list gebruiken om de momenteel geïnstalleerde extensies te valideren.

   Gebruik az extension remove --name azure-cli-iot-ext om de verouderde versie van de extensie te verwijderen.

   Gebruik az extension add --name azure-iot om de nieuwe versie van de extensie toe te voegen.

   Gebruik az extension list om te bekijken welke installaties u hebt geïnstalleerd.

3. Open de tweede CLI-sessie. Als u Cloud Shell in een browser gebruikt, selecteert u het pictogram Nieuwe sessie openen op de werkbalk van uw eerste CLI-sessie. Als u de CLI lokaal gebruikt, opent u een tweede CLI-exemplaar.

   

Een apparaat maken en simuleren

In deze sectie maakt u een apparaat-id voor uw IoT-hub in de eerste CLI-sessie en simuleert u vervolgens een apparaat met die apparaat-id. Het gesimuleerde apparaat reageert op de taken die u in de tweede CLI-sessie plant.

Zo maakt en start u een gesimuleerd apparaat:

1. Voer in de eerste CLI-sessie de opdracht az iot hub device-identity create uit, waarbij u de volgende tijdelijke aanduidingen vervangt door de bijbehorende waarden. Met deze opdracht maakt u de apparaat-id voor uw gesimuleerde apparaat.

   {DeviceName}. De naam van uw gesimuleerde apparaat.

   {HubName}. De naam van uw IoT-hub.

   az iot hub device-identity create --device-id {DeviceName} --hub-name {HubName} 
   

2. Voer in de eerste CLI-sessie de opdracht az iot device simulate uit, waarbij u de volgende tijdelijke aanduidingen vervangt door de bijbehorende waarden. Met deze opdracht wordt het apparaat gesimuleerd dat u in de vorige stap hebt gemaakt. De opdracht configureert ook het gesimuleerde apparaat om het connectiviteitskanaal te rapporteren als een gerapporteerde eigenschap op de bijbehorende apparaatdubbel van het apparaat wanneer het wordt geïnitialiseerd.

   {DeviceName}. De naam van uw gesimuleerde apparaat.

   {HubName}. De naam van uw IoT-hub.

   az iot device simulate --device-id {DeviceName} --hub-name {HubName} \
                          --init-reported-properties '{"connectivity":{"type": "cellular"}}'
   

   Tip

   De opdracht az iot device simulate verzendt standaard 100 apparaat-naar-cloud-berichten met een interval van 3 seconden tussen berichten. De simulatie eindigt nadat alle berichten zijn verzonden. Als u wilt dat de simulatie langer wordt uitgevoerd, kunt u de --msg-count parameter gebruiken om meer berichten op te geven of de --msg-interval parameter om een langer interval tussen berichten op te geven. U kunt de opdracht ook opnieuw uitvoeren om het gesimuleerde apparaat opnieuw op te starten.

De apparaatdubbel bijwerken

Zodra een apparaat-id is gemaakt, wordt impliciet een apparaatdubbel gemaakt in IoT Hub. In deze sectie gebruikt u de tweede CLI-sessie om een set tags bij te werken op de apparaatdubbel die is gekoppeld aan de apparaat-id die u in de vorige sectie hebt gemaakt. U kunt apparaatdubbeltags gebruiken om apparaten in uw IoT-oplossingen te organiseren en te beheren. Zie Apparaten beheren met behulp van apparaatdubbeltags in Azure IoT Hub voor meer informatie over het beheren van apparaten met behulp van tags.

1. Controleer of het gesimuleerde apparaat in de eerste CLI-sessie wordt uitgevoerd. Zo niet, start u deze opnieuw door de opdracht az iot device simulate opnieuw uit te voeren vanuit Create en simuleer een apparaat.

2. Voer in de tweede CLI-sessie de opdracht az iot hub device-twin update uit, waarbij u de volgende tijdelijke aanduidingen vervangt door de bijbehorende waarden. In dit voorbeeld werken we meerdere tags op de apparaatdubbel bij voor de apparaat-id die we in de vorige sectie hebben gemaakt.

   {DeviceName}. De naam van uw apparaat.

   {HubName}. De naam van uw IoT-hub.

   az iot hub device-twin update --device-id {DeviceName} --hub-name {HubName} \
                                 --tags '{"location":{"region":"US","plant":"Redmond43"}}'
   

3. Controleer in de tweede CLI-sessie of het JSON-antwoord de resultaten van de updatebewerking weergeeft. In het volgende voorbeeld van het JSON-antwoord hebben we gebruikt SampleDevice voor de {DeviceName} tijdelijke aanduiding in de az iot hub device-twin update CLI-opdracht.

   {
     "authenticationType": "sas",
     "capabilities": {
       "iotEdge": false
     },
     "cloudToDeviceMessageCount": 0,
     "connectionState": "Connected",
     "deviceEtag": "MTA2NTU1MDM2Mw==",
     "deviceId": "SampleDevice",
     "deviceScope": null,
     "etag": "AAAAAAAAAAI=",
     "lastActivityTime": "0001-01-01T00:00:00+00:00",
     "modelId": "",
     "moduleId": null,
     "parentScopes": null,
     "properties": {
       "desired": {
         "$metadata": {
           "$lastUpdated": "2023-02-21T10:40:10.5062402Z"
         },
         "$version": 1
       },
       "reported": {
         "$metadata": {
           "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
           "connectivity": {
             "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
             "type": {
               "$lastUpdated": "2023-02-21T10:40:43.8539917Z"
             }
           }
         },
         "$version": 2,
         "connectivity": {
           "type": "cellular"
         }
       }
     },
     "status": "enabled",
     "statusReason": null,
     "statusUpdateTime": "0001-01-01T00:00:00+00:00",
     "tags": {
       "location": {
         "plant": "Redmond43",
         "region": "US"
       }
     },
     "version": 4,
     "x509Thumbprint": {
       "primaryThumbprint": null,
       "secondaryThumbprint": null
     }
   }
   

Een query uitvoeren op uw IoT-hub voor apparaatdubbels

IoT Hub maakt de apparaatdubbels voor uw IoT-hub beschikbaar als een documentverzameling genaamd apparaten. In deze sectie gebruikt u de tweede CLI-sessie om twee query's uit te voeren op de set apparaatdubbels voor uw IoT-hub: de eerste query selecteert alleen de apparaatdubbels van apparaten in de Redmond43-installatie en de tweede verfijnt de query om alleen de apparaten te selecteren die ook zijn verbonden via een mobiel netwerk. Beide query's retourneren alleen de eerste 100 apparaten in de resultatenset. Zie Query's voor IoT Hub-apparaten en moduledubbels voor meer informatie over apparaatdubbels.

1. Controleer of het gesimuleerde apparaat in de eerste CLI-sessie wordt uitgevoerd. Zo niet, start u deze opnieuw door de opdracht az iot device simulate opnieuw uit te voeren vanuit Create en simuleer een apparaat.

2. Voer in de tweede CLI-sessie de opdracht az iot hub query uit , waarbij u de volgende tijdelijke aanduidingen vervangt door de bijbehorende waarden. In dit voorbeeld filteren we de query om alleen de apparaatdubbels van apparaten in de Redmond43-fabriek te retourneren.

   {HubName}. De naam van uw IoT-hub.

   az iot hub query --hub-name {HubName} \
                    --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'" \
                    --top 100
   

3. Controleer in de tweede CLI-sessie of het JSON-antwoord de resultaten van de query weergeeft.

   {
     "authenticationType": "sas",
     "capabilities": {
       "iotEdge": false
     },
     "cloudToDeviceMessageCount": 0,
     "connectionState": "Connected",
     "deviceEtag": "MTA2NTU1MDM2Mw==",
     "deviceId": "SampleDevice",
     "deviceScope": null,
     "etag": "AAAAAAAAAAI=",
     "lastActivityTime": "0001-01-01T00:00:00+00:00",
     "modelId": "",
     "moduleId": null,
     "parentScopes": null,
     "properties": {
       "desired": {
         "$metadata": {
           "$lastUpdated": "2023-02-21T10:40:10.5062402Z"
         },
         "$version": 1
       },
       "reported": {
         "$metadata": {
           "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
           "connectivity": {
             "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
             "type": {
               "$lastUpdated": "2023-02-21T10:40:43.8539917Z"
             }
           }
         },
         "$version": 2,
         "connectivity": {
           "type": "cellular"
         }
       }
     },
     "status": "enabled",
     "statusReason": null,
     "statusUpdateTime": "0001-01-01T00:00:00+00:00",
     "tags": {
       "location": {
         "plant": "Redmond43",
         "region": "US"
       }
     },
     "version": 4,
     "x509Thumbprint": {
       "primaryThumbprint": null,
       "secondaryThumbprint": null
     }
   }
   

4. Voer in de tweede CLI-sessie de opdracht az iot hub query uit , waarbij u de volgende tijdelijke aanduidingen vervangt door de bijbehorende waarden. In dit voorbeeld filteren we de query om alleen de apparaatdubbels van apparaten in de Redmond43-fabriek te retourneren die ook zijn verbonden via een mobiel netwerk.

   {HubName}. De naam van uw IoT-hub.

   az iot hub query --hub-name {HubName} \
                    --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' \
                                     AND properties.reported.connectivity.type = 'cellular'" \
                    --top 100
   

5. Controleer in de tweede CLI-sessie of het JSON-antwoord de resultaten van de query weergeeft. De resultaten van deze query moeten overeenkomen met de resultaten van de vorige query in deze sectie.

In dit artikel leert u het volgende:

• Metagegevens van apparaten toegevoegd als tags uit een Azure CLI-sessie
• Een apparaat gesimuleerd dat apparaatverbindingsgegevens in de apparaatdubbel heeft gerapporteerd
• Query's uitgevoerd op de gegevens van de apparaatdubbel, met behulp van sql-achtige IoT Hub-querytaal in een Azure CLI-sessie

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.