Share via

Kom igång med enhetstvillingar (Azure CLI)

  • Artikel

Enhetstvillingar är JSON-dokument som lagrar information om enhetstillstånd, som metadata, konfigurationer och villkor. IoT Hub bevarar en enhetstvilling för varje enhet som ansluter till den.

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.

Använd enhetstvillingar för att:

  • Lagra enhetsmetadata från lösningens serverdel.

  • Rapportera aktuell tillståndsinformation, till exempel tillgängliga funktioner och villkor, till exempel den anslutningsmetod som används, från enhetsappen.

  • Synkronisera tillståndet för långvariga arbetsflöden, till exempel inbyggd programvara och konfigurationsuppdateringar, mellan en enhetsapp och en serverdelsapp.

  • Fråga efter enhetens metadata, konfiguration eller tillstånd.

Enhetstvillingar är utformade för synkronisering och för att köra frågor mot enhetskonfigurationer och villkor. Mer information om enhetstvillingar, inklusive när du ska använda enhetstvillingar, finns i Förstå enhetstvillingar.

IoT Hubs lagrar enhetstvillingar som innehåller följande element:

  • Taggar. Enhetsmetadata är endast tillgängliga för lösningens serverdel.

  • Önskade egenskaper. JSON-objekt som kan ändras av lösningens serverdel och kan observeras av enhetsappen.

  • Rapporterade egenskaper. JSON-objekt kan ändras av enhetsappen och kan läsas av lösningens serverdel.

Taggar och egenskaper får inte innehålla matriser, men kan innehålla kapslade objekt.

Följande bild visar enhetstvillingorganisationen:

Skärmbild av ett konceptdiagram för enhetstvillingar.

Dessutom kan lösningens serverdel köra frågor mot enhetstvillingar baserat på alla ovanstående data. Mer information om enhetstvillingar finns i Förstå enhetstvillingar. Mer information om frågor finns i IoT Hub-frågespråk.

Den här artikeln visar hur du gör följande:

  • Använd en simulerad enhet för att rapportera dess anslutningskanal som en rapporterad egenskap på enhetstvillingen.

  • Fråga enheter med filter på taggarna och egenskaperna som skapades tidigare.

Mer information om hur du använder rapporterade egenskaper för enhetstvillingar finns i Vägledning för kommunikation från enhet till moln.

Den här artikeln visar hur du skapar två Azure CLI-sessioner:

  • En session som skapar en simulerad enhet. Den simulerade enheten rapporterar sin anslutningskanal som en rapporterad egenskap på enhetens motsvarande enhetstvilling när den initieras.

  • En session som uppdaterar taggarna för enhetstvillingen för den simulerade enheten och sedan frågar enheter från din IoT-hubb. Frågorna använder filter baserat på taggar och egenskaper som tidigare uppdaterats i båda sessionerna.

Förutsättningar

  • Azure CLI. Du kan också köra kommandona i den här artikeln med hjälp av Azure Cloud Shell, ett interaktivt CLI-gränssnitt som körs i webbläsaren eller i en app som Windows-terminal. Om du använder Cloud Shell behöver du inte installera något. Om du föredrar att använda CLI lokalt kräver den här artikeln Azure CLI version 2.36 eller senare. Kör az --version för att hitta versionen. Information om hur du installerar eller uppgraderar Azure CLI lokalt finns i Installera Azure CLI.

  • En IoT-hubb. Skapa en med CLI eller Azure-portalen.

  • Kontrollera att port 8883 är öppen i brandväggen. Exemplen i den här artikeln använder MQTT-protokollet, som 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 Anslut ing to IoT Hub (MQTT).

Förbereda Cloud Shell

Om du vill använda Azure Cloud Shell måste du först starta och konfigurera det. Om du använder CLI lokalt går du vidare till avsnittet Förbered två CLI-sessioner .

  1. Välj Cloud Shell-ikonen i sidhuvudet i Azure-portalen.

    Skärmbild av de globala kontrollerna från sidhuvudet i Azure-portalen och markera Cloud Shell-ikonen.

    Kommentar

    Om det är första gången du använder Cloud Shell uppmanas du att skapa lagring, vilket krävs för att använda Cloud Shell. Välj en prenumeration för att skapa ett lagringskonto och en Microsoft Azure Files-resurs.

  2. Använd miljöväljaren i Cloud Shell-verktygsfältet för att välja önskad CLI-miljö. Den här artikeln använder Bash-miljön. Du kan också använda PowerShell-miljön.

    Kommentar

    Vissa kommandon kräver olika syntax eller formatering i Bash- och PowerShell-miljöerna. Mer information finns i Tips för att använda Azure CLI.

    Skärmbild av ett Azure Cloud Shell-fönster som markerar miljöväljaren i verktygsfältet.

Förbereda två CLI-sessioner

Därefter måste du förbereda två Azure CLI-sessioner. Om du använder Cloud Shell kör du dessa sessioner på separata Cloud Shell-flikar. Om du använder en lokal CLI-klient kör du separata CLI-instanser. Använd de separata CLI-sessionerna för följande uppgifter:

  • Den första sessionen simulerar en IoT-enhet som kommunicerar med din IoT-hubb.
  • Den andra sessionen uppdaterar din simulerade enhet och frågar din IoT-hubb.

  1. Om du använder Cloud Shell går du vidare till nästa steg. Annars kör du kommandot az login i den första CLI-sessionen för att logga in på ditt Azure-konto.

    Om du använder Cloud Shell loggas du automatiskt in på ditt Azure-konto. All kommunikation mellan Azure CLI-sessionen och din IoT-hubb autentiseras och krypteras. Därför behöver den här artikeln inte extra autentisering som du använder med en riktig enhet, till exempel en anslutningssträng. Mer information om hur du loggar in med Azure CLI finns i Logga in med Azure CLI.

    az login

  2. I den första CLI-sessionen kör du kommandot az extension add . Kommandot lägger till Microsoft Azure IoT-tillägget för Azure CLI i CLI-gränssnittet. Tillägget lägger till specifika kommandon för IoT Hub, IoT Edge och IoT Device Provisioning Service (DPS) i Azure CLI. När du har installerat tillägget behöver du inte installera det igen i någon Cloud Shell-session.

    az extension add --name azure-iot

    Kommentar

    Den här artikeln använder den senaste versionen av Azure IoT-tillägget med namnet azure-iot. Den äldre versionen kallas azure-cli-iot-ext. Du bör bara ha en version installerad i taget. Du kan använda kommandot az extension list för att verifiera de tillägg som är installerade.

    Använd az extension remove --name azure-cli-iot-ext för att ta bort den äldre versionen av tillägget.

    Använd az extension add --name azure-iot för att lägga till den nya versionen av tillägget.

    Om du vill se vilka tillägg du har installerat använder du az extension list.

  3. Öppna den andra CLI-sessionen. Om du använder Cloud Shell i en webbläsare väljer du ikonen Öppna ny session i verktygsfältet för din första CLI-session. Om du använder CLI lokalt öppnar du en andra CLI-instans.

    Skärmbild av ett Azure Cloud Shell-fönster som markerar ikonen Öppna ny session i verktygsfältet.

Skapa och simulera en enhet

I det här avsnittet skapar du en enhetsidentitet för din IoT-hubb i den första CLI-sessionen och simulerar sedan en enhet med den enhetsidentiteten. Den simulerade enheten svarar på de jobb som du schemalägger i den andra CLI-sessionen.

Så här skapar och startar du en simulerad enhet:

  1. I den första CLI-sessionen kör du kommandot az iot hub device-identity create och ersätter följande platshållare med motsvarande värden. Det här kommandot skapar enhetsidentiteten för den simulerade enheten.

    {DeviceName}. Namnet på den simulerade enheten.

    {HubName}. Namnet på din IoT-hubb.

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

  2. I den första CLI-sessionen kör du kommandot az iot device simulate och ersätter följande platshållare med motsvarande värden. Det här kommandot simulerar den enhet som du skapade i föregående steg. Kommandot konfigurerar också den simulerade enheten att rapportera sin anslutningskanal som en rapporterad egenskap på enhetens motsvarande enhetstvilling när den initieras.

    {DeviceName}. Namnet på den simulerade enheten.

    {HubName}. Namnet på din IoT-hubb.

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

    Dricks

    Som standard skickar kommandot az iot device simulate 100 enhet-till-moln-meddelanden med ett intervall på 3 sekunder mellan meddelanden. Simuleringen avslutas när alla meddelanden har skickats. Om du vill att simuleringen ska köras längre kan du använda parametern --msg-count för att ange fler meddelanden eller parametern --msg-interval för att ange ett längre intervall mellan meddelanden. Du kan också köra kommandot igen för att starta om den simulerade enheten.

Uppdatera enhetstvillingen

När en enhetsidentitet har skapats skapas en enhetstvilling implicit i IoT Hub. I det här avsnittet använder du den andra CLI-sessionen för att uppdatera en uppsättning taggar på enhetstvillingen som är associerad med enhetsidentiteten som du skapade i föregående avsnitt. Du kan använda taggar för enhetstvillingar för att organisera och hantera enheter i dina IoT-lösningar. Mer information om hur du hanterar enheter med taggar finns i Hantera enheter med hjälp av enhetstvillingtaggar i Azure IoT Hub.

  1. Bekräfta att den simulerade enheten i den första CLI-sessionen körs. Annars startar du om det genom att köra kommandot az iot device simulate igen från Skapa och simulera en enhet.

  2. I den andra CLI-sessionen kör du kommandot az iot hub device-twin update och ersätter följande platshållare med motsvarande värden. I det här exemplet uppdaterar vi flera taggar på enhetstvillingen för den enhetsidentitet som vi skapade i föregående avsnitt.

    {DeviceName}. Namnet på enheten.

    {HubName}. Namnet på din IoT-hubb.

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

  3. I den andra CLI-sessionen bekräftar du att JSON-svaret visar resultatet av uppdateringsåtgärden. I följande JSON-svarsexempel använde SampleDevice vi för {DeviceName} platshållaren i az iot hub device-twin update CLI-kommandot.

    {
  "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
  }
}

Fråga din IoT-hubb efter enhetstvillingar

IoT Hub exponerar enhetstvillingarna för din IoT-hubb som en dokumentsamling som kallas enheter. I det här avsnittet använder du den andra CLI-sessionen för att köra två frågor på uppsättningen enhetstvillingar för din IoT-hubb: den första frågan väljer endast enhetstvillingar för enheter som finns i Redmond43-anläggningen och den andra förfinar frågan för att endast välja de enheter som också är anslutna via ett mobilnät. Båda frågorna returnerar endast de första 100 enheterna i resultatuppsättningen. Mer information om frågor om enhetstvillingar finns i Frågor för IoT Hub-enheter och modultvillingar.

  1. Bekräfta att den simulerade enheten i den första CLI-sessionen körs. Annars startar du om det genom att köra kommandot az iot device simulate igen från Skapa och simulera en enhet.

  2. I den andra CLI-sessionen kör du kommandot az iot hub query och ersätter följande platshållare med motsvarande värden. I det här exemplet filtrerar vi frågan för att endast returnera enhetstvillingarna för enheter som finns i Redmond43-anläggningen .

    {HubName}. Namnet på din IoT-hubb.

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

  3. I den andra CLI-sessionen bekräftar du att JSON-svaret visar resultatet av frågan.

    {
  "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. I den andra CLI-sessionen kör du kommandot az iot hub query och ersätter följande platshållare med motsvarande värden. I det här exemplet filtrerar vi frågan för att endast returnera enhetstvillingarna för enheter som finns i Redmond43-anläggningen som också är anslutna via ett mobilnät.

    {HubName}. Namnet på din IoT-hubb.

    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. I den andra CLI-sessionen bekräftar du att JSON-svaret visar resultatet av frågan. Resultatet av den här frågan bör matcha resultatet av föregående fråga i det här avsnittet.

Den här artikeln innehåller följande avsnitt:

  • Enhetsmetadata har lagts till som taggar från en Azure CLI-session
  • Simulerade en enhet som rapporterade anslutningsinformation för enheten i enhetstvillingen
  • Efterfrågade information om enhetstvillingar med sql-liknande IoT Hub-frågespråk i en Azure CLI-session

Nästa steg

Om du vill ta reda på hur du: